Extension:Graph

もっとも簡便にグラフを追加するには、既存の{{Graph:Chart}}などのテンプレートを使います。これらのテンプレートはVegaの複雑さを見ずに済みます。熟練のユーザーならグラフ用サンドボックスでグラフが作成できます。グラフのサンドボックスでは、JSON に加えてウィキのテンプレート構文を使用できます。

有用なリンク

Guide - ウィキでグラフを使う方法の標準的な推奨。
Interactive Tutorial - ゼロから複雑でインタラクティブなグラフ完成まで、段階的に解説する説明書。
Demo page - サンプルや使用法のトリックを解説。
TechTalk Video - ウィキメディア財団技術部門の議論。グラフ拡張機能を取上げ、Lyra エディタをわかりやすくデモしている。（on 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」に移動して、拡張機能が正しくインストールされたことを確認します。

MediaWiki 1.24 以前を稼働させている利用者へ:

上記の手順では、wfLoadExtension() を使用してこの拡張機能をインストールする新しい方法を記載しています。この拡張機能をこれらの過去のバージョン (MediaWiki 1.24 以前) にインストールする必要がある場合は、wfLoadExtension( 'Graph' ); の代わりに以下を使用する必要があります:

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

表の例

サンプルや使用法の裏技はデモのページを参照してください。

Historical Fertility Rates

外部データ

HTTP(S)を使ってグラフのデータを取得することはできません。代わりにwikiraw:やwikiapi:等、固有のウィキ・プロトコルを使用してください。

Graphoidサービスとグラフ拡張機能はGraphAllowedDomains設定を用いてプロトコルの解決を設定します。

$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 upscaling on most browsers can be blurry by default. Set the appropriate image-rendering property to solve.

内部リンク

解析をすると、グラフ拡張機能はテンプレートのパラメータや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サービスを示す。

グラフ拡張機能の設定がインタラクティブであり、クライアントのブラウザで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 を構成する書式文字列。例えば:

"//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 サービス

この節はwikitech:Graphoidを参照し同調するべきものとします。

Graphoid（git repo）とはnode.js サービスであり、先進的なブラウザで使用されるのと等しいVegaライブラリ・コードを採用し、グラフの定義から静的なPNG形式の画像に変換します。 The reason Graphoid was initially developed was to provide a static image so we wouldn't have to bundle Vega and d3 resource loader modules with every page response. See phab:T211881 for more details. このサービスはウィキメディアのクラスタ上のgraphoid.wikimedia.orgによって提供されます。

ユーザー自身によるインストールが可能です。

$ git clone https://gerrit.wikimedia.org/r/mediawiki/services/graphoid
$ cd graphoid
$ npm install
$ npm start

各サービスURLにはページのドメイン名（例＝mediawiki.org）とサービスのバージョン（v1）、グラフが載ったページの題名（PageTitle）とページの更新ID（12345等だが現状は0もあり）、さらにグラフ自体の隠しIDが書かれています（グラフ定義を認識するためHTMLでも使用）。例を挙げるとすると:

http://localhost:6927/mediawiki.org/v1/PageTitle/12345/a64b022a8fa5b7fc5e40a2c95cd0a114b2ae1174.png
http://graphoid.wikimedia.org/mediawiki.org/v1/png/Extension:Graph/0/be66c7016b9de3188ef6a585950f10dc83239837.png

グラフ拡張機能を定義、LocalSettings.phpにおいてGraphoidサービスを線と同時に用いる例

$wgGraphImgServiceUrl = "//localhost:6927/%1\$s/v1/%2\$s/%3\$s/%4\$s.png";
$wgGraphImgServiceUrl = "//graphoid.wikimedia.org/%1\$s/v1/png/%2\$s/%3\$s/%4\$s.png";

Configure graphoid services

グラフ拡張機能のワークフロー

このサービスはconfigファイルを使ってさらに設定ができます。

ビジュアルエディターのモジュール

2015年の夏以降、グラフ拡張機能にはVisualEditorを使ってグラフを編集するモジュール（ext.graph.VisualEditor）が付与されました。

このモジュールは「Google Summer of Code 2015」プロジェクトの成果です。詳細は phab:T89287 を参照してください。

ユーザーはこのモジュールを使い、外部の拡張機能ノードに頼らずとも、VisualEditor内でグラフを見ることができます。ユーザーはさらに、グラフの形式、データやパディングを編集するダイアログを開くことができます。ユーザーインタフェース（UI）ではさらに、ウィキテキスト・エディターに切り替えなくてもビジュアルエディター上でグラフの生JSON定義を直接、編集できます。熟練したユーザーなら、これを使ってUIのサポートしない設定の微調整も可能です。

この第1ステップは、ビジュアルエディター内でどのようなグラフ編集ができるかという試金石になり、またモジュールとして改善したり伸展する方法が十分にあります。

この拡張機能は 1 つ以上のウィキメディアのプロジェクトで使用されています。これはおそらく、この拡張機能が安定していて高いトラフィックのウェブサイトでも十分に動作することを意味します。この拡張機能がインストールされている場所を確認するには、ウィキメディアの設定ファイル CommonSettings.php および InitialiseSettings.php 内で、この拡張機能の名前を探してください。特定のウィキにインストールされている拡張機能の完全な一覧は、そのウィキの Special:Version ページにあります。