Phabricator のプロジェクト名 #Graphs

Extension:Graph

From MediaWiki.org
Jump to navigation Jump to search
This page is a translated version of the page Extension:Graph and the translation is 94% complete.

Other languages:
English • ‎español • ‎français • ‎occitan • ‎русский • ‎中文 • ‎日本語 • ‎한국어
MediaWiki 拡張機能マニュアル
OOjs UI icon advanced.svg
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 に加えてウィキのテンプレート構文を使用できます。

有用なリンク

インストール

  • Vagrant を使用している場合は、vagrant roles enable graph --provision でインストールしてください
手動インストール
  • JsonConfig 拡張機能が必要
  • ダウンロードして、ファイルを extensions/ フォルダー内の Graph という名前のディレクトリ内に配置します。
  • 以下のコードを LocalSettings.php の末尾に追加します:
    wfLoadExtension( 'Graph' );
    
  • Yes 完了 – ウィキの「Special:Version」に移動して、拡張機能が正しくインストールされたことを確認します。

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

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

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

表の例

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

Historical Fertility Rates
Historical Fertility Rates

外部データ

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

内部リンク

解析をすると、グラフ拡張機能はテンプレートのパラメータやexpressionsをすべて開き、グラフのハッシュを識別子に使うと完全なグラフ定義をgraph_specsページのプロパティとして保存。 このことから、ウィキのグラフを検索するときSpecial:PageWithPropsthe 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ライセンスの修正版容認の範囲で使用できるものとして配布されます。

600

設定

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日)、wgGraphDataDomainse0813f85aから削除(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 を参照してください。

Ve-graph-showcase.png

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

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

関連項目

  • Extension:GraphViz — エッジ(枝)で結ばれた複数のノード(頂点)のグラフを表示(このページで解説した拡張機能の表形式ではない)
  • Plotly — オープンソースのJavaScriptグラフ作成ライブラリ(3D作表も可能)
  • D3 — データ駆動型ドキュメント