Custom Fields

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

In 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/private.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 livewhale/client/private.config.php file via SFTP to add a custom field (LiveWhale 1.7+).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
$_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'=>'',
]
]
];
Argument Description Examples
header Title of field 'header'=>'My Field',
name Name of field (no 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',

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 private.config.php, the display variable is named custom_registration_link.

There is one exception for custom fields on the group editor. These 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" />.

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.