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 “Base this widget on a template.”

Once you’ve chosen a template, you can still edit any settings from the template in the widget editor, and your changes will override those set in the template. If you need to disable any settings from the template, click “Modify settings” and you can then check/uncheck any settings coming from the template on a per-widget basis.

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>