Widget Templates

Using a widget template

Widget templates allow you to design widgets with pre-determined settings and formatting from a template. Create your own templates and then use them with the steps below.

LiveWhale 1.7.1+

When creating a widget in LiveWhale 1.7.1, the first option after you choose your widget type (if any usable templates exist) will be to select a template. It will use a “default” template to start, if one exists.

Choosing a widget template

Once you’ve chosen a template, you can still edit any settings from the template in the widget editor by clicking “Modify setting,” and your changes will override those set in the template.

Overriding settings from a widget template

If you need to disable any settings from the template, click “Modify settings” near the top, and you can then check/uncheck any settings coming from the template on a per-widget basis.

Disabling settings from a widget template

LiveWhale 1.7

When creating a widget in LiveWhale 1.7, the last option in the settings list (if any usable templates exist) will be “Import widget args from template.”

Once you’ve chosen a template, you can no longer edit any settings from the template in the widget editor (they will be hidden). However, you can still override them on a webpage using inline arguments (in LiveWhale) or data-options (in LiveWhale Calendar).

Adding your own widget templates

You may have certain widget settings (like a formatting style) that you want to re-use over many different widgets. Starting in LiveWhale 1.7 you can separate certain arguments into a widget template that’s saved in your _ingredients folder. That way, you can have any number of widgets reference that template, and when the template is updated, those widgets will inherit those changes automatically.

LiveWhale will scan _ingredients/templates/widgets/ for any XML files matching the format [widget type].[short name].xml. It will then parse those for a title that will be shown in the widget editor for that type, and any number of arguments (args) that will be applied when you choose that template.

Example templates:

_ingredients/templates/widgets/events.my-test-template.xml

1
2
3
4
5
6
<widget type="template">
<title>My Test Event Template</title>
<args>
<arg id="format">{title}</arg>
</args>
</widget>

_ingredients/templates/widgets/news.featured-story.xml

1
2
3
4
5
6
7
8
<widget type="template">
<title>Featured Story Format</title>
<args>
<arg id="format"><h2>{headline}</h2>{summary}</arg>
<arg id="class">featured-news</arg>
<arg id="max">3</arg>
</args>
</widget>

Adding a widget template inline

Most widget templates will probably be applied to saved widgets. However, you can apply a widget template inline if you need.

To apply the template _ingredients/templates/widgets/news.featured-story.xml, you’d use the short name “featured-story” in the inline argument:

1
2
3
<widget type="news">
<arg id="widget_template">featured-story</arg>
</widget>