Help:Widget syntax

Widget page syntax

The Widgets extension uses the Smarty PHP templating engine to provide simple templating functionality within widget pages. All parameters passed to a widget are converted into Smarty parameters.

Important: Use escape modifiers on all passed-in parameters to prevent users from passing in raw HTML from normal wiki pages. Failure to protect against this will expose the hosting site to XSS (and other) attacks.

Arrays

If you use the same parameter multiple times, the widget will get an array of values. You can use foreach to go through the array.

Booleans (true/false)

Since version 0.8.5, this extension supports passing boolean parameters by just using a parameter name without a value, like this:

{{#widget:WidgetName|popup}}

This will set $popup to true for your widget. Also, in addition to PHP's default handling of boolean conversions, you can use value "false" to set the boolean value false (this is not the case in PHP as string "false" doesn't get converted to a boolean false; see PHP docs on boolean casting).

{{#widget:WidgetName|popup=false}}

Dotted notation

Parameter names can have dots, and Smarty will interpret them as associative arrays, so you can use foreach with both key and item attributes to traverse through them, or you can just use the same name with dots if you want to reference the parameter directly.

Validate modifier

In addition to standard Smarty modifiers (like the heavily used escape), the Widgets extension implements the validate modifier, that uses PHP Data filtering to allow for validating widget parameters.

To make sure the $homepage variable value is a valid URL, you can use following code:

<a href="<!--{$homepage|validate:url}-->">Homepage</a>

The following values for the validate are supported (mapping to PHP's validation filters):

• url (FILTER_VALIDATE_URL)
• int (FILTER_VALIDATE_INT)
• boolean (FILTER_VALIDATE_BOOLEAN)
• float (FILTER_VALIDATE_FLOAT)
• email (FILTER_VALIDATE_EMAIL)
• ip (FILTER_VALIDATE_IP)

Refreshing a widget page

If you're using a call to the widget within the widget page itself, then you will not see the updated widget (and no widget at all when you just created a page). This happens because the page contents are not available to the Widgets extension until a page is saved, but the call to the {{#widget}} parser function is made before the page is saved. After the page is saved, it's cached by MediaWiki, so you won't see the result even if you reload the page via the browser. To make the latest edits to the widget code appear, you need to refresh the page in the cache; to do this, you just need to use the purge action (see also Purge extension), or wait a certain amount of time (up to 24 hours).

Widgets and ParserFunctions

Using ParserFunctions within templates to display widgets, makes them an invaluable tool for creating complex displays of data with minimal lines of code.

It is particularly helpful if you want to pre-set some parameters of the widget while allowing users to modify others (e.g. video ID for YouTube widget or user handle for Twitter widget).

Simply including a widget in existing template that collects necessary data might be an easy way to enhance existing site without additional content work.