モジュール定義

Broccoli は、個別に設計された小さな部品 ドキュメントモジュール を組み合わせて構築するインターフェイスです。

ここでは、ドキュメントモジュールのテンプレートを定義する方法について説明します。

ディレクトリとファイルの構成

モジュールの単位とディレクトリ構成

モジュールは、次のようなディレクトリ構成で表現されます。

└─ package/ (root)
  ├─ info.json
  ├─ language.csv
  ├─ category1/
  │　├─ info.json
  │　├─ language.csv
  │　├─ module1/
  │　│　├─ README.md
  │　│　├─ info.json
  │　│　├─ template.html.twig
  │　│　├─ module.css.scss
  │　│　├─ module.js
  │　│　├─ finalize.php
  │　│　├─ finalize.js
  │　│　├─ thumb.png
  │　│　└─ pics/
  │　│　│　├─ pic1.png
  │　│　│　├─ pic2.png
  │　│　│　├─ ・・・
  │　│　│　└─ picN.png
  │　│　└─ language.csv
  │　│
  │　├─ module2/
  │　├─ module3/
  │　├─ ・・・
  │　└─ moduleN/
  │
  ├─ category2/
  ├─ category3/
  ├─ ・・・
  └─ categoryN/

この構成を元に、モジュールの識別IDが生成されます。モジュールIDは次のような形式になります。

{$mod_package}:{$mod_category}/{$mod_name}

パッケージ1つあたりのファイル構成

{$mod_package} ディレクトリには、各カテゴリディレクトリの他に、次のようなファイルで構成されます。

info.json
language.csv

info.json

このJSONファイルには、パッケージの詳細な付加情報を記述します。

下記は記述例です。

{
  "name": "パッケージの論理名称",
  "sort":[
    "category1",
    "category2"
  ],
  "hidden": false,
  "deprecated": false
}

sort には、パッケージに含まれるカテゴリのディレクトリ名を配列で指定します。ここに書かれたカテゴリは優先的に上位に表示され、指定した順番に並べられます。記述のないカテゴリは、成り行き順に最後尾に続いて表示されます。

deprecated に true を設定して、パッケージ全体を非推奨モジュールに指定できます。非推奨モジュールにすると、すでに過去に使用しているページは壊さずに、モジュールパレット上から隠し、新規に使用できなくすることができます。

hidden は、 Broccoli v0.4.8 で追加されました。 deprecated と同様、 true を設定してモジュールパレット上から隠すことができますが、非推奨のような否定的なニュアンスを含みません。

language.csv

パッケージ名を多言語に翻訳するための辞書ファイルです。この機能は、 Broccoli v0.3.22 で追加されました。

次のようなCSV形式の表として表現します。

	en	ja	zh	zh-TW
name	Package Name(en)	パッケージ名(ja)	包裹名字(zh)	包裹名字(zh-TW)

縦列は言語です。 1行目は定義行で、言語コードを定義します。最初の言語(2列目)が、デフォルトの言語として認識されます。

一番左の列は、キーです。

name: パッケージ名を表します。

カテゴリ1つあたりのファイル構成

{$mod_category} ディレクトリには、各モジュールディレクトリの他に、次のようなファイルで構成されます。

info.json
language.csv

info.json

このJSONファイルには、カテゴリの詳細な付加情報を記述します。

下記は記述例です。

{
  "name": "カテゴリの論理名称",
  "sort":[
    "module1",
    "module2"
  ],
  "hidden": false,
  "deprecated": false
}

sort には、カテゴリに含まれるモジュールのディレクトリ名を配列で指定します。ここに書かれたモジュールは優先的に上位に表示され、指定した順番に並べられます。記述のないモジュールは、成り行き順に最後尾に続いて表示されます。

deprecated に true を設定して、カテゴリ全体を非推奨モジュールに指定できます。非推奨モジュールにすると、すでに過去に使用しているページは壊さずに、モジュールパレット上から隠し、新規に使用できなくすることができます。

language.csv

カテゴリ名を多言語に翻訳するための辞書ファイルです。この機能は、 Broccoli v0.3.22 で追加されました。

次のようなCSV形式の表として表現します。

	en	ja	zh	zh-TW
name	Category Name(en)	カテゴリ名(ja)	分类名称(zh)	分類名稱(zh-TW)

縦列は言語です。 1行目は定義行で、言語コードを定義します。最初の言語(2列目)が、デフォルトの言語として認識されます。

一番左の列は、キーです。

name: カテゴリ名を表します。

モジュール1つあたりのファイル構成

{$mod_name} ディレクトリの内容は、次のようなファイルで構成されます。

