Extension:Widgets

From mediawiki.org
Jump to navigation Jump to search
This page is a translated version of the page Extension:Widgets and the translation is 98% complete.
Other languages:
Deutsch • ‎English • ‎Türkçe • ‎français • ‎polski • ‎日本語
Phabricatorチケットタスク T245850で解説のとおり、セキュリティ上の問題が発生しており、至急、お使いのwikiでウィジェットの更新を実行するよう強く勧告されています。 修正の供給対象の分岐は過去版で MediaWiki 1.31.x、1.33.x、1.34.x ならびにそれより新しい版の分岐すべてです。
また、ぜひこの機会に自作のウィジェットの投稿をお願いできないでしょうか。 ご理解のほどよろしくお願いいたします。
MediaWiki 拡張機能マニュアル
OOjs UI icon advanced.svg
Widgets
リリースの状態: 安定
実装 パーサー関数
説明 Widget 名前空間のページを編集すると、wiki にフリースタイルのウィジェットを追加できます
作者
メンテナー Yaron Koren
最新バージョン  (Continuous updates)
MediaWiki 1.31.x and 1.33+
PHP 5.6+
ライセンス GNU 一般公衆利用許諾書 2.0 以降
ダウンロード
Widgets on MediaWikiWidgets.org
  • $wgWidgetsCompileDir
  • $wgWidgetsUseFlaggedRevs
  • editwidgets
translatewiki.net で翻訳を利用できる場合は、Widgets 拡張機能の翻訳にご協力ください
使用状況とバージョン マトリクスを確認してください。
Vagrant role widgets
問題点 未解決のタスク · バグを報告

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

インストール

Git 経由もしくは .zip 形式の圧縮ファイルをダウンロードしてインストールします。

Git を使用してインストール

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

MediaWiki バージョン:
1.32
# for mediawiki version 1.32 and later
cd extensions
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/Widgets.git
cd Widgets
composer update --no-dev
MediaWiki バージョン:
1.31
# for mediawiki version 1.31 and earlier
cd extensions
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/Widgets.git
cd Widgets
git submodule init
git submodule update


.zip ファイルからインストール

警告 警告: As of March 2018, using the libs folder from the Smarty version (v2.6.31) may trigger a "Call to undefined method Smarty::addPluginsDir()" error. This issue was reportedly avoided by using a current release (v3.1.34). See discussion.
  1. Download the latest .zip file here, create a $IP/extensions/Widgets folder and unpack the archive into there. Note: $IP stands for the root directory of your MediaWiki installation, the same directory that holds LocalSettings.php .
  2. Download the latest Smarty release and unpack it into there, too.
  3. Create a folder smarty inside the Widgets folder.
  4. Move the folder libs from the unpacked Smarty archive into Widgets/smarty.

This puts everything into expected places. You can delete the remainings of the unpacked Smarty archive.

設定

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

wfLoadExtension( 'Widgets' );

Note: The instructions above describe the newer way of installing this extension using wfLoadExtension(). If you need to install this extension on MediaWiki versions 1.28 and earlier, instead of wfLoadExtension( 'Widgets' );, you need to use:

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

フォルダーの権限

Also, the $IP/extensions/Widgets/compiled_templates/ folder should be made writable by the web server. See Making a directory writable by the webserver. The compiled templates folder 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.27.5/extensions/Widgets/compiled_templates
chmod a+rw /share/MD0_DATA/Qweb/mediawiki-1.27.5/extensions/Widgets/compiled_templates

使用法

To add a widget to your MediaWiki installation, just create a page in the Widget: namespace and then use the {{#widget:...}} parser function to include it in the pages of 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 options specifies how the parameter will be 'escaped', or encoded, in the resultant Widget. 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", which is automatically added to your wiki when you install this extension.

To see all Widgets defined in your system, you can simply 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 below 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)

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

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

ドット付き記述

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

Validate modifier

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.

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

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

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

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

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 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. 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 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 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 を使用

As of version 0.9 you can use the FlaggedRevs extension to enable a widget security review process.

This will enable the 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:

$wgWidgetsUseFlaggedRevs = true;

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

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

require_once "$IP/extensions/Widgets/Widgets.php";
require_once "$IP/extensions/FlaggedRevs/FlaggedRevs.php";

$wgFlaggedRevsNamespaces = array(NS_WIDGET);
$wgFlaggedRevTags = array(
        'security' => array( 'levels' => 1, 'quality' => 1, 'pristine' => 1 )
);

$wgFlaggedRevsOverride = true;
$wgWidgetsUseFlaggedRevs = true;

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

Since version 1.1 the widgets extension provides a parameter allowing 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 that it has the correct permissions.

名前空間 ID の変更

The default ID for the "Widget:" namespace is 274. This can be changed if you want, but make sure that it's an even number. To set the namespace ID, define a value for NS_WIDGET before you include the extension in LocalSettings.php:

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

The "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.

利用者権限

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 the editwidgets permission (the widgeteditor group is also created to add users to; see Help:User rights management for more details).

作者

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.

バージョン履歴

  • 1.3.0 (August 3, 2017) - removed I18n php shim, dropped compatibility with MW 1.22 and earlier
  • 1.2.2 (April 14, 2017) - restored compatibility with MW 1.27 and later
  • 1.2.1 (November 9, 2015) - Minor changes: improved debugging, license to show on "Special:Version"
  • 1.2.0 (April 29, 2015) - Possibility of arbitrary HTML output removed, support added for PHP 5.3
  • 1.1.0 (May 28, 2014) - i18n messages moved into JSON files, fixes for MediaWiki 1.21+, new parameter for setting the storage location of compiled widgets, removed support for PHP 5.2 and earlier
  • 1.0 (February 21, 2013) - Security leak fixed.
  • 0.10.1 (February 20, 2013) - Smarty added as a Git submodule, and updated to version 3.1.7.
  • 0.10.0 (January 19, 2012) - 'editwidgets' permission given to sysops by default, support removed for MediaWiki < 1.16.
  • 0.9.2 (January 12, 2011) - PHP fixes.
  • 0.9.1 (September 19, 2010) - Some code structure changes and fix to a bug 25219.
  • 0.9 (April 16, 2010) - 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, 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 https://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.0 (June 10, 2008) - Fixed a bug where variables were carried over from one widget to another on the same page
  • 0.7.0 (May 23, 2008) - Added support for arrays and Smarty's dotted notation
  • 0.6.0 (May 9, 2008) - Minor tweaks and bug fixes, release Makefile
  • 0.5.0 (Feb 11, 2008) - First public release

ウィジェットの投稿

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

サポート

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

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

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

トラブルシューティング

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 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 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 totally 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 contents of the page.

動画/音声用のウィジェット

Video
Audio

その他のウィジェット

もっと他のウィジェット

To get the most up-to-date list of widgets, 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 come and create a widget for that to simplify deployment. Also, these lists of extensions are a good source for action:

よくある質問

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