Custom Console Extensions は、 Pickles 2 アプリケーションの管理画面を拡張するAPIです。
プロジェクト側に追加することで、 プロジェクト独自のカスタマイズされた管理画面拡張機能を追加することができます。
カスタマイズされた管理画面拡張機能は、Composerパッケージから読み込むことができるので、複数のプロジェクトで共有したり、配布したり、アイデアを再利用することも容易です。
Custom Console Extensions は、Pickles 2 babycorn v2.0.0-beta.28 および pickles2/px2-px2dthelper v2.0.17 で追加されました。
Custom Console Extensions は、バックエンド処理のためのPHPスクリプトと、画面を表現するJavaScript、およびスタイルシートや画像などのリソースファイル群で構成されます。
プロジェクト側に実装し、 コンフィグ $conf->plugins->px2dt->custom_console_extensions に設定します。
アプリケーションには、PXコマンドを通じてロードされます。
ファイルの構成の例を示します。
/
├ front/
│ ├ sample.css
│ ├ sample.js
│ └ images/
│ └ imageN.png
└ php/
└ sample.php
ディレクトリ名やファイル名は任意(後述するPHP内のメソッドでファイル名を知らせます)ですが、画面を構成するフロントエンドの資材は1つのディレクトリ内にまとめて格納するようにしてください。
php/sample.php には、バックエンド処理を記述するクラスを実装します。次のコードは、任意の namespase 内に実装したクラスの命名例です。 namespase にもクラス名にも、命名規則は特にないので、他と重複しない任意の名前を与えてください。
<?php
namespace yourVendorName\customConsoleExtensions\sample;
class main{
/* 実装については後に詳しく説明します */
}
Composerパッケージとして配布する場合は、このクラスがロードされるように設定してください。
クラスをプロジェクトにロードしたら、Pickles 2 プロジェクトのコンフィグに次のように追記します。
<?php
return call_user_func( function(){
// initialize
$conf = new stdClass;
/* 中略 */
/**
* CMS画面に追加するカスタム管理画面を登録する
*/
$conf->plugins->px2dt->custom_console_extensions = array(
'sample' => 'yourVendorName\customConsoleExtensions\sample\main',
);
}
または、次のように記述することもできます。
// 例
$conf->plugins->px2dt->custom_console_extensions = array(
'sample' => array(
'class_name' => 'yourVendorName\customConsoleExtensions\sample\main({"test":"1"})',
),
);
$conf->plugins->px2dt->custom_console_extensions に、キーと値のセットを設定します。
キーは、拡張機能のIDとして利用されます。 値には、PHPに与えたクラス名を指定します。
クラス名の末尾にカッコ () で囲ったJSON形式の文字列を記述して、設定オプションを渡すことができます。
これは、バックエンド側PHPクラスのコンストラクタ第2引数から受け取れます。
// 例
$conf->plugins->px2dt->custom_console_extensions = array(
'sample' => 'yourVendorName\customConsoleExtensions\sample\main({"test":"1"})',
);
拡張機能にアクセスするために、特定の権限を要求するには、次のように capability を設定します。
次の例では、 manage と server_side_scripting の権限を要求します。
// 例
$conf->plugins->px2dt->custom_console_extensions = array(
'sample' => array(
'class_name' => 'yourVendorName\customConsoleExtensions\sample\main({"test":"1"})',
'capability' => array('manage', 'server_side_scripting'),
),
);
クライアント側の初期化時には、任意のJavaScript関数名を与え、実行されます。
この関数名は任意で、後述する PHPメソッド get_client_initialize_function() から通知します。
初期化関数には、ヘルパーオブジェクト cceAgent が第1引数に与えられます。
window.yourVendorNameCustomConsoleExtensionsSample = function(cceAgent){
let $elm = cceAgent.elm();
cceAgent.onBroadcast(function(message){
console.info('Broadcast recieved:', message);
alert(message.message);
});
$elm.innerHTML = `
<p>管理画面拡張を読み込みました。</p>
<p>GPIを呼び出すテスト</p>
<p><button type="button" class="px2-btn">呼び出します。</button></p>
`;
$elm.querySelector('button').addEventListener('click', function(){
cceAgent.gpi({
'command': 'test-gpi-call'
}, function(res){
console.log('---- res:', res);
alert(res);
});
});
}
画面を描画する対象のDOM要素を取得します。
バックエンド側PHPのGPIをコールします。
第1引数の options が、PHP側では gpi() の引数として受け取ることができます。
callback には、 PHP側 gpi() の返却値が渡されます。
cceAgent.gpi({
'command': 'test-gpi-call'
}, function(res){
console.log('---- res:', res);
});
PXコマンドを実行します。
次の例は、パブリッシュを実行する場合のサンプルです。
cceAgent.pxCmd('/?PX=publish.run',
{
"progress": function(data, error){
console.log('--- progress:', data, error);
},
},
function(pxCmdStdOut, error){
console.log('---- pxCmdStdOut:', pxCmdStdOut, error);
});
pickles2/px2-px2dthelper v2.2.3 で追加されました。
コンテンツ編集画面を開きます。
pickles2/px2-px2dthelper v2.1.9 で追加されました。
テーマレイアウトの編集画面を開きます。
pickles2/px2-px2dthelper v2.1.9 で追加されました。
PHP側 $cceAgent.broadcast() に対するコールバック関数を登録します。
バックエンドで $cceAgent.broadcast() がコールされたとき、非同期のメッセージを callback の引数として受け取ることができます。
PHPクラスには、予め決められたメソッドが実装されている必要があります。
<?php
namespace yourVendorName\customConsoleExtensions\sample;
class main{
/** $px */
private $px;
/** $options */
private $options;
/** $cceAgent */
private $cceAgent;
/**
* コンストラクタ
* @param object $px Pickles 2 オブジェクト
* @param object $options 設定オプション
* @param object $cceAgent 管理画面拡張エージェントオブジェクト
*/
public function __construct($px, $options, $cceAgent){
$this->px = $px;
$this->options = $options;
$this->cceAgent = $cceAgent;
}
/**
* 管理機能名を取得する
*/
public function get_label(){
return 'サンプル機能拡張';
}
/**
* フロントエンド資材の格納ディレクトリを取得する
*/
public function get_client_resource_base_dir(){
return __DIR__.'/../front/';
}
/**
* 管理画面にロードするフロント資材のファイル名を取得する
*/
public function get_client_resource_list(){
$rtn = array();
$rtn['css'] = array();
array_push($rtn['css'], 'sample.css');
$rtn['js'] = array();
array_push($rtn['js'], 'sample.js');
return $rtn;
}
/**
* 管理画面を初期化するためのJavaScript関数名を取得する
*/
public function get_client_initialize_function(){
return 'window.yourVendorNameCustomConsoleExtensionsSample';
}
/**
* General Purpose Interface (汎用API)
*/
public function gpi($request){
switch($request->command){
case 'test-gpi-call':
$this->cceAgent->async(array(
'type'=>'gpi',
'request' => array(
'command' => 'test-async',
),
));
return 'Test GPI Call Successful.';
case 'test-async':
$this->cceAgent->broadcast(array(
'message'=>'Hello Broadcast Message !',
));
return 'Test GPI Call Successful.';
}
return false;
}
}
非同期の処理を実行します。
例えば Pickles 2 のパブリッシュなどの、1つの処理に長い時間がかかる処理を実行したい場合に利用します。 処理は、クライアントからのリクエストに待たせることなく非同期的に実行されます。
クライアント側のJavaScriptへ、非同期のメッセージを送信します。