Extension:Widgets

From MediaWiki.org

Jump to: navigation, search

             

Manual on MediaWiki Extensions
List of MediaWiki Extensions
Crystal Clear action run.png
Widgets

Release status: stable
Implementation  Parser function
Description Allows adding free-type widgets to the wiki by editing pages in Widget namespace
Author(s)  Sergey ChernyshevTalk
Last Version  0.8.9 (2009-11-11)
MediaWiki  1.12?
License GPL
Download SVN, tarball, zip
Example  Widgets on MediaWikiWidgets.org

check usage (experimental)

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

This extension was developed and being maintained by Sergey Chernyshev.

Contents

[edit] Usage

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

[edit] {{#widget}} parser function

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

{{#widget:WidgetName|param1=value1|param2=value2}}

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

[edit] Pages in Widget namespace

All widgets in the wiki are defined by creating pages in special Widget 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 Special:AllPages, 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.

[edit] 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.

[edit] Arrays

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

[edit] Booleans (true/false)

Since 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 boolean value false (this is not the case in PHP as string "false" doesn't get converted to boolean false, see PHP docs on boolean casting).

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

[edit] 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 parameter directly.

[edit] Validate modifier

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

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

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

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)

[edit] 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 {{#widget}} 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 purge action (see also Purge extension).

[edit] Download instructions

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

[edit] Installing from tarball

You can download Widgets code here:

You can also download this extension as part of Semantic Bundle, which includes Widgets version 0.8.8, as well as some other very interesting extensions.

[edit] Installing from SVN

To get code from Subversion, just type

svn checkout http://svn.wikimedia.org/svnroot/mediawiki/tags/extensions/Widgets/REL_0_8_9/

[edit] Installation

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

require_once("$IP/extensions/Widgets/Widgets.php");

[edit] Folder permissions

Also, $IP/extensions/Widgets/compiled_templates/ folder should be made writable by web server (this is where Smarty stores pre-compiled templates).

[edit] 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 editwidgets permission (widgeteditor 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;

[edit] Optional configuration

[edit] 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:

define('NS_WIDGET', 274);
require( "$IP/extensions/Widgets/Widgets.php" );

Widget Talk namespace ID (NS_WIDGET_TALK) will be automatically defined as NS_WIDGET + 1, so don't set it yourself.

You can use NS_WIDGET and NS_WIDGET_TALK when configuring other MediaWiki properties.

[edit] CHANGES

  • 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 </p><p> 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

[edit] 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.

[edit] 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

[edit] 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.

[edit] 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:<your-widget-name>" /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 {{#widget:Youtube|...}} when the widget is called Widget:YouTube, or vice versa.
  • If page doesn't load and you see following error message in the log file:
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:<your-widget-name>
Check if you changed permissions for Smarty to store compiled templates in.

[edit] 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.

[edit] Video widgets

[edit] More widgets

[edit] Even more widgets

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

[edit] See also

[edit] Sites using this extension

Retrieved from "http://www.mediawiki.org/wiki/Extension:Widgets"