Extension:Widgets

Widgets extension allows adding widgets to wiki by just creating pages in Widget namespace.

This extension was developed by Sergey Chernyshev for Ardorado.com and sponsored by Semantic Communities, LLC.

Usage
To add a widget to MediaWiki installation, just create a page in Widget namespace and then use  parser function to include it to the pages of the wiki.

Widget page syntax
Widget extension uses Smarty PHP templating engine to provide simple templating functionality within widget pages. All parameters passed to widget are converted into Smarty parameters.

You should use escape modifiers to make sure that user parameters can not expose hosting website to XSS (or any other) attacks.

parser function
To add defined widget to pages, users can use  parser function. The syntax is as follows:

Where WidgetName is a page name in Widget namespace (e.g. Widget:WidgetName) and param=value pairs are defining parameters defined within widget code.

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

Booleans (true/false)
Since 0.8.5, this extension supports passing boolean parameters by just using a parameter name without a value like this:

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

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

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

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

Following values for the validate are supported (mapping to PHP's validation filters):
 * (FILTER_VALIDATE_URL)
 * (FILTER_VALIDATE_INT)
 * (FILTER_VALIDATE_BOOLEAN)
 * (FILTER_VALIDATE_FLOAT)
 * (FILTER_VALIDATE_EMAIL)
 * (FILTER_VALIDATE_IP)

Refreshing 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 page contents are not available to Widget extension until page is saved, but the call to  parser function is made before page is saved. After page is saved, it's being cached by MediaWiki so you don't see the result even if you just reload the page. To make latest edits of the widget code to work, you need to refresh the page in the cache, to do this, you just need to use  action (see also Purgetab extension).

Download instructions
Download the code archive and extract it to  folder. Note: $IP stands for the root directory of your MediaWiki installation, the same directory that holds LocalSettings.php.

Installing from tarball
You can download Widgets code here:
 * Widgets-0.8.6.tgz - compressed using tar and gzip
 * Widgets-0.8.6.zip - compressed using zip

Installing from SVN
To get code from Subversion, just type svn checkout http://svn.wikimedia.org/svnroot/mediawiki/trunk/extensions/Widgets/

Installation
To install this extension, add the following to LocalSettings.php:

Folder permissions
Also,  folder should be made writable by web server (this is where Smarty stores pre-compiled templates).

User rights
This extension adds Widget namespace, but due to potential security implications that can result from using insecure widget code, this namespace is only editable by users who have  permission (  group is also created to add users to, see Help:User rights management for more details).

To allow widgets to be editable by sysops, add the following to your 'LocalSettings.php' file:

$wgGroupPermissions['sysop']['editwidgets'] = true;

Changing namespace ID
Default namespace ID (274) can be changed if you want, but make sure that it's an even number. To set the namespace ID, define NS_WIDGET value before you include the extension in LocalSettings.php: Widget Talk namespace ID (NS_WIDGET_TALK) will be automatically defined as  + 1, so don't set it yourself.

You can use  and   when configuring other MediaWiki properties.

CHANGES

 * 0.8.6 (May 22, 2009) - some important security fixes by Tim Starling.
 * 0.8.5 (March 12, 2009) - Allowing parameters without values to work as bulean "true" and converting test "false" into boolean false (which is not the case in PHP itself).
 * 0.8.4 (March 11, 2009) - Minor security release - compiled Smarty templates can't be accessed directly. Also fixed a problem with compiled_templates being empty in archives and therefore not extractable by some software.
 * 0.8.3 (February 10, 2009) - Added 'validate' modifier that makes sure variable value conforms to validation rules (using http://us.php.net/filter).
 * 0.8.2 (January 27, 2009) - Fixed a bug when widgets were not showing up correctly on old versions of the pages. Thanks to Max Ingleton for a bug report.
 * 0.8.1 (June 25, 2008) - Worked around MediaWiki bug that inserts  in front of widget output.
 * 0.8 (June 10, 2008) - Fixed a bug where variables were carried over from one widget to another on the same page
 * 0.7 (May 23, 2008) - Added support for arrays and Smarty's dotted notation
 * 0.6 (May 9, 2008) - Minor tweaks and bug fixes, release Makefile
 * 0.5 (Feb 11, 2008) - First public release

TODO

 * ? Implement page-wide variables. Useful for widgets like JS-Kit that require only one JS include, for example.
 * get the Widgets component in WikiMedia bugzilla so list below can be moved there.
 * rewrite using next version of Smarty and get rid of compiled_templates folder altogether, use MW cache capabilities.

Widgets that use 'validate' modifier break the site on PHP < 5.2.0
When 'validate' modifier (http://www.mediawiki.org/wiki/Widgets#Validate_modifier) is used on widget parameters, sites that use PHP version < 5.2.0 break because filter extension is not available: http://us.php.net/manual/en/filter.installation.php

Proper solution is to upgrade PHP, but code should be modified to display an error in place of a widget.

Contributing code and widgets
If you would like to contribute patches or found some problems with the code, please send message to the discussion group: http://groups.google.com/group/mediawiki-widgets

If you created a widget and would like to share it, feel free to post it to MediaWikiWidgets.org or just add it to Widgets library.

Troubleshooting
There are a few common problems users encounter when they start to use Widgets extension - we'll try to document them here:
 * On a widget page, right after you just created it (or copied from MediaWikiWidgets.org)you see the message:

Warning: Smarty error: unable to read resource: "Widget:" /path-to-your-mediawiki/extensions/Widgets/ smarty/Smarty.class.php on line 1095


 * This is most likely caused by widget not yet existing at the moment when widget page itself is being processed - to solve this simply purge the page, e.g. add &action=purge (or ?action=purge if you have nice URLs) to the url.

PHP Fatal error: Smarty error: unable to write to $compile_dir '/path-to-your-mediawiki/extensions/Widgets/compiled_templates'. Be sure $compile_dir is writable by the web server user. in /path-to-your-mediawiki/extensions/Widgets/smarty/Smarty.class.php on line 1095, referer: http://your-wiki.com/Widget:
 * If page doesn't load and you see following error message in the log file:
 * Check if you changed permissions for Smarty to store compiled templates in.

Support
The best way to seek help with this extension is to send you questions to MediaWiki Widgets Google group

http://groups.google.com/group/mediawiki-widgets

extension maintainer and active users and contributors are on this list and will be able to help you.

Widgets library
MediaWikiWidgets.org contains a full library of ready-made widgets, including support for most of the major video sites. Any widget can be used simply by copying over the contents of the page.

To get a most up to date list of widgets click here.

Sites using this extension

 * Technical Presentations
 * Ardorado.com
 * All sites on Referata.com hosting
 * Second Life wiki
 * New York Semantic Web meetup group
 * Armada HQ wiki
 * theDIYpal
 * The Koç School Knowledgebase and The Koç School Academic Wiki (two wiki's of a Turkish K-12 school, both with restricted access)
 * Verwaltungskooperation.at - Cooperation in public administration (German)
 * University of Sheffield: teachingcommons project - Case Studies Wiki
 * Guida Wiki Comuni-Italiani.it
 * MIKE2.0 Wiki
 * SAS community wiki
 * Food & Cooking News on DishiWiki
 * Wiki Expert