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.

Parameter Description
pagetitle Required. The name of the page
content HTML formatted content for the body of the page. This must be formatted using SetSeed compatible HTML. Use bpe_to_html on a plaintext field to generate.
live Either 1 or 0 (default). Sets the page's initial live status.
dm_template id of the primary design mode template the page should use. If creating an 'inner page' leave blank and populate the 'widget_template' value instead.
widget_template Enter the widget template name to create an inner page for an index template layer app.
userid Id of the current logged in user to associate as the creator/owner of the page.
tagids CSV separated list of tag ids to be applied to the new page.
meta_@@@ List of parameters starting with meta_ and then the matching meta name to populate defined meta data fields for inner templates. For example 'meta_date'.
locked Either 1 or 0 (default). If set to 1 the page will prevent editing of its contents in the CMS.

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.

Parameter Description
id The ID of the page to edit.
live Set the page's live status (1 or 0).
pagetitle The name of the page. Omit to leave the value unchanged.
content HTML formatted content for the body of the page. This must be formatted using SetSeed compatible HTML. Use bpe_to_html on a plaintext field to generate. Omit to leave the content unchanged.
meta_@@@ List of parameters starting with meta_ and then the matching meta name to populate defined meta data fields for inner templates. For example 'meta_date'. Only supplied values are changed.

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.

Parameter Description
pageid The ID of the page to attach the child data to.
userid Optional. The user ID to represent the owner of this page child data item.
data An array of key-value pairs of data to attach to the child data object.
more_data_@@@ Additional data items can be supplied using this format where you can't add to the main array above. i.e to add a key value pair where there key is 'date', you could supply more_data_date="2019-12-05".
type Required. The type of child data. Each kind of child data in the system needs a unique name supplied for its type. i.e blog comments using the default theme's blog widget use 'blogcomment' as the type.
activity_name If 'show_in_activity' is set to 1, you can set the visible name for this item in the Activity feed. For example, blog comments use 'Blog comment' as the value for this.
show_in_activity Required. 0 or 1. Use 1 to show an item in the Activity feed a new item is created.

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.

Parameter Description
id The ID of the page child data item to be edited.
checkowner If set and a valid User id, the function will only edit the child data item if its owner matches this value.
data As in 'add_page_child_data'
more_data_@@@ As in 'add_page_child_data'

get_page_child_data

Use this function retrieve page child data for a page.

Parameter Description
type Optional. Restrict results by the supplied 'type' of page child data.
userid Optional. If supplied will only return page child data that is owned/created by the userid.
pageid Required. ID of the page to retrieve child data form.
assign Optional. If supplied resulting data will be assigned to a Smarty variable of this name. Default is {$page_child_data}
use_as_key Optional. If supplied will add the child data item's value for this property name as the keys for output array. Values should be suitable for use as array keys, i.e numbers of simple strings.
reverse Optional. Reverses the output array.

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.

Parameter Description
userid If the original page child data item had its 'owner' set, that value needs to be supplied here for the deletion to take place. If the original item had no owner specified then this parameter can be omitted or set to 0.
pageid The ID of the page that the page child data item belongs to.
type If specified, the function will remove all child data items of this type that belong to 'pageid'.
page_child_dataid If 'type' is not specified, the function will expect this value to be populated with the id of the page child data item to be removed.

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.

Parameter Description
pageid The ID of the page to attach the child data to.
userid Optional. The user ID to represent the owner of this page child data item.
files The post name used to access the $_FILES array within PHP. For example, if your template includes inputs named like this <input type="file" name="attachments[]" value="" id="file1"> <input type="file" name="attachments[]" value="" id="file2"> you would name this property 'attachments'.
type As in 'add_page_child_data'.
activity_name As in 'add_page_child_data'.
show_in_activity As in 'add_page_child_data'.

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.

Parameter Description
pageid The ID of the page that the page child data item belongs to.
keep_@@@ Required. This parameter should always be set even if it is empty as the varied portion of it is used as the 'type' value. For example, to remove all uploads with the type of 'attachments' you would supply this parameter as keep_attachments and then its value would be an array of ids of items to keep. If the array is empty, all the 'attachments' items belonging to the 'pageid' will be removed.
owner If the original page child data item had its 'owner' set, that value needs to be supplied here for the deletion to take place. If the original item had no owner specified then this parameter needs to be set to 0.

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.

Parameters Description
slug The string of the URL portion for the page name.
thispage When a template is using this function to retrieve an 'inner' page, it is recommended to include the parent page id in this property.
assign The name of a Smarty variable to assign the output of this function to.

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.

Parameters Description
ids Comma separated list of page ids to retrieve.
menu_root_tag Optional. The menu root tag id to use to obtain the full URL if the pages are based on a drop-down menu hierarchy.
assign The name of a Smarty variable to assign the output of this function to.

Output:

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

Property Description
pagetitle The title of the page.
meta An array of the meta properties of the page.
page_child_data An array of page child data types. i.e use like this: {foreach from=$page.page_child_data.blogcomments item=comment}...{/foreach}
tags_csv Comma separated list of tag ids belonging to this page.
tags_array Array of the tags added to this page.
full_url Full URL for the page. Only included if 'menu_root_tag' was specified with the original function call.
url_str The URL string for this page (i.e just based on the page name).
pic_url URL for the first image used on this page. Use for thumbnails or indexes.

pages_by_tag

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

