Pickles 2

モジュール定義

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

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

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

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

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

└─ package/ (root)
  ├─ info.json
  ├─ category1/
  │ ├─ info.json
  │ ├─ 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
  │ │
  │ ├─ module2/
  │ ├─ module3/
  │ ├─ ・・・
  │ └─ moduleN/
  │
  ├─ category2/
  ├─ category3/
  ├─ ・・・
  └─ categoryN/

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

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

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

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

  • info.json

info.json

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

下記は記述例です。

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

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

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

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

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

  • info.json

info.json

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

下記は記述例です。

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

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

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

モジュール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

info.json

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

下記は記述例です。

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

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

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

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

次の例は、フィールド main に入力されたコードを出力するテンプレートの実装例です。 {{ main }} は、 info.jsoninterface.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.jpgthumb.gifthumb.svg が利用できます。

README.html (または README.md)

モジュールに関する説明などがあれば、このファイルに記述します。

この記述は、自動生成されるスタイルガイドなどに記載されます。

pics/*.png

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

クリップモジュール

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

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

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

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

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

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

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

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

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

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

モジュールを登録する設定には、 path_module_templates_dirpath_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の一部として利用されます。添字には、半角英数字と、ハイフン、アンダースコア が使えます。

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