broccoli-html-editor

broccoli-html-editor は、GUIベースでHTMLを編集するブロックエディタライブラリです。断片化されたHTMLの部品(モジュール)をドラッグ＆ドロップ操作で組み合わせて、ウェブページを構成できます。

インストール - Install

$ composer require broccoli-html-editor/broccoli-html-editor

使い方 - Usage

サーバー側 - Server side (PHP)

/path/to/broccoli_api.php にAPIを設置する例です。

<?php
require_once('path/to/vendor/autoload.php');

$broccoli = new broccoliHtmlEditor\broccoliHtmlEditor();
$broccoli->init(
    array(
        'appMode' => 'web', // 'web' or 'desktop'. default to 'web'
        'paths_module_template' => array(
            'testMod1' => '/realpath/to/modules1/' ,
            'testMod2' => '/realpath/to/modules2/'
        ) ,
        'documentRoot' => '/realpath/to/www/htdocs/', // realpath
        'pathHtml' => '/path/to/your_preview.html',
        'pathResourceDir' => '/path/to/your_preview_files/resources/',
        'realpathDataDir' => '/realpath/to/www/htdocs/path/to/your_preview_files/guieditor.ignore/',
        'customFields' => array(
            // カスタムフィールドを実装します。
            // このクラスは、 `broccoliHtmlEditor\\fieldBase` を基底クラスとして継承します。
            // customFields のキー(ここでは custom1)が、フィールドの名称になります。
            'custom1' => 'broccoli_class\\field_custom1'
        ) ,
        'fieldConfig' => array(
            'image' => array( // image field に対する設定
                'filenameAutoSetter' => 'ifEmpty', // filenameAutoSetterの初期値を設定
            ),
        ),
        'bindTemplate' => function($htmls){
            $fin = '';
            $fin .= '<!DOCTYPE html>'."\n";
            $fin .= '<html>'."\n";
            $fin .= '    <head>'."\n";
            $fin .= '        <title>sample page</title>'."\n";
            $fin .= '    </head>'."\n";
            $fin .= '    <body>'."\n";
            $fin .= '        <div data-contents="main">'."\n";
            $fin .= $htmls['main']."\n";
            $fin .= '        </div><!-- /main -->'."\n";
            $fin .= '        <div data-contents="secondly">'."\n";
            $fin .= $htmls['secondly']."\n";
            $fin .= '        </div><!-- /secondly -->'."\n";
            $fin .= '    </body>'."\n";
            $fin .= '</html>';

            return $fin;
        },
        'log' => function($msg){
            // エラー発生時にコールされます。
            // msg を受け取り、適切なファイルへ出力するように実装してください。
            error_log('[ERROR HANDLED]'.$msg, 3, '/path/to/error.log');
        },
        'userStorage' => function($key, $val = null){
            // ユーザー固有の情報を読み書きします。
            $args = func_get_args();
            if( count($args) == 1 ){
                // 読み取りとしてコールされる場合、引数が1つだけ提供されます。
                return file_get_contents('/path/to/userdir/'.urlencode($key).'.json');
            }else{
                // 書き込みの要求の場合、引数が2つ提供されます。
                return file_put_contents('/path/to/userdir/'.urlencode($key).'.json', $val);
            }
        }
    )
);


$rtn = $broccoli->gpi(
    $_REQUEST['api'],
    json_decode($_REQUEST['options'], true)
);
echo json_encode($rtn);
exit;

APIの一覧はこちらを参照ください。

PHPの要件

PHP 7.3 以上
- mbstring PHP Extension
- JSON PHP Extension

モジュールやカスタムフィールドなど他のパッケージとの構成によって、いくつかの要件が追加される場合があります。依存パッケージのシステム要件も確認してください。

クライアント側 - Client side JavaScript

<div id="canvas" data-broccoli-preview="http://127.0.0.1:8081/path/to/your_preview.html"></div>
<div id="palette"></div>
<div id="instanceTreeView"></div>
<div id="instancePathView"></div>

<!-- jQuery -->
<script src="/path/to/jquery/jquery.js"></script><!-- <- option; not required -->

