Extension:Widgets

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

This extension was developed and being maintained by Sergey Chernyshev.

Installation
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.9.1.tgz - compressed using tar and gzip
 * Widgets-0.9.1.zip - compressed using zip

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

Configuration
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).

An example of Qnap: Start telnet with port22 find / -name 'compiled_templates' [cr] [result] /share/MD0_DATA/Qweb/mediawiki-1.15.1/extensions/Widgets/compiled_templates chmod a+rw /share/MD0_DATA/Qweb/mediawiki-1.15.1/extensions/Widgets/compiled_templates

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.

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.

Pages in Widget namespace
All widgets in the wiki are defined by creating pages in special  namespace which is automatically added to your wiki when you install this extension.

To see all Widgets defined in your system, simply list all page is this namespace by going to, picking "Widget" in a namespace dropdown and clicking "Go".

For security reasons, these pages are only editable by wiki administrators - see #User rights below for more info.

You can find many widgets to install to your wiki at MediaWikiWidgets.org. If you're interested in creating widgets yourself, next section.

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.

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 Purge extension).

Additional configuration
Steps in this section are optional - extension will work fine without these changes, but they give you more flexibility if you have a complex MediaWiki installation.

Using FlaggedRevs for widget review
As of version 0.9 you can use FlaggedRevs extension for widget security review process.

This will enable Widgets extension to use only stable versions of the Widget:* pages.

When you have your FlaggedRevs configured in the way that represents your review process, just set the following variable in your LocalSettings.php:

This will tell Widgets extension not to protect Widget:* pages using permissions, but require changes to be reviewed for security before they can take effect.

To just use FlaggedRevs to review widgets, following configuration should suffice:

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.

User rights
This extension adds a namespace called "Widget", 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).

CHANGES

 * 0.9.1 (September 19, 2010) - Release 0.9.1: Some code structure changes and fix to a bug 25219.
 * 0.9 (April 16, 2010) - Release 0.9: Added support for FlaggedRev extension controlling Widget review.
 * 0.8.10 (November 27, 2009) - Security Release: Fixed a security hole in error message.
 * 0.8.9 (November 11, 2009) - Bugfix release: base64 wasn't identified properly which caused some widgets not to be displayed.
 * 0.8.8 (November 2, 2009) - HTML is inserted as is now, thanks to Joshua C. Lerner.
 * 0.8.7 (June 19, 2009) - namespaces issues and i18n issues fixed by ialex.
 * 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

Contributing 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 Widget library.

Bugs and feature requests
If you found a problem, would like to contribute a patch or request a new feature, feel free to open a bug in MediaWiki Bugzilla:

https://bugzilla.wikimedia.org/enter_bug.cgi?product=MediaWiki+extensions&component=Widgets

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.

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.
 * It's also possible that you call on the Widget wrongly. Widget page names are case sensitive and must match the name of the widget you're calling. E.g. don't use when the widget is called Widget:YouTube, or vice versa.

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.

Widget 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.

Extensions that can be replaced with widgets
Let's collect a list of extensions that can be replaced with widgets because all they do is output some HTML/JS/CSS with parameters and simple logic that can be done using Smarty templates.

Maybe someone will come and create a widget for that to simplify deployment:
 * Extension:Google Chart

Also, these lists of extensions are good source for action:
 * Special:WhatLinksHere/Template:XSS_alert
 * Extension_Matrix/parser_function

Sites using this extension
Please post to live wiki sites only.
 * 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
 * Wikitel
 * Persianwiki
 * JargonF - (French) IT dictionary / Dictionnaire d'informatique
 * Wikipercu - (French) Percussions (music)
 * Men of War - Wiki
 * Iubar Wiki
 * Appropedia Sharing knowledge to build rich, sustainable lives.
 * brajdiscovery.org
 * Virtual Loup de Mer - (French) Virtual Sailing Game.
 * ponkavanam.com
 * The Secret World Russian Wiki
 * Esopedia: l'Enciclopedia dell'Esoterismo
 * BCmoney MobileTV knowledge base