Custom Fields may be added to profiles and forms using the LiveWhale interface, and to Event RSVP forms using the config files.
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.
$_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 (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',
|
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
$_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',
]
]
];
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 forcontact_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”) forsecondary_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.)
{[ 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:
{<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:
<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 format when you want to use it inside another HTML tag.
<xphp content="true">
<if var="details_custom_registration_link"/>
<content>
<div class="registration_button">
<a href="">Register</a>
</div>
</content>
</xphp>