Extension:Graph
 リリースの状態: 安定 |
|
|---|---|
| 実装 | タグ, ContentHandler |
| 説明 | Data-driven graphs |
| 作者 | Yuri Astrakhan (Yurik トーク), Dan Andreescu, Frédéric Bolduc |
| ライセンス | MIT ライセンス |
| ダウンロード | |
|
|
| translatewiki.net で翻訳を利用できる場合は、Graph 拡張機能の翻訳にご協力ください | |
| 問題点 | 未解決のタスク · バグを報告 |
Graph (グラフ) 拡張機能は <graph> タグを用いてデータの画像化をJSONで記述しレンダリングします。棒グラフ、円グラフ、タイムテーブル（年表）やヒストグラム（demo）をVega宣言型プログラミングで生成します。
全般的な情報
グラフ拡張機能は強力なVega宣言型プログラムのグラフをウィキページに加えます。グラフは静的と動的のどちらの形式も扱います。
もっとも簡便にグラフを追加するには、既存の{{Graph:Chart}}などのテンプレートを使います。 これらのテンプレートはVegaの複雑さを見ずに済みます。 熟練のユーザーならグラフ用サンドボックスでグラフが作成できます。 グラフのサンドボックスでは、JSON に加えてウィキのテンプレート構文を使用できます。
有用なリンク
- Vega 2 documentation - restored Vega 2 documentation pages.
- Guide - ウィキでグラフを使う方法の標準的な推奨。
- Interactive Tutorial - ゼロから複雑でインタラクティブなグラフ完成まで、段階的に解説する説明書。
- デモ ページ - サンプルや使用法のトリックを解説。
- TechTalk 動画 - ウィキメディア財団技術部門の議論。グラフ拡張機能を取上げ、Lyra エディターを分かりやすくデモしている (labsにも合わせてインストールする)。
- 興味があれば、Vegaの将来的な機能の動画も参照できる（Jeffrey Heerの基調講演）。
- 開発者のための Vega 解説 - Vegaのリソースを探すならこちらが最適。
- Vega 2.0 への移行
- 対話的な Vega の紹介動画
インストール
- Vagrant を使用している場合は、
vagrant roles enable graph --provisionでインストールしてください
- 手動インストール
- JsonConfig拡張機能が必要
- ダウンロードして、ファイルを
extensions/フォルダー内のGraphという名前のディレクトリ内に配置します。 - 以下のコードを LocalSettings.php の末尾に追加します:
wfLoadExtension( 'Graph' );
完了 – ウィキの「Special:Version」に移動して、拡張機能が正しくインストールされたことを確認します。
Additional config setup
If you are looking to replicate a production environment like en.wiki you will need to complete the following steps:
Roles
- Enable graphs role
- Enable scribunto role
- Enable imagemap role
Templates and Lua Modules
- Copy Module:Graph locally
- Copy Module:Graph/doc locally
- Copy Template:Nowrap locally
- Copy Module:Chart locally
- Copy Module:Chart/Default_colors locally.
- Copy File:Circle_frame.svg locally
表の例
サンプルや使用法の裏技はデモのページを参照してください。
User defined fallback
When using client side rendering, it is possible to use Wikimedia Commons to provide a static fallback image to noscript users.
This is a temporary solution until a new service is put in place to provide server side rendering to replace the soon to be decomissioned Graphoid service.
The user must first upload the static graph to Wikimedia Commons.
Fallback images have two variables fallback and fallbackWidth.
fallback relates to a Wikimedia Commons filename.
fallbackWidth is the fallback images width in pixels.
These variables are pass through the graph in the following way:
<graph fallback="Graph test seddon.png" fallbackWidth=450>
Where lua modules are used such as Module:Graph then these variables can be provided via the tag function. If Template:Graph:Chart were adapted, it would look like this:
{{safesubst:#tag:graph|{{safesubst:#invoke:Graph|chartWrapper}} | fallback = {{{fallback|''}}} | fallbackWidth= {{{fallbackWidth|''}}} }}
It would then be utilised in a template in the following manner:
{{Graph:Chart|width=400|height=100|xAxisTitle=X|yAxisTitle=Y
|type=rect|x=1,2,3,4,5,6,7,8|y=10,12,6,14,2,10,7,9|fallback=Graph test seddon.png|fallbackWidth=450}}
If a fallbackWidth isn't provided but an image is defined then the extension will derive the width from the provided graph width. The reason for this is there is frequently a difference in the rendered image width and the actual image width.
{{Graph:Chart|width=400|height=100|xAxisTitle=X|yAxisTitle=Y
|type=rect|x=1,2,3,4,5,6,7,8|y=10,12,6,14,2,10,7,9|fallback=Graph test seddon.png}}
外部データ
HTTP(S)を使ってグラフのデータを取得することはできません。
代わりにwikiraw:やwikiapi:等、固有のウィキ・プロトコルを使用してください。
Graphoidサービスとグラフ拡張機能はGraphAllowedDomains設定を用いてプロトコルの解決を設定します。
Note that because queries rely on the structure of wikibase items, they may suddenly stop working if the underlying data is edited and changes, as it may yield incomplete, empty or invalid data that can't be used to create a graph. In these cases the graph will end up empty (see phab:T168601).
$wgGraphAllowedDomains = [
# http + httpsキーで外部のデータアクセスが認められるドメインをすべて一覧にします。
# ここに列記したドメインはサブドメインもすべて容認します。
# 〈wikiraw〉のような特製のプロトコルは、どのプロトコルを選ぶべきか調べるために用います。
# こうするとwikiraw://en.wikipedia.org/Pageはhttps://en.wikipedia.org/w/api.php?action=query&titles=Page&...を呼び出すapiのリクエストになる
'https' => [ 'wikipedia.org', 'wikimedia.org', ... ],
'http' => [ 'wmflabs.org', ... ],
# wikirawuploadに用いることが承認されたドメイン一覧: プロトコルにアクセス。
# 完全一致のみ。サブドメインは対象外。
'wikirawupload' => [ 'upload.wikimedia.org' ],
# wikirawuploadと同値だがウィキデータSparqlクエリ用
'wikidatasparql' => [ 'query.wikidata.org' ],
];
既知のバグと制限
- グラフ拡張機能のバグ
- Graphoidサービスのバグ
- ISO 8601タイムスケールの実装に失敗。したがってタイムラインではグレゴリオ暦のみ使用可能。
- ほとんどのブラウザーで、既定では画像の拡大はぼやけている場合があります。 解決するにはimage-rendering属性を適正に設定します。
内部リンク
解析をすると、グラフ拡張機能はテンプレートのパラメータやexpressionsをすべて開き、グラフのハッシュを識別子に使うと完全なグラフ定義をgraph_specsページのプロパティとして保存。
このことから、ウィキのグラフを検索するときSpecial:PageWithPropsかthe action APIを用いると簡単に見つけることができます。
グラフ拡張機能はページ上のどこにグラフを配置するか、HTML形式で、<img>タグを含む<div>を出力。
サンプル:
<div class="mw-wiki-graph-container">
<img class="mw-wiki-graph-img"
src="/api/rest_v1/page/graph/png/Extension%3AGraph%2FDemo/1686336/d243aa924db2f82926e0f317217fcce591fe8cd4.png" />
</div>
<img>タグのhref属性は静的なグラフの画像を提供する#Graphoidサービスを示す。
Graph 拡張機能が対話機能用に構成されていて、クライアント ブラウザーで JavaScript が有効になっていて、ResourceLoader が JavaScript を提供していないレガシー ブラウザーではない場合、クライアント ブラウザーはその場でグラフをレンダリングします。
グラフ拡張機能はResourceLoaderのJavaScriptモジュールとしてVegaライブラリを含むページに ext.graph を呼び込み、グラフ定義のJSONを通称 wgGraphSpecs と呼ばれるJavaScript mediaWiki.config変数に組み込む。
このモジュールがクライアントのブラウザに読み込まれると、Vega JavaScriptライブラリは<div>を個別のHTMLキャンバスに取り込み、その中にグラフを描画すると静止画像と置き換えます。
2015年11月時点では、ウィキメディアのウィキでは編集のプレビュー以外で、このインタラクティブなレンダラを有効にしていません。
ユーザーはグラフ拡張機能を設定し、常時<img>タグのみ使用するがVegaライブラリやグラフ定義のJSONを参照しないようにできます。
このモジュールはpage_propsが保存後まで更新されないため、編集作業中には作動しません。
一旦保存すると、GraphoidサービスはアクションAPI経由で新しいグラフ定義にアクセスできます。
セキュリティ機能
信用できないデータソース参照を許可しないように、<graph>を設定できます（例: ウィキメディアではウィキメディアのサイト内のデータのみ許可）。
また外部データにアクセスするたびに追加の見出しを送ることができ、例えばTreat-as-Untrusted見出しにより、MediaWikiはCSRF攻撃を予防します。
ライセンス
VegaライブラリはBSDライセンスの修正版容認の範囲で使用できるものとして配布されます。
| “ | BSDライセンスの複写に（容認できる範囲の）微調整を加えたようにも見えます。 使用に際して問題はありませんが、このような変更をライセンスに加えないと理想的です。 ライセンスがオープンソースの使用について安全かどうかという（このような）混乱を防ぐためにも、ライセンス条件にこのような改変を行うことは好ましくありません。 | ” |
—Stephen LaPorte | ||
設定
wgGraphIsTrusted
もしfalse（既定）なら、Treat-as-Untrustedを返す。つまりヘッダ1件にあらゆるグラフデータのリクエストが対応
wgGraphImgServiceUrl
<img> タグ向けのバックエンド サービス要求 URL を構成する書式文字列。 例えば:
$wgGraphImgServiceUrl = "//graphoid.wikimedia.org/%1\$s/v1/png/%2\$s/%3\$s/%4\$s.png";
このURLを出力:
//graphoid.wikimedia.org/mediawiki.org/v1/png/Extension:Graph/0/be66c7016b9de3188ef6a585950f10dc83239837.png
/{domain}/v1/png/{title}/{revid}/{hash}.png
パラメータの出力順: 1=サーバ、2=題名、3=revid、4=graph-hash-id。
どのパラメータもrawurlencode()を用いて回避できる。
値がfalseの場合（既定）<noscript> urlはまったく生成されない
その他の変数
wgGraphUrlBlacklist変数を787d64a11から削除（2015年12月7日）。
wgGraphDataDomainsはe0813f85aから削除（2016年1月28日）。wgGraphAllowedDomainsを用いること。
wgGraphUserServiceAlways変数はb735f63ff4bから削除（2015年9月30日）。
グラフ名前空間の有効化
JsonConfigを設定すると、グラフの設定を単独ページとしてそれぞれの名前空間に保管できます。
// See https://www.mediawiki.org/wiki/Extension:JsonConfig
$wgJsonConfigModels['graph.jsonconfig'] = 'graph\Content';
$wgJsonConfigs['graph.jsonconfig'] = array(
'namespace' => <PICK-A-NS-NUMBER>,
'nsName' => 'Graph',
'isLocal' => true,
);
Graphoid サービス
 警告: | WMF によるGraphoid のメンテナンスは終了しており、ウィキメディアのウィキでは近い将来、廃止されます。 |
Graphoid（git repo）とはnode.js サービスであり、先進的なブラウザーで使用されるのと等しいVegaライブラリ コードを採用し、グラフの定義から静的な PNG 形式の画像に変換します。 そもそもGraphoidが開発された理由は、静止画を提供してページごとにVega ならびに d3 リソースローダーのモジュールをバンドルする必要を解消するためでした。 詳細は phab:T211881 を参照してください。 このサービスはウィキメディアのクラスタ上のhttps://www.mediawiki.org/api/rest_v1/#/Page%20content/get_page_graph_png__title___revision___graph_id_によって提供されます。
ユーザー自身によるインストールが可能です。
$ sudo apt-get install libcairo2-dev libjpeg8-dev libpango1.0-dev libgif-dev build-essential g++
$ git clone https://gerrit.wikimedia.org/r/mediawiki/services/graphoid
$ cd graphoid
$ npm install
$ npm start
(注記：このパッケージはメンテナンスが継続しておらず(phab:T211881、インストールが失敗する場合は phab:T196001と phab:T239100を参照。npm i --build-from-source も参照。)
各サービスURLにはページのドメイン名（例＝mediawiki.org）とサービスのバージョン（v1）、グラフが載ったページの題名（PageTitle）とページの更新ID（12345等だが現状は0もあり）、さらにグラフ自体の隠しIDが書かれています（グラフ定義を認識するためHTMLでも使用）。例を挙げるとすると:
http://localhost:6927/mediawiki.org/v1/PageTitle/12345/a64b022a8fa5b7fc5e40a2c95cd0a114b2ae1174.png (deprecated url)
グラフ拡張機能を定義、LocalSettings.phpにおいてGraphoidサービスを線と同時に用いる例
$wgGraphImgServiceUrl = "//localhost:6927/%1\$s/v1/%2\$s/%3\$s/%4\$s.png"; //deprecated path, older versions only
$wgGraphImgServiceUrl = "//graphoid.wikimedia.org/%1\$s/v1/png/%2\$s/%3\$s/%4\$s.png"; //deprecated path, older versions only
graphoid サービスを設定
このサービスはconfigファイルを使ってさらに設定ができます。
ビジュアルエディターのモジュール
2015年の夏以降、Graph 拡張機能にはビジュアルエディターを使ってグラフを編集するモジュール (ext.graph.VisualEditor) が付与されました。
このモジュールは「Google Summer of Code 2015」プロジェクトの成果です。 詳細は phab:T89287 を参照してください。
ユーザーはこのモジュールを使い、外部の拡張機能ノードに頼らずとも、VisualEditor内でグラフを見ることができます。 ユーザーはさらに、グラフの形式、データやパディングを編集するダイアログを開くことができます。 ユーザーインタフェース（UI）ではさらに、ウィキテキスト・エディターに切り替えなくてもビジュアルエディター上でグラフの生JSON定義を直接、編集できます。熟練したユーザーなら、これを使ってUIのサポートしない設定の微調整も可能です。
この第1ステップは、ビジュアルエディター内でどのようなグラフ編集ができるかという試金石になり、またモジュールとして改善したり伸展する方法が十分にあります。
| この拡張機能は 1 つ以上のウィキメディアのプロジェクトで使用されています。 これはおそらく、この拡張機能が安定していて高いトラフィックのウェブサイトでも十分に動作することを意味します。 この拡張機能がインストールされている場所を確認するには、ウィキメディアの設定ファイル CommonSettings.php および InitialiseSettings.php 内で、この拡張機能の名前を探してください。 特定のウィキにインストールされている拡張機能の完全な一覧は、そのウィキの Special:Version ページにあります。 |
関連項目
- Extension:GraphViz — エッジ（枝）で結ばれた複数のノード（頂点）のグラフを表示（このページで解説した拡張機能の表形式ではない）
- Plotly — オープンソースのJavaScriptグラフ作成ライブラリ（3D作表も可能）
- D3 — データ駆動型ドキュメント