template.html.twig (または template.html)
module.css (または module.css.scss)
module.js
finalize.php
finalize.js
thumb.png
info.json
README.html (または README.md)
pics/*.png
language.csv

info.json

このJSONファイルには、モジュールの詳細な付加情報を記述します。

下記は記述例です。

{
  "id": "package:category/module",
  "name": ".cols (3カラム)",
  "areaSizeDetection": "shallow",
  "enabledParents": ["pkg:cat/mod1"],
  "interface": {},
  "hidden": false,
  "deprecated": false
}

id: モジュールのIDを設定します。省略時は、ディレクトリ構成から自動的に設定されます。
パッケージ、カテゴリ、モジュールそれぞれの層のID(ディレクトリ名)を、 : と / で区切る形式で指定します。3層すべてを明示する必要はなく、例えばパッケージ名だけ省略したい場合は :category/module のように指定できます。 :/ という指定は、 3層すべてを省略したのと同じで、つまり id 属性自体を省略したのと同じ意味になります。
モジュールIDを明示しておくと、既存コンテンツのデータ構造を変更することなく、モジュールカテゴリの配置移動などをすることが可能になります。
この属性は、 Broccoli v0.3.17 で追加されました。
name: モジュールの名称を設定します。
areaSizeDetection: 編集画面でモジュールのサイズを測る方法を指定します。deep は、モジュールに含まれるすべての要素のサイズを測り、最大値を探します。shallowを指定すると、ルートノードのみのサイズを測ります。デフォルトはshallowです。
enabledParents: このモジュールを挿入できる親モジュールのIDを指定します。文字列または配列で複数指定可能です。パッケージ名は省略できます。
interface: Twigテンプレートエンジンを利用する場合に、入力欄の構造を定義します。詳しくは、モジュールテンプレートの書き方を参照してください。
hidden: true を設定して、モジュールパレット上から隠すことができます。`deprecated` と同様ですが、非推奨のような否定的なニュアンスを含みません。 Broccoli v0.4.8 で追加されました。
deprecated: true を設定して、非推奨モジュールに指定できます。非推奨モジュールにすると、すでに過去に使用しているページは壊さずに、モジュールパレット上から隠し、新規に使用できなくすることができます。

template.html.twig (または template.html)

このHTMLファイルに、テンプレートの実装を記述します。テンプレートは、部分だけを切り出した純粋なHTMLをベースに、フィールド(変更可能な箇所を定義するメタ構文)を埋め込むような形式で記述していきます。

ファイル名 template.html.twig で定義されたモジュールは、 Twigテンプレート言語によって記述します。

次の例は、フィールド main に入力されたコードを出力するテンプレートの実装例です。 {{ main }} は、 info.json の interface.fields.main に設定された値を参照します。

<!-- template.html.twig の実装例 -->
<div class="sample_module">
    <div class="sample_module-inner">
{{ main }}
    </div>
</div>

利用可能なフィールドについては、フィールド一覧のページを参照してください。

template.html.twig の代わりに、template.html を設置する場合、Broccoli標準のテンプレート記法で記述します。

<!-- template.html の実装例 -->
<div class="sample_module">
    <div class="sample_module-inner">
{&{"module":{"name":"main"}}&}
    </div>
</div>

テンプレートエンジンの選択と記述方法について詳しくは、モジュールテンプレートの書き方を参照ください。

module.css (または module.css.scss)

モジュールに関連するスタイルシートを記述します。ファイル名の最後に .scss を付加すると、SCSS形式で記述することができます。

// module.css.scss の実装例
.sample_module{
    border: 1px solid #999;
    padding: 15px;
    margin:1em 0;
    &-inner{
        padding: 0;
        margin: 0;
    }
}

ここに書かれたスタイルは、Pickles 2 用のプラグイン px2-px2dthelper によって収集・統合し、テーマから自動的に読み込むことができます。

module.js

モジュールの動作に関連するスクリプトを記述します。

ここに書かれたスクリプトは、 Pickles 2 用のプラグイン px2-px2dthelper によって収集・統合し、テーマから自動的に読み込むことができます。

finalize.php

ビルドされたモジュールのHTMLコードを、最終的な完成コードに加工するスクリプトを追加します。

例えば、マークダウン記法で作られたシンプルなリスト要素に、クラス名を与えて複雑な装飾を行いたい場合などに利用できます。

<?php
/**
 * finalize.php
 */
return function( $html, $supply ){
    $data = $supply['data']; // モジュールに入力されたデータが供給される。

    /* ここに $html を加工するコードを書く。 */

    return $html;
};

finalize.php は、broccoli-html-editor-php エンジンで使用できます。 (旧エンジン broccoli-html-editor では、代わりに finalize.js が呼び出されます)

finalize.js

finalize.js は、JS版エンジン broccoli-html-editor 使用時に finalize.php の代わりに呼び出される加工スクリプトです。

/**
 * finalize.js
 */
module.exports = function(html, callback, supply){
    var data = supply['data']; // モジュールに入力されたデータが供給される。
    var cheerio = supply['cheerio'];// ← broccoli-html-editor からリソースとして供給される "cheerio" を利用.

    /* ここに html を加工するコードを書く。 */

    // 完成したHTMLは、callback() に渡して返します。
    callback(html);
    return true;
}

thumb.png

thumb.png は、GUI編集画面上での、モジュールのサムネイルとして使用されます。

縦横比 1:1 の画像を登録してください。大きさについては特に規定はありませんが、500px前後で作成されていれば十分でしょう。

