View source for Extension:Widgets

<languages /><!--WARNING: This page is 24 kio long; consider shortening it to better serve readers.--> 
{{Tip
 |1=<translate><!--T:3--> Please also consider [[<tvar name=1>#Contributing Widgets</tvar>|contributing widgets]] you created.</translate> <translate><!--T:4--> Thank you for sharing!</translate>
}}
{{Extension
|status      = stable
|type1       = parser function
|type2       =
|author      = <nowiki/>
* {{u|Sergey Chernyshev|Sergey Chernyshev}}
* {{u|Yaron Koren|Yaron Koren}}
|username    = 
|maintainer  = {{u|Yaron Koren|Yaron Koren}}
|description = <translate><!--T:5--> Allows adding free-type widgets to the wiki by editing pages in Widget namespace</translate>
|image       =
|version     = 1.5.0
|update      = 2023-11-13
|mediawiki   = 1.35+
|download    = {{WikimediaDownload|Widgets|phab=EWID}}
|readme      =
|changelog   =
|rights      = * editwidgets
|example     = <translate><!--T:56--> [<tvar name=1>https://www.mediawikiwidgets.org/Widgets_Catalog</tvar> Widgets on <tvar name=2>MediaWikiWidgets.org</tvar>]</translate>
|phabricator = MediaWiki-extensions-Widgets
|vagrant-role = widgets
}}
<translate><!--T:6--> The '''Widgets''' extension allows the creation of raw HTML pages that can be [[<tvar name=1>Special:MyLanguage/Transclusion</tvar>|transcluded]] (similarly to templates) in normal wiki pages.</translate>
<translate><!--T:7--> You do this by creating pages in the ''Widget'' namespace.</translate>
<translate><!--T:8--> They avoid the security problems of raw HTML in editable wiki pages because the privilege to edit in the Widget namespace is managed.</translate>
<translate><!--T:9--> Many pre-written Widgets are available.</translate>

<translate>
== Download == <!--T:50--> 

<!--T:13-->
To get the code with Git, type the following commands:
</translate>
<syntaxhighlight lang="bash">
cd extensions
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/Widgets.git
cd Widgets
composer update --no-dev
</syntaxhighlight>
<translate><!--T:47--> Composer is a PHP dependency manager. For MediaWiki >= 1.35.2, you may need to update composer to version 2. Instructions [[<tvar name=comp>Special:MyLanguage/Composer</tvar>|here]].</translate>

<translate>
== Installation == <!--T:10-->
</translate>
<translate><!--T:57--> To invoke this extension, add the following to <tvar name=1>{{ll|Manual:LocalSettings.php|LocalSettings.php}}</tvar>:</translate>

<syntaxhighlight lang="php">
wfLoadExtension( 'Widgets' );
</syntaxhighlight>

<translate>
<!--T:16-->
; Folder permissions
</translate>
<translate><!--T:58--> Also, the <tvar name=1><code>$IP/extensions/Widgets/compiled_templates/</code></tvar> folder should be made writable by the web server.</translate>
<translate><!--T:59--> See [<tvar name=1>https://web.archive.org/web/20160417115203/http://www.g-loaded.eu/2008/12/09/making-a-directory-writable-by-the-webserver/</tvar> Making a directory writable by the webserver].</translate>
<translate><!--T:60--> The compiled templates folder is where Smarty stores pre-compiled templates.</translate>

<translate>
== Configuration == <!--T:15-->

<!--T:51-->
The steps in this section are optional—the extension should work fine even without these changes, but they will give you more flexibility if you have a complex MediaWiki installation.

=== Using FlaggedRevs for widget review === <!--T:29-->
</translate>

<translate><!--T:61--> You can use the [[<tvar name=1>Special:MyLanguage/Extension:FlaggedRevs</tvar>|FlaggedRevs]] extension to enable a widget security review process.</translate> <translate><!--T:216--> See this [[<tvar name=1>Special:Permanentlink/6159317#Using_FlaggedRevs_for_widget_review</tvar>|version of the documentation]] for how to integrate the extension.</translate>

<translate>
=== Changing the directory for storing the compiled widgets === <!--T:30-->
</translate>
<translate><!--T:66--> You can use the <tvar name=1><code>$wgWidgetsCompileDir</code></tvar> variable to change the directory for storing the compiled widgets (<tvar name=2>$compile</tvar>_dir in the code).</translate>
<translate><!--T:67--> The default setting is</translate>

<syntaxhighlight lang="php">
$wgWidgetsCompileDir = "$IP/extensions/Widgets/compiled_templates/";
</syntaxhighlight>

<translate><!--T:68--> If you change the location by setting the parameter with another directory, make sure that it exists and has the [[<tvar name=1>#Folder permissions</tvar>|correct permissions]].</translate>

<translate>
=== User rights === <!--T:32-->
</translate>
<translate><!--T:69--> This extension adds a namespace called "<tvar name=1>Widget</tvar>", but due to potential security implications that can result from using insecure widget code, this namespace is only editable by users who have the <tvar name=2><code>editwidgets</code></tvar> permission (the <tvar name=3><code>widgeteditor</code></tvar> group is also created to add users to; see [[<tvar name=4>Special:MyLanguage/Help:User rights management</tvar>|Help:User rights management]] for more details).</translate>

<translate>
== Usage == <!--T:17-->
</translate>
<translate><!--T:70--> To add a widget to your MediaWiki installation, just create a page in the <tvar name=1>Widget:</tvar> namespace.</translate>
<translate><!--T:71--> You can then use the <tvar name=1><syntaxhighlight lang=wikitext inline>{{#widget:...}}</syntaxhighlight></tvar> parser function to include it in any page in the wiki.</translate>

<translate nowrap>
=== <tvar name=1><code><nowiki>{{#widget}}</nowiki></code></tvar> parser function === <!--T:18-->
</translate>
<translate><!--T:72--> To add a defined widget to pages, users can use the <tvar name=1><syntaxhighlight lang=wikitext inline>{{#widget}}</syntaxhighlight></tvar> parser function.</translate>
<translate><!--T:73--> The syntax is as follows:</translate>
<syntaxhighlight lang=wikitext>
{{#widget:WidgetName|param1=value1|param2=value2}}
</syntaxhighlight>

<translate><!--T:74--> Where <tvar name=1>WidgetName</tvar> is a page name in the <tvar name=2>Widget</tvar> namespace (e.g. <tvar name=3>Widget:WidgetName</tvar>) and param=value pairs are the settable parameters, defined within the widget code.</translate>

<translate><!--T:75--> Parameters can be expanded inside a widget using [<tvar name=1>https://www.smarty.net/syntax_comparison</tvar> Smarty syntax], as follows:</translate>

<syntaxhighlight lang=html>
<a href="<!--{$param1|escape:'url'}-->"><!--{$param2|escape:'html'}--></a>
</syntaxhighlight>

<translate><!--T:76--> The <tvar name=1><code>escape</code></tvar> options specifies how the parameter will be 'escaped', or encoded, in the resultant Widget.</translate>
<translate><!--T:77--> It is critically important that all parameters are escaped to prevent cross-site scripting vulnerabilities.</translate>
<translate><!--T:78--> Some escape methods are ineffective.</translate>
<translate><!--T:79--> In general you should use one of <tvar name=1><code>escape:html</code></tvar>, <tvar name=2><code>escape:url</code></tvar>, <tvar name=3><code>escape:urlpathinfo</code></tvar> or <tvar name=4><code>escape:javascript</code></tvar>.</translate>
<translate><!--T:80--> See <tvar name=1>http://www.smarty.net/docsv2/en/language.modifier.escape</tvar> for more information on this.</translate>

<translate>
=== Pages in Widget namespace === <!--T:19-->
</translate>
<translate><!--T:81--> All widgets in the wiki are defined by creating pages in the special "<tvar name=1>Widget:</tvar>" namespace, like e.g. "<tvar name=2>Widget:WidgetName</tvar>".</translate>

<translate><!--T:82--> To see all Widgets defined in your system, you can simply go to the page "<tvar name=1>Special:AllPages</tvar>", select "<tvar name=2>Widget</tvar>" in the namespace dropdown and click "Go".</translate>

<translate><!--T:83--> For security reasons, these pages are only editable by wiki administrators - see [[<tvar name=1>#User rights</tvar>|User rights]] above for more info.</translate>

<translate><!--T:84--> You can find many pre-defined widgets to install in your wiki at [<tvar name=1>https://www.mediawikiwidgets.org/Widgets_Catalog#Available_widgets</tvar> MediaWikiWidgets.org].</translate>
<translate><!--T:52--> If you are interested in creating widgets yourself, see the next section.</translate>

<translate>
== Widget page syntax == <!--T:20-->
</translate>
<translate><!--T:85--> The Widgets extension uses the [<tvar name=1>https://www.smarty.net/</tvar> Smarty] PHP templating engine to provide simple templating functionality within widget pages.</translate>
<translate><!--T:53--> All parameters passed to a widget are converted into Smarty parameters.</translate>

<translate><!--T:86--> '''Important:'''</translate>
<translate><!--T:87--> Use [<tvar name=1>https://www.smarty.net/docsv2/en/language.modifier.escape</tvar> escape modifiers] on all passed-in parameters to prevent users from passing in raw HTML from normal wiki pages.</translate>
<translate><!--T:54--> Failure to protect against this will expose the hosting site to XSS (and other) attacks.</translate>

<translate>
=== Arrays === <!--T:21-->
</translate>
<translate><!--T:55--> If you use the same parameter multiple times, the widget will get an array of values.</translate>
<translate><!--T:88--> You can use <tvar name=1>[https://www.smarty.net/docsv2/en/language.function.foreach <code>foreach</code>]</tvar> to go through the array.</translate>

<translate>
=== Booleans (true/false) === <!--T:22-->
</translate>
<translate><!--T:89--> In addition to PHP's default handling of Boolean conversions, you can (unlike in PHP) use the values "<tvar name=1>true</tvar>" or "<tvar name=21>false</tvar>" to set the Boolean value.</translate>
<translate><!--T:90--> The following would set the <tvar name=1><code>$popup</code></tvar> parameter to <tvar name=2><code>false</code></tvar>, for example:</translate>

<syntaxhighlight lang=wikitext>
{{#widget:WidgetName|popup=false}}
</syntaxhighlight>

<translate><!--T:91--> In addition, you can set Boolean parameters to <tvar name=1><code>true</code></tvar> by just using a parameter name without a value, like this:</translate>

<syntaxhighlight lang=wikitext>
{{#widget:WidgetName|popup}}
</syntaxhighlight>

<translate>
=== Dotted notation === <!--T:23-->
</translate>
<translate><!--T:92--> Parameter names can have dots, and Smarty will interpret them as associative arrays, so you can use <tvar name=1>[https://www.smarty.net/docsv2/en/language.function.foreach <code>foreach</code>]</tvar> with both <tvar name=2><code>key</code></tvar> and <tvar name=3><code>item</code></tvar> attributes to traverse through them, or you can just use the same name with dots if you want to reference the parameter directly.</translate>

<translate>
<!--T:24-->
; Example
</translate>
<translate><!--T:93--> Widget:AssocTest might look like this:</translate>

<syntaxhighlight lang=html>
<includeonly><ul>
<!--{foreach from=$arg key=key item=item}-->
   <li><!--{$key|escape:'html'}-->: set to <!--{$item|escape:'html'}--></li>
<!--{/foreach}-->
</ul></includeonly>
</syntaxhighlight>

<translate><!--T:94--> ...and you might call this Widget as follows:</translate>

<syntaxhighlight lang=wikitext>
{{#widget:AssocTest|arg.foo=bar|arg.bar=oni}}
</syntaxhighlight>

<translate><!--T:95--> ..which would be displayed as:</translate>

* <translate><!--T:96--> <tvar name=1>foo</tvar> set to <tvar name=2>bar</tvar></translate>
* <translate><!--T:97--> <tvar name=1>bar</tvar> set to <tvar name=2>oni</tvar></translate>

<translate>
=== Validate modifier === <!--T:25-->
</translate>
<translate><!--T:98--> In addition to [<tvar name=1>https://www.smarty.net/docsv2/en/language.modifiers</tvar> standard Smarty modifiers] (like the heavily used <tvar name=2><code>[https://www.smarty.net/docsv2/en/language.modifier.escape escape]</code></tvar>), the Widgets extension implements the <tvar name=3><code>validate</code></tvar> modifier, that uses [<tvar name=4>https://php.net/filter</tvar> PHP Data filtering] to allow for validating widget parameters.</translate>
<translate><!--T:99--> Validating a parameter is not a replacement for escaping a parameter.</translate>
<translate><!--T:100--> You should still use an escape modifier even when validating.</translate>
<translate><!--T:101--> The following values for the validate are supported (mapping to [<tvar name=1>https://www.php.net/manual/fr/filter.filters.validate.php</tvar> PHP's validation filters]):</translate>

* <code>url</code> &mdash; <translate><!--T:102--> Validate as URL.</translate> <translate><!--T:104--> This allows only URL schemes listed in [[<tvar name=1>Special:MyLanguage/Manual:$wgUrlProtocols</tvar>|$wgUrlProtocols]], and, unlike PHP validation, does not allow URLs with characters dangerous in HTML.</translate>
* <code>url-php</code> (FILTER_VALIDATE_URL)  &mdash; <translate><!--T:106--> '''Warning:''' Validating as a URL still allows JavaScript URLs that can lead to XSS.</translate> <translate><!--T:107--> It also allows urls containing characters that are unsafe in HTML.</translate>
* <code>int</code> (FILTER_VALIDATE_INT)  &mdash; <translate><!--T:180--> Validates value as integer, optionally from the specified range, and converts to int on success.</translate> 
* <code>boolean</code> or <code>bool</code> (FILTER_VALIDATE_BOOLEAN)  &mdash; <translate><!--T:181--> Returns <tvar name=1><code>true</code></tvar> for "1", "true", "on" and "yes".</translate> <translate><!--T:182--> Returns <tvar name=1><code>false</code></tvar> otherwise.</translate> 
* <code>float</code> (FILTER_VALIDATE_FLOAT)  &mdash; <translate><!--T:183--> Validates value as float, optionally from the specified range, and converts to float on success.</translate>
* <code>email</code> (FILTER_VALIDATE_EMAIL)  &mdash; <translate><!--T:108--> '''Warning:''' Valid email address can still contain characters that are unsafe in HTML, be sure to escape in addition to validating</translate>
* <code>ip</code> (FILTER_VALIDATE_IP)  &mdash; <translate><!--T:184--> Validates value as IP address, optionally only IPv4 or IPv6 or not from private or reserved ranges.</translate> 
* <code>domain</code> (FILTER_VALIDATE_DOMAIN)  &mdash; <translate><!--T:109--> '''Warning:''' Valid domains can still contain characters that are unsafe in HTML, be sure to escape in addition to validating.</translate>
* <code>mac</code> (FILTER_VALIDATE_MAC)  &mdash; <translate><!--T:185--> Validates value as MAC address.</translate>

=== Undefined parameters ===

If the widget expects a parameter but that parameter remains undefined in the parser function, a PHP error will be thrown. They're hidden by default, but if they're visible on your wiki it might say something like <code>Attempting to read property "value" on null in [...]</code>. One way to prevent an error from showing despite undefined parameters is to add <code>default:<nowiki>''</nowiki></code> to widget parameters that are at risk of remaining undefined. For an example see param2 below:

<syntaxhighlight lang=html>
<a href="<!--{$param1|escape:'url'}-->" class="<!--{$param2|default:''|escape:'html'}-->"><!--{$param3|escape:'html'}--></a>
</syntaxhighlight>

<translate>
=== Refreshing a widget page === <!--T:26-->
</translate>
<translate><!--T:110--> 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).</translate>
<translate><!--T:111--> This happens because the page contents are not available to the Widgets extension until a page is saved, but the call to the <tvar name=1><code><nowiki>{{#widget}}</nowiki></code></tvar> parser function is made before the page is saved.</translate>
<translate><!--T:112--> 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.</translate>
<translate><!--T:113--> 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 <code>[[<tvar name=1>Special:MyLanguage/Manual:Purge</tvar>|Purge]]</code> action (see also [[<tvar name=2>Special:MyLanguage/Extension:Purge</tvar>|Purge]] extension), or wait a certain amount of time (up to 24 hours).</translate>

<translate>
=== Widgets and templates === <!--T:27-->

<!--T:114-->
Placing widgets within [[<tvar name=1>Special:MyLanguage/Help:Templates</tvar>|templates]] makes them an invaluable tool for creating complex displays of data with minimal lines of code.

<!--T:115-->
It is particularly helpful if you want to preset some parameters of the widget while allowing users to modify others (e.g. video ID for the [<tvar name=1>https://www.mediawikiwidgets.org/YouTube</tvar> YouTube] widget or username for the <tvar name=2>[https://www.mediawikiwidgets.org/Twitter_timeline Twitter]</tvar> widget).

== Authors == <!--T:33-->
</translate>
<translate><!--T:116--> The widgets extension was created and designed by <tvar name=1>[[User:Sergey Chernyshev|Sergey Chernyshev]]</tvar>.</translate>
<translate><!--T:117--> It is currently maintained by <tvar name=1>[[User:Yaron Koren|Yaron Koren]]</tvar>, who has also contributed to the code base.</translate>

<translate><!--T:118--> Other important contributions have been provided by Alexandre Emsenhuber, Jeroen De Dauw, Joshua Lerner, Majr, Sam Reed and Tim Starling.</translate>

{{anchor|CHANGES}}
<translate>
== Version history == <!--T:34-->
</translate>
<translate><!--T:217--> The Widgets extension is currently at version <tvar name=1>1.5.0</tvar>.</translate>
<translate><!--T:218--> See the entire [[<tvar name=1>Special:MyLanguage/Extension:Widgets/Version history</tvar>|version history]].</translate>

{{anchor|Contributing Widgets}}
<translate>
== Contributing Widgets == <!--T:35-->

<!--T:119-->
If you created a widget and would like to share it, feel free to post it to [<tvar name=url>https://www.mediawikiwidgets.org/Adding_your_widget</tvar> MediaWikiWidgets.org] website and to add a reference to it to the [[<tvar name=1>#Widget library</tvar>|Widget library]] on this page.

== Bugs and feature requests == <!--T:36-->

<!--T:120-->
If you found a problem, would like to contribute a patch or request a new feature, feel free to open a bug in the Wikimedia bug tracker:
</translate>

 https://phabricator.wikimedia.org/maniphest/task/create/?projects=MediaWiki-extensions-Widgets

<translate>
== Troubleshooting == <!--T:38-->

<!--T:121-->
There are a few common problems that users encounter when they start to use Widgets extension - we'll try to document them here:
</translate>

* <translate><!--T:122--> On a widget page, right after you just created it (or copied from <tvar name=1>MediaWikiWidgets.org</tvar>) you see the message:</translate>

<pre>
Warning: Smarty error: unable to read resource: "Widget:<your-widget-name>" /../extensions/Widgets/
smarty/Smarty.class.php on line 1095
</pre>

: <translate><!--T:123--> This is most likely caused by the widget not yet existing at the moment when the widget page itself is being processed - to solve this simply purge the page, e.g. add '''<tvar name=1>&action=purge</tvar>''' (or '''<tvar name=2>?action=purge</tvar>''' if you have [[<tvar name=3>Special:MyLanguage/Manual:Short URL</tvar>|nice URLs]]) to the URL.</translate>
: <translate><!--T:124--> It's also possible that you called the Widget incorrectly.</translate> <translate><!--T:125--> Widget page names are case sensitive and must match the name of the widget you're calling.</translate> <translate><!--T:126--> E.g. don't use <tvar name=1>{{#widget:Youtube|...}}</tvar> when the widget is called "<tvar name=2>Widget:YouTube</tvar>", or vice versa.</translate>

* <translate><!--T:127--> If the page doesn't load and you see the following error message in the log file:</translate>
<pre>PHP Fatal error:  Smarty error: unable to write to $compile_dir '/../extensions/Widgets/compiled_templates'.
Be sure $compile_dir is writable by the web server user. in /../extensions/Widgets/smarty/Smarty.class.php on line 1095,
referer: https://your-wiki.com/Widget:<your-widget-name></pre>
: <translate><!--T:128--> Check if you [[<tvar name=1>#Folder permissions</tvar>|changed permissions and owner]] for Smarty to store compiled templates in.</translate> <translate><!--T:129--> See also [<tvar name=url>https://phabricator.wikimedia.org/T180316#4941305</tvar> this post] for further details.</translate>
* <translate><!--T:130--> If your wiki began returning totally white pages or 500 errors when you updated MediaWiki to 1.20 or a later version, try setting the permissions on <tvar name=1>/../extensions/Widgets/compiled_templates</tvar> to 777.</translate>

{{anchor|Widget library}}
<translate>
== Widget library == <!--T:39-->
</translate>
<translate><!--T:131--> [<tvar name=url>https://www.mediawikiwidgets.org/Widgets_Catalog</tvar> MediaWikiWidgets.org] contains a full library of ready-made widgets, including support for most of the major video sites.</translate>
<translate><!--T:132--> Any widget can be used simply by copying over the contents of the page.</translate>

<translate><!--T:169--> To get the most up-to-date list of widgets by purpose, e.g. social media, video, images, etc.</translate>
<translate><!--T:219--> [<tvar name=url>https://www.mediawikiwidgets.org/List_of_widgets_by_purpose</tvar> click here].</translate>

<translate>
== Extensions that can be replaced with widgets == <!--T:43-->

<!--T:170-->
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.
</translate>

<translate><!--T:171--> Maybe someone will come and create a widget for that to simplify deployment.</translate>
<translate><!--T:172--> Also, these lists of extensions are a good source for action:</translate>
* {{ll|Extension:YouTube}}
* {{ll|Extension:PDFEmbed}}

<translate>
==Frequently asked questions== <!--T:44-->
</translate>
;<translate><!--T:173--> How do I get a video to align to the right with the other images?</translate>

<translate><!--T:174--> Use something like this.</translate>
<translate><!--T:175--> Note that the <tvar name=1>{{tag|br|single}}</tvar> line break tags will have to be added manually.</translate>
<translate><!--T:176--> 180px is used for width because that is the default for thumbnails.</translate>
<translate><!--T:177--> 150px is used for height because that keeps the same ratio as for the default 350x420.</translate>

<syntaxhighlight lang="html">
<div class="thumb tright">
<div class="thumbinner">
{{#widget: YouTube |width=180px |height=150px |id=qRhitIPEr0Y }}<br>
<div class="thumbcaption">
Seeing bad acting sully a good<br>
script can upset some people<br>
who place a high value on<br>
natural-seeming performances.<br>
</div>
</div>
</div>
</syntaxhighlight>

<translate>
==See also== <!--T:178-->
</translate>
* {{ll|HTML_restriction}} - <translate><!--T:179--> list of extensions that allow for the inclusion of raw HTML</translate>

{{Used by}}

[[Category:Remote content extensions{{#translation:}}]]
[[Category:Flickr extensions{{#translation:}}]]
[[Category:Social bookmarking extensions{{#translation:}}]]
[[Category:Video player extensions{{#translation:}}]]
[[Category:YouTube extensions{{#translation:}}]]
[[Category:Google extensions{{#translation:}}]]
[[Category:Yahoo extensions{{#translation:}}]]
[[Category:News bar extensions{{#translation:}}]]
[[Category:Audio player extensions{{#translation:}}]]
[[Category:Amazon extensions{{#translation:}}]]
[[Category:Disqus extensions{{#translation:}}]]
[[Category:Discussion and forum extensions{{#translation:}}]]
[[Category:Twitter extensions{{#translation:}}]]
[[Category:Wikipedia extensions{{#translation:}}]]