Extension:Widgets

また、ぜひこの機会に自作のウィジェットの投稿をお願いできないでしょうか。 ご理解のほどよろしくお願いいたします。

MediaWiki 拡張機能マニュアル

Widgets リリースの状態: 安定
実装	パーサー関数
説明	Widget 名前空間のページを編集すると、wiki にフリースタイルのウィジェットを追加できます
作者	Sergey Chernyshev Yaron Koren
メンテナー	Yaron Koren
最新バージョン	1.6.0 (2024-08-02)
MediaWiki	1.38+
ライセンス	GNU 一般公衆利用許諾書 2.0 以降
ダウンロード	拡張機能をダウンロード Git [?]: Git master をダウンロード リポジトリを参照 (Phabricator · GitHub) コミット履歴 リポジトリの貢献者 (GitHub) コード レビュー
例	MediaWikiWidgets.orgのウィジェット
パラメーター $wgWidgetsCompileDir $wgWidgetsUseFlaggedRevs
追加する権限 editwidgets
使用するフック ParserAfterTidy ParserFirstCallInit
四半期ごとのダウンロード数	149 (Ranked 37th)
使用中の公開ウィキ	1,122 (Ranked 207th)
translatewiki.net で翻訳を利用できる場合は、Widgets 拡張機能の翻訳にご協力ください
Vagrant role	widgets
問題点	未解決のタスク · バグを報告

Widgets 拡張機能は raw HTML ページの作成と、標準的なウィキページに (テンプレートと似た形で) 参照読み込みできるようにします。 実行するには、 Widget 名前空間にページを作成します。 Widget 名前空間の編集には権限の制限が設けられており、編集可能なウィキページ上に raw HTML を埋め込むセキュリティ上のリスクを回避します。 既製のウィジェットがたくさん用意されています。

ダウンロード

Git からコードを入手するには、以下のコマンドを書きます。

cd extensions
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/Widgets.git
cd Widgets
composer update --no-dev

Composer は PHP の依存関係管理ツールです。MediaWiki インストレーションの一部では、Composer をバージョン 2 に更新する必要があるかもしれません。手順はこちらを参照してください。

インストール

この拡張機能を呼び出すには、LocalSettings.php に以下の行を追加します:

wfLoadExtension( 'Widgets' );

フォルダーの権限

また、$IP/extensions/Widgets/compiled_templates/フォルダーはウェブサーバーから書き込み可能にしておく必要があります。 ウェブサーバーがディレクトリに書き込みできるようにするを参照してください。 compiled templatesフォルダーは、Smartyがコンパイル済みのテンプレートを保存する場所です。

設定

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.

ウィジェットの査読に FlaggedRevs を使用

You can use the FlaggedRevs extension to enable a widget security review process. See this version of the documentation for how to integrate the extension.

コンパイルしたウィジェットの保存先ディレクトリを変更する

You can use the $wgWidgetsCompileDir variable to change the directory for storing the compiled widgets ($compile_dir in the code). The default setting is

$wgWidgetsCompileDir = "$IP/extensions/Widgets/compiled_templates/";

If you change the location by setting the parameter with another directory, make sure that it exists and has the correct permissions.

利用者権限

この拡張機能は"Widget"と呼ばれる名前空間を追加しますが、安全ではないウィジェットコードによってセキュリティに影響を及ぼすおそれがあるため、この名前空間はeditwidgets権限を持つ利用者のみが編集できるようになっています(利用者追加のためのwidgeteditor(ウィジェット編集者)グループも作成されます。詳細は Help:User rights を参照してください)。

使用法

