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).

Argument Description Examples
header Title of field 'header'=>'My Field',
name Name of field (alphanumeric and underscores only; no dashes or spaces) 'name'=>'my_field',
instruction Note to appear beneath the field in the editor (optional) 'instruction'=>'Enter your info here.',
content_type string or array of content type(s), optionally specifying type id(s) 'content_type'=>'events',
'content_type'=>['events','news'],
'content_type'=>['profiles'=>[3,4]],
'content_type'=>['news','blurbs'=>2],
type Type of field (accepted values: text, textarea, select, radio, or checkbox) 'type'=>'text',
options Array of options for select/radio/checkbox 'options'=>['A', 'B', 'C', 'D'],
wysiwyg Allow rich-text WYSIWYG editor for textarea type?
true for full options
"limited“ for bold/italics/underline/links
false for plain text
'wysiwyg'=>true,
'wysiwyg'=>"limited",
'wysiwyg'=>false,
default Placeholder text for text fields, and pre-selected (default) options for radio/select/checkboxes). 'default'=>'https://',
'default'=>['A', 'B'],
is_required Make field required (default: false) 'is_required'=>false,
show_filter Allow filtering by this field in the back-end (only for select, check, and radio fields) 'show_filter'=>true,
place_before
place_after
Where in the editor you’d like the new field to appear. 'place_before'=>'cost',
'place_after'=>'tags',
meta_name When configured for news/profiles/blurbs, the first 160 characters (shortened with … if need be) of this custom field value will be used as the <meta name="{meta_name}" content="{custom field value}"/> value on those details pages 'meta_name'=>'description',
is_details LiveWhale 2.9.1 and later: Enabling this setting makes your custom field part of the “details” of your content. This means:
• The field is hidden from the editor for shared/linked copies
• The field is hidden from the editor when you click “link to another site for information”
• The field doesn’t check for is_required in the above two cases
• And finally, when the field is filled in, it will generate a news/event details link for that item, even if otherwise there would be no details to show.
'is_details'=>true,

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.