Parameters Description
start Optional. Numerical offset to start the returned set of results from.
limit Optional. Limit the number of results.
sortbymeta Optional. Name of a meta property to sort the lists by. For example if your pages have a date meta property set, you could use sortbymeta=date in the function call to use the value of that property to sort the results.
onlyhistorical Optional. Works with 'sortbymeta' if the value of the 'sortbymeta' option is a date. If set to true', will only include items where the date is in the past.
sortbyname Optional. Only applicable if 'sortbymeta' is not used. If set to true, the results will be sorted by the page name.
filter_meta_@@@ Optional. Use the value of a meta property to filter the returned set of pages. For example, to only include pages that have a meta property called 'paid' and a value of '1' you'd add filter_meta_paid=1 to the function call.
filter_array_meta Optional. Array based version of above. Array keys are the meta property names to filter by.
direction Use values ASC or DESC to set the sorting direction of results.
omit Optional. Comma separated list of tags used as negative match on results. For example if you include a tag id of 4 in this parameter, any page that has the tag with id 4 will be excluded from the results.
tags Required. The main comma separated list of tags to use to find pages.
additional_tags Optional. Additional additive list of tags to use for finding pages. When this is set, only pages that contain at least one tag from the list in 'tags' and at least one tag from this list will be included.
root_tag Optional. Improve accuracy of the full url link generation by specifying a root tag to use for the menu tree calculation.
inner Default=true. Set to false to return pages that are normal template based pages and not 'inner' templates.
fullcontent Default=false. Set to true to return the full page content for each the returned pages. Only use on smaller sets and if required. Output can be accessed via $item.content in the results loop.
thispage Optional. Improve accuracy when finding pages by specifying the id of the page containing the widget instance.
assign Smarty variable to assign the array of returned pages to.

User Functions

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.

Parameters Description
userid Required. The ID of the user to add the avatar image to.
file HTML post variable for a file input from a form submission.

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}

Parameters Description
var The name of the user custom field to search.
value The value to match the user custom field defined in 'var'.

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}

Parameter Description
userid Required. Id of the user to retrieve.

add_user_child_data

Inserts a new user child data record.

Parameters Description
userid Required. User ID for the ‘owner’ of the user child data.
data An array of key-value pairs of data to attach to the user child data object.
more_data Additional data items can be supplied using this format where you can't add to the main array above. i.e to add a key value pair where there key is 'date', you could supply more_data_date="2019-12-05".
type Required. The type of user child data. Each kind of child data in the system needs a unique name supplied for its type.
show_in_activity As in 'add_page_child_data'.
activity_name As in 'add_page_child_data'.

get_user_child_data

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

Parameter Description
userid Required. The User ID of the user to use.
type If supplied, limits the returned results to only items that match the type given.
assign If supplied, the output array will be assigned to an array of this name. Otherwise 'user_child_data' will contain the most recently output result.

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.

Parameters Description
userid Required. The User ID to attach the custom field value to.
id Optional. If supplied, the ID of an existing custom data field to update.
name The name of the custom field. Only needed if ID is not supplied.
value The new value of the custom field.

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.

Parameter Description
userid Required. The id of the user to retrieve custom values field values for.

delete_user_child_data

Delete a user child data item.

Parameters Description
userid Required. The User ID for the user who created the child data item.
id Required if 'type' is not supplied. The ID for the user child data item to remove.
type Required if 'id' not supplied. Delete all items of this type belonging to the supplied userid.

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.

Parameters Description
pageid Numerical ID of the email page (selected from Compose emails) to use for the email content. This can be obtained by allowing the CMS user to select a page for a widget property of type ‘choose_email’.
sendid A unique reference for this email. This is used to prevent duplicate sending so it’s useful to incorporate some kind of instance ID into this value.
email The email address to send the message to.
name The recipient’s name.
send_plus Used to set the time to send the email. Use this value to set a date in the future from a value like “+ 1 week”. Omit both this and send_date to send immediately.
send_date Use this instead of date_plus, if you are entering an explicit date and time string. Omit both this and send_plus to send immediately.
subject Subject of the email.

Returns:

Returns the campaign ID associated with the email. You can save this for use with email_cancel if needed.

email_cancel

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

Parameters Description
campaign_id Numeric ID of the campaign to cancel.

Event Functions

add_event

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

Parameter Description
title Required. Title for the event
date Required. Date for the event. Will be parsed using PHP strtotime.
link Optional. A link for the event.
summary Optional. Summary for the event.
belongs_to_category Required. Numerical id of the calendar to add the event to. Usually populated from a 'calendar_list' meta_data menu value.
location Optional. Location for the event.
time Optional. Time for the event.
duration Optional. Duration for the event.
repeat Optional. Repeat string for the event. Optional values are: "daily", "weekly", "monthly" or "yearly".
repeat_end Optional. If set, stops events repeating after this date. Date will be parsed by PHP strtotime.

delete_event

Deletes an event.

Parameter Description
id ID of the 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.

Parameters Description
instance_id This instance ID of the widget to add the meta value to.
name The widget meta property name. (Taken from the ‘var’ value of the meta item definition in the widget configuration).
value The value to save.

get_widget_meta

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

Parameter Description
widget_id Required. Id of the widget instance to retrieve meta dat for.
assign Optional. If included outputs the resulting array to a Smarty variable of this name. Default is {$widget_metadata}

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.

Parameter Description
name Name of the product
price Price of the product
currency currency code for the product. This will set the basket to this currency if it is the first one added.
quantity Quantity of the item to add.

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.

Search