thumb.png の他にも、thumb.jpg、thumb.gif、thumb.svg が利用できます。

README.html (または README.md)

モジュールに関する説明を、このファイルに記述します。この記述は、自動生成されるスタイルガイドなどに記載されます。

ファイル名に言語コードを加え README-en.md や README-en.html とすると、各言語向けの説明を書き分けることができます。READMEの多言語対応機能は Broccoli v0.5.0 で追加されました。

pics/*.png

picsディレクトリに置かれた画像は、README.html(.md) と共にスタイルガイドなどに表示されます。モジュール名だけでは内容を把握しにくかったり、微妙に異なる他のモジュールと区別しなければならない場合などに、ユーザーの判断を助けるヒントとして活用できます。

language.csv

モジュール名やフィールド名を多言語に翻訳するための辞書ファイルです。この機能は、 Broccoli v0.3.22 で追加されました。

次のようなCSV形式の表として表現します。

	en	ja	zh	zh-TW
name	Module Name(en)	モジュール名(ja)	模块名称(zh)	模塊名稱(zh-TW)
fields.fieldname:label	Field Label(en)	フィールドラベル(ja)	字段标签(zh)	字段標籤(zh-TW)
subModule.fieldname.submodname:label	Field Label(en)	フィールドラベル(ja)	字段标签(zh)	字段標籤(zh-TW)

縦列は言語です。 1行目は定義行で、言語コードを定義します。最初の言語(2列目)が、デフォルトの言語として認識されます。

一番左の列は、キーです。

name: モジュール名を表します。
fields.{$fieldname}:label: フィールドラベルを表します。
subModule.{$fieldname}.{submodname:label}:label: サブモジュールのフィールドラベルを表します。

その他、フィールドの種類毎に、多言語化のためのキーが定義されている場合があります。例えば、 selectフィールドは、オプションラベルの多言語化をサポートしています。詳しくは各フィールドの説明を参照してください。

クリップモジュール

クリップモジュールは、特殊なモジュール形態です。

他のモジュールを組み合わせて予めプリセットを構成し、コンテンツに配置することができます。

template.html を置かず、代わりに clip.json を設置すると、クリップモジュールとして認識されます。

clip.json の編集手順は次の通りです。

任意のコンテンツをGUI編集します。
クリップしたいインスタンスを選択し、コピーします。この操作で、JSON形式のテキストがクリップボードにコピーされます。
この状態で clip.json を開き、ペーストします。

モジュールをプロジェクトに登録する

モジュールの定義ができたら、プロジェクト共有設定(config.php)画面からモジュールとして登録します。

プロジェクト共有設定(`config.php`)画面を開く

サブメニュー内にある 設定 > プロジェクト共有設定(config.php) を開きます。Pickles 2 のプロジェクト共有設定は、./px-files/config.php に保存されています。

Pickles 2 アプリケーションに関する設定は、Pickles 2 プロジェクトのプロジェクト共有設定から $conf->plugins->px2dt に記述します。

モジュールを登録する設定には、 path_module_templates_dir と path_module_templates_dir があります。

`path_module_templates_dir` にモジュールディレクトリを設定

次の例を参考に、path_module_templates_dir 欄にモジュールのパスを設定してください。

$conf->plugins->px2dt->path_module_templates_dir = "./px-files/modules/";

path_module_templates_dir ディレクトリの直下に配置されたディレクトリをパッケージとして認識します。複数のパッケージを一度に登録することができます。

`paths_module_template` にパッケージを登録

または、ばらばらの場所にあるパッケージを個別に登録することもできます。次の例を参考に、paths_module_template 欄にモジュールのパスを設定してください。

$conf->plugins->px2dt->paths_module_template = [
  "SELF" => "./px-files/resources/module_templates/"
];

モジュールのセットは、1つのプロジェクトにつき複数登録することができます。

paths_module_template の添字(上記の例では、SELF の部分)は、モジュールのIDの一部として利用されます。添字には、半角英数字と、ハイフン、アンダースコアが使えます。

コンテンツに使用した後から変更すると、モジュール構造が壊れ、作成済みのコンテンツが失われる場合がありますので注意してください。より詳しい注意事項については、モジュールメンテナンスに関する注意事項を参照してください。

ページの先頭へ戻る

モジュール定義

ディレクトリとファイルの構成

モジュールの単位とディレクトリ構成

パッケージ1つあたりのファイル構成

info.json

language.csv

カテゴリ1つあたりのファイル構成

info.json

language.csv

モジュール1つあたりのファイル構成

info.json

template.html.twig (または template.html)

module.css (または module.css.scss)

module.js

finalize.php

finalize.js

thumb.png

README.html (または README.md)

pics/*.png

language.csv

クリップモジュール

モジュールをプロジェクトに登録する

プロジェクト共有設定(config.php)画面 を開く

path_module_templates_dir にモジュールディレクトリを設定

paths_module_template にパッケージを登録

プロジェクト共有設定(`config.php`)画面を開く

`path_module_templates_dir` にモジュールディレクトリを設定

`paths_module_template` にパッケージを登録