To add a widget to your MediaWiki installation, create a page in the Widget: namespace. You can then use the {{#widget:...}} parser function to include it in any page in the wiki.

{{#widget}} パーサー関数

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

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

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

Parameters can be expanded inside a widget using Smarty syntax, as follows:

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

The escape option specifies how the parameter will be 'escaped', or encoded, in the resultant Widget. It is critically important that all parameters are escaped to prevent cross-site scripting vulnerabilities. Some escape methods are ineffective. In general you should use one of escape:html, escape:url, escape:urlpathinfo or escape:javascript. See http://www.smarty.net/docsv2/en/language.modifier.escape for more information on this.

Widget 名前空間内のページ

All widgets in the wiki are defined by creating pages in the special "Widget:" namespace, like, e.g., "Widget:WidgetName".

To see all Widgets defined in your system, you can go to the page "Special:AllPages", select "Widget" in the namespace dropdown and click "Go".

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

You can find many pre-defined widgets to install in your wiki at MediaWikiWidgets.org. If you are interested in creating widgets yourself, see the next section.

ウィジェット ページの構文

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.

配列

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.

真偽値 (true/false)

In addition to PHP's default handling of Boolean conversions, you can (unlike in PHP) use the values "true" or "false" to set the Boolean value. The following would set the $popup parameter to false, for example:

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

In addition, you can set Boolean parameters to true by just using a parameter name without a value, like this:

{{#widget:WidgetName|popup}}

ドット付き記述

Parameter names can have dots, and Smarty will interpret them as associative arrays so that 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.

例

Widget:AssocTest might look like this:

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

...and you might call this Widget as follows:

{{#widget:AssocTest|arg.foo=bar|arg.bar=oni}}

..which would be displayed as:

• foo set to bar
• bar set to oni

有効な修飾語

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. Validating a parameter is not a replacement for escaping a parameter. You should still use an escape modifier even when validating. The following values for the validation are supported (mapping to PHP's validation filters):

• url — Validate as URL. This allows only URL schemes listed in $wgUrlProtocols , and, unlike PHP validation, does not allow URLs with characters dangerous in HTML.
• url-php (FILTER_VALIDATE_URL) — Warning: Validating as a URL still allows JavaScript URLs that can lead to XSS. It also allows URLs containing characters that are unsafe in HTML.
• int (FILTER_VALIDATE_INT) — Validates value as an integer, optionally from the specified range, and converts to int on success.
• boolean or bool (FILTER_VALIDATE_BOOLEAN) — Returns true for "1", "true", "on" and "yes". Returns false otherwise.
• float (FILTER_VALIDATE_FLOAT) — Validates value as float, optionally from the specified range, and converts to float on success.
• email (FILTER_VALIDATE_EMAIL) — Warning: Valid email address can still contain characters that are unsafe in HTML, be sure to escape in addition to validating
• ip (FILTER_VALIDATE_IP) — Validates value as IP address, optionally only IPv4 or IPv6 or not from private or reserved ranges.
• domain (FILTER_VALIDATE_DOMAIN) — Warning: Valid domains can still contain characters that are unsafe in HTML, be sure to escape in addition to validating.
• mac (FILTER_VALIDATE_MAC) — Validates value as MAC address.

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 Attempting to read property "value" on null in [...]. One way to prevent an error from showing despite undefined parameters is to add default:'' to widget parameters that are at risk of remaining undefined. For an example, see param2 below:

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

ウィジェットページのキャッシュを破棄

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 saving the page, it's cached by MediaWiki, so you won't see the result even if you reload it 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 need to use the Purge action (see also Purge extension), or wait a certain amount of time (up to 24 hours).

ウィジェットとテンプレート

Placing widgets within templates makes them an invaluable tool for creating complex displays of data with minimal lines of code.

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 YouTube widget or username for the Twitter widget).

作者

The widgets extension was created and designed by Sergey Chernyshev. It is currently maintained by Yaron Koren, who has also contributed to the code base.

Other important contributions have been provided by Alexandre Emsenhuber, Jeroen De Dauw, Joshua Lerner, Majr, Sam Reed and Tim Starling.

バージョン履歴

The Widgets extension is currently at version 1.6.0. See the entire version history.

ウィジェットの投稿

If you created a widget and would like to share it, feel free to post it to MediaWikiWidgets.org website and to add a reference to it to the Widget library on this page.

バグ / 機能の要望

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:

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

トラブルシューティング

There are a few common problems that 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>" /../extensions/Widgets/
smarty/Smarty.class.php on line 1095

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 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 called the Widget incorrectly. 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 the page doesn't load and you see the following error message in the log file:

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>

Check if you changed permissions and owner for Smarty to store compiled templates in. See also this post for further details.

• If your wiki began returning white pages or 500 errors when you updated MediaWiki to 1.20 or a later version, try setting the permissions on /../extensions/Widgets/compiled_templates to 777.

ウィジェット ライブラリ

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 page's contents.

To get the most up-to-date list of widgets by purpose, e.g., social media, video, images, etc. click here.

拡張機能をウィジェットと交換

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 create a widget to simplify deployment. Also, these lists of extensions are a good source for action:

• Extension:YouTube
• Extension:PDFEmbed

よくある質問

How do I get a video to align to the right with the other images?

Use something like this. Note that the ‎<br /> line break tags will have to be added manually. 180px is used for width because that is the default for thumbnails. 150px is used for height because that keeps the same ratio as the default 350x420.

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

関連項目

• HTML の制限 - list of extensions that allow for the inclusion of raw HTML