Widget API Reference

Page Functions

add_page

This inserts a page into the CMS. It can be used to create a normal page or an 'inner' page.

Output:

{$incomplete} is set to true if some required values are not supplied.

{$exists} is set to true if the page already exists.

{$added} is set to the id of the new page if successfully added.

edit_page

Use this function to make changes to an existing page.

Output:

{$pagenameinuse} will be set to true if the new page name already exists.

{$edited} will be set to true if the page was successfully edited.

page_metadata

Ads metadata to a page.

add_page_child_data

Use this function to add a new page child data item to a page. Things like blog or forum comments are stored this way for example.

Here's an example from the Blog widget included with the Design Mode theme:

{add_page_child_data
 pageid=$page.id 
 userid=$content.logged_in_user.id
 data=$smarty.post.data
 more_data_approved=$approved
 show_in_activity=1
 activity_name="Blog comment"
 type="blogcomment"}

Output:

{$child_data_added} will be set to the id of the adding item if successfully added. This can be used as a key for associating other data types with a master item.

{$child_data_exists} will be set to true if the item already exists.

edit_page_child_data

Use this function to make changes to a specific page child data item.

get_page_child_data

Use this function retrieve page child data for a page.

delete_page_child_data

Use this function to remove a single page child data item using its id, or remove all items of a certain type that belong to a given page.

add_page_child_data_uploads

Use this function to store uploaded files as page child data items. For example the built in Forum widget lets users add images and files as attachments when they create a new page.

Here's an example showing how this function is used in the Forum widget that comes with the Design Mode theme.

{add_page_child_data_uploads
 pageid=$page.id
 type="attachments"
 files="attachments"
 show_in_activity=0
 userid=$content.logged_in_user.id
}

delete_all_page_child_data_uploads

Use this function to remove all uploads of a certain type for a given page. Use the keep_@@@ parameter to only delete certain items.

Here's an example from the Forum template:

{delete_all_page_child_data_uploads
 pageid=$page.id
 keep_attachments=$smarty.post.keep_attachments
 owner=$content.logged_in_user.id
}

page_by_slug

This function allows you to retrieve the full data of a page from the url portion of the page (slug).

The main use of this function is to work with Widget Sub Pages in complex Index Widgets.

Example:

{assign var=slug value="my-example-page-name"}
{page_by_slug slug=$slug assign=pagecontent}
<h1>{$pagecontent.pagetitle}</h1>

pages_by_id

Used to obtain a list of pages from their ids.

Output:

An array of pages. Each page has this set of array properties:

pages_by_tag

A very powerful function used to return lists of pages based on tags.

add_page_search_data

Populate the search index with text that isn’t generated via the CMS editor. For example you might have a widget that populates the page with content pulled via another API. To get that page to be returned in search results that match words from that text you need to populate the search index with that content.

User Functions

users_from_lists

Retrieves all users belonging to one or more users lists. Users will be returned in an array names {$users} with the following keys: name, email, id, avatar

add_user_avatar

This function can be used to add or replace an avatar image for a user. Currently used by the User Control Bar widget in design mode theme.

get_user_from_custom

Use this function to retrieve a user based on a custom field name and value. Only returns a single user so a unique value should be used. Outputs three Smarty variables: {$user_name}, {$user_email} and {$user_id}

get_user_from_id

Use this function to retrieve a user based on the supplied user id. Outputs two Smarty variables: {$user_name} and {$user_email}

add_user_child_data

Inserts a new user child data record.

get_user_child_data

Get a list of child data items associated with a user.

add_user_custom_fields

Add or update a value for a custom field to a user. If the custom field name doesn't exist, it will be created.

get_user_custom_fields

Retrieve custom field values for a user. Returns an array assigned to the Smarty variable {$user_custom_fields}. Array keys are the id of each custom field id. Each item is an array with these property names: name, value. 'name' is the custom field name itself and the value is the supplied user's value for that custom field.

delete_user_child_data

Delete a user child data item.

Email Functions

email_send

Use this function to send an email to an address based on the contents of an email created in the CMS Compose area.

Returns:

Returns the campaign ID associated with the email. You can save this for use with email_cancel if needed. This value is available in the {$campaign_id} variable.

email_cancel

Cancel an email that has been scheduled for sending at a later date.

Event Functions

add_event

Adds a new event to a calendar. Returns the ID of the event, assigned to a variable: {$added}

delete_event

Deletes an event.

Modifiers

bpe_to_html

A quick modifyer to convert plain text with SetSeed-style shortcode formatting to full HTML. This is good for allowing custom chunks of content to be saved into a page content using a page injector.

images_to_json

This modifier is used to take a block of HTML content that includes images and convert it to a json encoded array of image paths. This can be used for any purpose but the Design Mode theme uses it with the Backstretch plugin on some widgets. See the Banner.tpl widget for an example.

General Functions

add_widget_meta

Adds a widget meta value to an instance of a widget.

get_widget_meta

Gets meta data for a widget based on the supplied id. Returns an array with meta names as keys.

flush_cache

Call this function to clear the template cache for the site. Useful when your template layer app or widget has changed something that is reflected on the site.

redirect

Call this function with a parameter name of location to redirect the page when the code is executed. Useful when building apps that change some properties that need to reflected in the same page.

add_to_basket

Call this function to add a product to the user's shopping basket. This can be used for any kind of custom product outside the built-in products system. For example it is how we built the included Unleashed product integration.