<!-- broccoli -->
<script src="/path/to/broccoli-html-editor/client/dist/broccoli.js"></script>
<script>
var broccoli = new Broccoli();
broccoli.init(
    {
        'elmCanvas': document.getElementById('canvas'),
        'elmModulePalette': document.getElementById('palette'),
        'elmInstanceTreeView': document.getElementById('instanceTreeView'),
        'elmInstancePathView': document.getElementById('instancePathView'),
        'lang': 'en', // language
        'appearance': 'dark', // light, dark, auto(default)
        'contents_area_selector': '[data-contents]',
            // ↑編集可能領域を探すためのクエリを設定します。
            // 　この例では、data-contents属性が付いている要素が編集可能領域として認識されます。
        'contents_bowl_name_by': 'data-contents',
            // ↑bowlの名称を、data-contents属性値から取得します。
        'customFields': {
            'custom1': function(broccoli){
                // カスタムフィールドを実装します。
                // この関数は、fieldBase.js を基底クラスとして継承します。
                // customFields オブジェクトのキー(ここでは custom1)が、フィールドの名称になります。
            }
        },
        'customValidationRules': {
            'customValidation1': function(value, req, attribute, passes) {
                // カスタムバリデーションを定義します。
                // フィールドの validate に登録して呼び出すことができます。
                var ok = true;
                if( ok ){
                    passes(); // if available
                }else{
                    passes(false, 'The '+attribute+' is not valid.'); // if not available
                }
            }
        },
        'gpiBridge': function(api, options, callback){
            // GPI(General Purpose Interface) Bridge
            // broccoliは、バックグラウンドで様々なデータ通信を行います。
            // GPIは、これらのデータ通信を行うための汎用的なAPIです。
            $.ajax({
                "url": "/path/to/broccoli_api.php",
                "type": 'post',
                'data': {
                    'api': api ,
                    'options': JSON.stringify(options)
                },
                "success": function(data){
                    callback(data);
                }
            });
            return;
        },
        'clipboard': {
            // クリップボード操作の機能を拡張できます。
            // 通常のクリップボード処理では対応できない特殊な環境で利用する場合に拡張してください。
            // 省略した場合は、Broccoliの標準的な処理が適用されます。
            'set': function( data, type, event, callback ){
                // クリップボードにコピーする機能を実装してください。
            },
            'get': function( type, event, callback ){
                // クリップボードからデータを取得する機能を実装してください。
            }
        },
        'droppedFileOperator': {
            // ローカルディスクから直接ファイルがドロップされた場合の処理を拡張します。
            // mimetype毎に加工処理を設定できます。
            // 省略した場合は、Broccoliの標準的な処理が適用されます。
            'text/example': function(fileInfo, callback){
                var clipContents = {
                    'data': {},
                    'resources': {}
                };

                // クリップモジュールと同様の形式のオブジェクトを生成して
                // コールバックへ返却してください。
                // ファイルを処理しない場合は false を返却してください。
                callback(clipContents);
                return;
            }
        },
        'onClickContentsLink': function( uri, data ){
            // コンテンツ内のリンクをクリックした場合のイベントハンドラを登録できます。
            alert(uri + ' へ移動');
            console.log(data);
            return false;
        },
        'onMessage': function( message ){
            // ユーザーへ知らせるメッセージを表示します。
            // 組み込む先でお使いのフレームワークや環境に応じて、
            // 適切なメッセージ機能へ転送してください。
            yourOunCustomMessageMethod( message );
        },
        'onEditWindowOpen': function(){
            // インスタンスの編集ウィンドウを開いたときにコールされます。
        },
        'onEditWindowClose': function(){
            // インスタンスの編集ウィンドウを閉じたときにコールされます。
        },
        'enableModuleAnchor': true, // モジュールごとのid属性入力の有効/無効 (デフォルトは `true`)
        'enableModuleDec': true // DEC入力の有効/無効 (デフォルトは `true`)
        'enableInstanceLock': true // インスタンスロックの有効/無効 (デフォルトは `true`)
    } ,
    function(){
        // 初期化が完了すると呼びだされるコールバック関数です。

        $(window).on('resize', function(){
            // このメソッドは、canvasの再描画を行います。
            // ウィンドウサイズが変更された際に、UIを再描画するよう命令しています。
            broccoli.redraw();
        });

    }
);
</script>

プレビュー用ウェブサーバー - Web Server for preview

クロスオリジンで動作する場合は、編集画面上のプレビューHTMLの最後に、次のスクリプトコードを埋め込む必要があります。同一オリジンで動作させる場合はこの手順は必要ありません。

'http://127.0.0.1:8080' の箇所には、broccoli-html-editor の編集画面が置かれるサーバーの origin を設定してください。

<script data-broccoli-receive-message="yes">
window.addEventListener('message',(function() {
return function f(event) {
if(!event.data.scriptUrl){return;}
if(event.origin!='http://127.0.0.1:8080'){return;}// <- check your own server's origin.
var s=document.createElement('script');
document.querySelector('body').appendChild(s);s.src=event.data.scriptUrl;
window.removeEventListener('message', f, false);
}
})(),false);
</script>

APIの一覧はこちらを参照ください。

モジュールの開発 - developing HTML module

coming soon.

カスタムフィールドの開発 - developing custom field

サーバー側、クライアント側ともに、オプション customFields[fieldName] に定義します。

このメソッドは、サーバーサイドは broccoliHtmlEditor\fieldBase を、クライアントサイドは client/src/apis/fieldBase.js を、基底クラスとして継承します。

server side
- bind($fieldData, $mode, $mod) - データをバインドする
- resourceProcessor($path_orig, $path_public, $resInfo) - リソースを加工する
- gpi($options) - GPI
client side
- normalizeData(fieldData, mode) - データを正規化する
- mkPreviewHtml(fieldData, mod, callback) - プレビュー用の簡易なHTMLを生成する
- mkEditor(mod, data, elm, callback) - エディタUIを生成
- focus(elm, callback) - エディタUIにフォーカス
- duplicateData(data, callback) - データを複製する
- extractResourceId(data, callback) - データから使用するリソースのリソースIDを抽出する
- validateEditorContent(elm, data, mod, callback) - エディタUIで編集した内容を検証する
- saveEditorContent(elm, data, mod, callback, options) - エディタUIで編集した内容を保存
- callGpi(options, callback) - GPIを呼び出す

プラグインの種類と `broccoli.json`

broccoli-html-editor のプラグインには、 モジュール と フィールド があります。アプリケーションがこれらのパッケージを効率的に利用するため、各パッケージのルートディレクトリに broccoli.json を配置し、パッケージに関する情報を記述します。

モジュールの例

{
    "id": "foo-bar-elements",
    "name": "Foo Bar Elements",
    "type": "module",
    "path": "path/to/modules/"
}

フィールドの例

{
    "id": "foo-bar-field",
    "name": "Foo Bar Field",
    "type": "field",
    "backend": {
        "class": "myNamespace\\myClassName"
    },
    "frontend": {
        "file" : "path/to/dist/broccoli-field-foobar.js",
        "function" : "window.BroccoliFieldFooBar"
    }
}

データフォーマット

Data Format を参照してください。

for developer

build

$ npm run prod

build with watching edit change

$ npm run watch

server up

node.js

$ npm start

PHP

$ composer start

test

node.js

$ npm test

PHP

$ composer test

更新履歴 - Change log