Docs

Widget JSON Configuration

When you add a new Widget, you can configure it with a block of JSON code at the top of the file.

For example, lets look at the Banner.tpl file included in the Design Mode theme:

{* @@@
{
        "widget_info":{
                "title":"Banner"
                ,"title_info":"Enter a name for this instance of the banner widget."
                ,"category":"media" 
        },
        "meta_data":[{
                "name":"Text position"
                ,"type": "dropdown"
                ,"var": "position"
                ,"default":"middle"
                ,"options":[
                        {
                                "label":"Top"
                                ,"value":"top"
                        },
                        {
                                "label":"Middle"
                                ,"value":"middle"
                        },
                        {
                                "label":"Bottom"
                                ,"value":"bottom"
                        }
                ]
        }],
        "inner_templates":{
        }
}
@@@ *}
{*
{$editable.background_image}
*}
<div class="banner-feature inverted" data-backgrounds="{$editable.background_image|images_to_json:true|htmlspecialchars}">
        <div class="banner-feature-inner banner-feature-content-{$metadata.position}">
                <div class="banner-feature-content">
                        {$editable.content}
                </div>
        </div>
</div>

You can see we have two delimiter lines to identify where the JSON code fits in the file:

{* @@@ 
... 
@@@ *}

After this area of code we have the HTML and Smarty syntax that generates the widget output.

JSON Structure

The structure of the JSON configuration object:

widget_info

An object with these properties:

title: The visible name of the widget.
title_info: More information on the widget that is presented to the user when they enter the name for an instance of the widget.
category: A category to include the widget in to aid its discoverability in the CMS insert palette. Options are: text, media, products, features, columns, forms, setup.
works_in_email: Optional. If omitted or false, the widget will only work on webpages and won't be available to add to emails in the Compose section. If 'true' the widget will only show for emails won't be available for webpages. If set to "both" the widget will be available for both emails and webpages.
head_append: Optional: Add a value here to be included in the head of any page including the widget. Useful for including third party javascript libraries.

meta_data

An array of objects for each property definition for the widget. Each one will show up as an editable property when the CMS user views the properties menu for the widget instance. The values they enter are available in the Smarty template file.

Properties of each item in the array:

name: The visible lable for the property that shows to the CMS user.
type: The type of the property. This denotes what kind of information and how it's entered by the CMS user. Options are:

text	Allows any text string to be entered.
tick	Shows as a simple on/off tick box. Value will equate to true of false when working with the value in the Smarty template file.
dropdown	Displays a set of options that the user can choose from. Only one can be selected.
hidden	Used for storing custom values in. The property won't be visible or editable by the CMS user.
pagetagmulti	Displays the list of page tags set up in the system. Any number can be selected. The value is returned in the Smarty template file as a CSV separated list of tag ids.
link	Displays the link chooser dialogue to let the CMS user choose a page or file to link to or enter any third party link.
user_list	Displays the list of Users lists. Useful for creating widgets that add users to a certain User list.
choose_email	Displays a list of emails created in Compose. Used to let the CMS user choose an email that can be sent from the template using the 'send_email' API function.
linkpageonly	Displays the link editor with only the shortcut to choose a webpage. The file chooser shortcut is hidden.
image	Displays the Storage image chooser to select a single image.
imagestyle	Displays the list of image styles for the current theme - including the theme_merge collection.
imagesize	Displays the list of image size and crop presets for the current theme, including the theme_merge list.
calendar_list	Lets the user choose from all the calendars in the system.
imagesize_email	Uses the size/crop presets designed for email templates. Will merge with theme_merge version of the image_sizes_email.json
imagestyle_email	Uses the email version of the advanced image styles. Merges with theme_merge version of advanced_image_styles_email.json
video	Displays the Storage video chooser to select a single video.
quickaddtag	Allows a tag to be created automatically. Use just after a pagetagmulti item for the button to be automatically added inside the previous tag dropdown menu.
imagetagmulti	Displays the list of storage tags set up in the system. Any number can be selected. The value is returned in the Smarty template file as a CSV separated list of tag ids. This will always be displayed with the Quick Add option.

var: The variable name used to reference the property in the Smarty template. Used as an array key for the $metadata variable. For example if you defined a property with the var value of 'myproperty' you'd access it in the Smarty template file with {$metadata.myproperty}

Important: there is a reserved variable name that's used only for Index Widgets which is tagids - only use that to store the primary tag ids for an Index Widget.

default: A default value for the property.

options: Only required when 'type' is set to 'dropdown'. An array of objects with these properties each:
label: The visible lable that the CMS user chooses.
value: the internal value string for the property when the item is selected.

destvar Required only if 'type' is 'quickaddtag'. The value of this should be the 'var' value of a 'pagetagmulti' item. The tag that gets created from the quick add button will also be applied to the 'pagetagmulti' var value.

onlyone Required if 'type' is 'quickaddtag'. If true, the quick add button will grey out once there is one tag set in the 'destvar' item's value.

needsparent Optional only if 'type' is 'quickaddtag'. If this is set to true, the first tag added via the button will be nested below a new tag automatically created based on the widget instance's name followed by the text in the 'parent_tag_append' value.

parent_tag_append Required if 'needsparent' is true. Seed 'needsparent' for information.

inner_templates

With simple widgets this should just be set to an empty object. Learn more about using the inner_templates system when creating Index Widgets.

HTML Smarty Template

The code that follows the delimited JSON configuration area is the rest of the Smarty template area.

In the above example we see some code inside a Smarty comment:

{*
{$editable.background_image}
*}

This is actually important in this particular template. Whenever a variable is listed like {$editable.some_name} the name is picked up and becomes and editable zone of the widget when it's placed on a page. This means the CMS user can add in any kind of rich content into that area and it can be accessed in the template using the variable.

However, in the case of this example widget, the {$editable.background_image} variable is never actually used without a modifier (images_to_json). This means the system wouldn't be able to detect it in the template. That's why we show it surrounded by the curly brackets inside the Smarty comment. This lets the system detect it but the Smarty template doesn't actually output it to the page.

Below this we can see some HTML with some Smarty variables included. Notice how we access the value of the widget property for the 'position' dropdown item with {$metadata.position}.