Phabricator のプロジェクト名 #graph

Extension:Graph/ja

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

Other languages:
English • ‎français • ‎occitan • ‎中文 • ‎日本語 • ‎한국어
かつて、この拡張機能と同名で2006年以降は使用されず、既に廃止された旧グラフ拡張機能(graph extension)がありました。
MediaWiki 拡張機能マニュアルManual:Extensions
Crystal Clear action run.svg
Graph

リリースの状態:Extension status ベータ

実装Template:Extension#type Tag, ContentHandler
説明Template:Extension#description Data-driven graphs
作者Template:Extension#username Yuri Astrakhan (Yurik talk), Dan Andreescu, Frédéric Bolduc
ライセンスTemplate:Extension#license MIT License
ダウンロード
使用するフックTemplate:Extension#hook
ParserFirstCallInitManual:Hooks/ParserFirstCallInit

translatewiki.net で翻訳を利用できる場合は、Graph 拡張機能の翻訳にご協力ください

使用状況とバージョン マトリクスを確認してください。

問題点Phabricator

未解決のタスク · バグを報告

グラフ拡張機能は<graph>タグを用いてデータの画像化をJSONで記述しレンダリングします。棒グラフ、円グラフ、タイムテーブル(年表)やヒストグラム(demo)をVega宣言型プログラミングで生成します。

全般的な情報

グラフ拡張機能は強力なVega宣言型プログラムのグラフをウィキページに加えます。グラフは静的と動的のどちらの形式も扱います。

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

有用なリンク

インストール

  • VagrantMediaWiki-Vagrant を使用している場合は、vagrant roles enable graph --provision でインストールしてください
手動インストール
  • 以下のコードを LocalSettings.php の末尾に追加します:
    wfLoadExtension( 'Graph' );
    
  • YesY 完了 – ウィキの「Special:Version」に移動して、拡張機能が正しくインストールされたことを確認します。

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

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

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

表の例

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

Historical Fertility Rates
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' ],
];

既知のバグと制限

内部リンク

解析をすると、グラフ拡張機能はテンプレートのパラメータや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ライセンスの修正版容認の範囲で使用できるものとして配布されます。

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日)、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形式の画像に変換します。 このサービスはウィキメディアのクラスタ上の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";
グラフ拡張機能のワークフロー

このサービスは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 — データ駆動型ドキュメント