Custom Fields

Custom Fields may be added to profiles and forms using the LiveWhale interface, and to Event RSVP forms using the config files.

Since LiveWhale 1.7, you can easily add custom fields to any content type (Events, News Stories, Blurbs, etc.) using a simple configuration option in your client/global.config.php file.

Much like custom RSVP fields, the CUSTOM_FIELDS setting lets you add fields to every group (“global”), or you can add fields to an individual group by using the group id (example below).

Adding a Custom Field to the Back-end

Add the following code to your client configuration via SFTP to add a custom field.

• In LiveWhale 2.0+, this can be in a separate file at livewhale/client/custom_fields.config.php. This is our current best practice, to keep custom fields organized separately from your other configurations.
• In Livewhale 1.7+, this can be stored in livewhale/client/global.config.php (or, in rare cases, livewhale/client/private.config.php).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

$_LW->CONFIG['CUSTOM_FIELDS']=[ // custom fields to apply to backend editors
	'global'=>[
		[
			'header'=>'Registration Link',
			'name'=>'registration_link',
			'instruction'=>'Paste a link to show a "Register" button.',
			'content_type'=>'events',
			'type'=>'text',
			//'options'=>['A', 'B', 'C', 'D'],
			// 'wysiwyg'=>false,
			'default'=>'https://',
			'is_required'=>false,
			'place_before'=>'cost',
			// 'place_after'=>'',
			// 'is_details'=>false
		]
	]
];

Note: There is no difference in functionality depending where you place the configuration code, but we suggest making sure you only save $_LW->CONFIG['CUSTOM_FIELDS'] in one of the two locations (e.g., it could cause confusion to define it in global.config.php and then re-define it in custom_fields.config.php).

Note: For place_before and place_after, accepted values include title, summary, description, metadata, tags, location, related_content, contact_info, sharing, visibility, date_time, categories, cost, or any other criteria you can see in the page source as <!-- START NAME_OF_FIELD -->.

Example: Add custom field(s) to a particular group

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

$_LW->CONFIG['CUSTOM_FIELDS']=[ 
	'global'=>[ // This field appears in all groups
		[
			'header'=>'Registration Link',
			'name'=>'registration_link',
			'content_type'=>'events',
			'type'=>'text',
			'place_before'=>'cost',
		]
	],
	'123'=>[ // These fields appear only in the group with id = 123
		[
			'header'=>'My Field 1',
			'name'=>'field1',
			'content_type'=>['news','events'],
			'type'=>'textarea',
			'place_after'=>'tags',
		],
		[
			'header'=>'My Field 2',
			'name'=>'field2',
			'content_type'=>['blurbs'=>[3]],
			'type'=>'radio',
			'options'=>['A', 'B', 'C'],
			'place_before'=>'location',
		]
	]
];

Setting custom value/label pairs (LiveWhale 1.7.1+)

By default, you only need to supply labels in your 'options'=> array, and LiveWhale will generate and handle the associated form values. However, if you’re doing any custom work (form handling, filtering via URLs, etc.), you may prefer to customize those values. To do so, set 'options'=> as an associative array.

1
2
3
4
5

'options'=>[
	'Value 1'=>'This is label 1',
	'Value 2'=>'This is label 2',
	'Value 3'=>'This is label 3'
],

When setting values on a custom field:

• You must set them for all labels.
• You may not use values 0 or -1, these are reserved by the CMS.

Displaying a Custom Field

To display custom fields on the front-end, you’ll need to add them to a details template or calendar component.

Note: All custom fields get preceded by custom_ or details_custom_ when displaying on the front-end. So, if you set your field name to “registration_link” in global.config.php, the display variable is named custom_registration_link.

There are exceptions for:

• Custom fields on the group editor get prefixed with custom_group_. So, if you have a group setting for contact_info, you’d display it on the front end with <xphp var="custom_group_contact_info" />.
• Custom fields on Edit Page Details get prefixed with custom_page_. So, if you have a page setting (content_type=”pages”) for secondary_title, you’d display it on the front end with <xphp var="custom_page_secondary_title" />.

On the Calendar

To show a custom field on an event page in your calendar, edit the calendar component lw_cal_event_detail.html via SFTP to add your custom field. (Or, on an older setup, this might be in calendar.html in your theme.)

1
2
3
4
5

{[ if (obj.custom_registration_link) { ]}
  <div class="registration_button">
  	<a href="{{ custom_registration_link }}">Register</a>
  </div>
{[ } ]}

In a Widget

To show a custom field in a widget, add the variable {custom_registration_link} to the format argument. You can also use conditional formatting to format it only when it has a value:

1

{<div class="registration_button"><a href="|custom_registration_link|">Register</a></div>}

On a Details Page

To show a custom field on a news, event, profile, gallery, form, or blurb detail page, add its XPHP variable (prefixed with details_custom_) to the associated details page template via SFTP.

You can also use XPHP logic to format it only when it has a value:

1
2
3
4
5
6
7
8

<xphp content="true">
	<if var="details_custom_my_message"/>
	<content>
		<div class="message">
			<xphp var="details_custom_my_message"/>
		</div>
	</content>
</xphp>

Or, use the %%xphp_variable_name%% format when you want to use it inside another HTML tag.

1
2
3
4
5
6
7
8

<xphp content="true">
	<if var="details_custom_registration_link"/>
	<content>
		<div class="registration_button">
			<a href="%%xphp_details_custom_registration_link%%">Register</a>
		</div>
	</content>
</xphp>

Note: Custom fields are currently not supported on non-details Pages in LiveWhale 1.7 without a custom module. This is roadmapped for a future version of LiveWhale, please contact support with any questions.