基本情報

はじめに

最初はスニペットの作り方から習得するとよいでしょう。

return date('Y年m月d日');

上記のような内容のスニペットを作ると、「今日の日付」を出力します。

return $msg;

上記のようなスニペットを作って、

[[試作スニペット? &msg=`こんにちは`]]

上記のようにスニペットコールを記事内またはテンプレート内に書くと「こんにちは」と出力します。

さらに、$modxオブジェクトを習得するとよいでしょう。$modxオブジェクトには、プロパティ的なもの・メソッド的なものの両方がありますが、まずは習得しやすいプロパティを覚えましょう。プロパティ的なものとしてはリソース変数などがあります。

上記の例の$msgという変数は$modx->event->params['msg']に置き換えると、スニペットコール由来の変数であることを明示できるため分かりやすくなります。

API(プロパティ)

$modx->documentObject['リソース変数名']

まずはprint_r($modx->documentObject); で確認を。この配列は、リソース変数の値が格納されており、全部で37種類あります。テンプレート内でリソース変数を書くのと同じくらい気軽に、このプロパティを扱えるようになりましょう。

$modx->documentObject['テンプレート変数名'][1]

任意のテンプレート変数の値を取得します。ウィジェットの処理は通さないため注意。

$modx->documentIdentifier

$modx->documentObject['id']と同じですが、慣習的にこちらを使うことになっています。リソースIDを得たい場合はこちらを使ってください。

$modx->config['コンフィグ変数名']

こ れもprint_r($modx->config); で。数はいくつと決まってなくて、今後も増える可能性があります。ここには主にグローバル設定の値が格納されています。site_urlのように、グロー バル設定には項目がないものも含まれています。これはコンフィグ変数に相当します。テンプレート中でコンフィグ変数を書く機会はあまりないですが、開発の ために用いる機会は多いです。

スニペットを作ってみよう

最もシンプルなスニペットの作例を以下に示します。

<?php
    echo 'ハロー・ワールド。';
echo date(ただいまH時i分s秒です。); ?>

スニペット名「ハローワールド」として保存し、リソースまたはテンプレートで[[ハローワールド]]と記述して呼び出します。この時、MODXのデフォルトのリソース設定では出力がキャッシュされるため、2回目以降のアクセスでは、このスニペットで表示されるはずのリアルタイムな時刻が得られません。このスニペットのみ出力をキャッシュしたくない場合は[!ハローワールド!]と記述してください。MODXではこのようにブロック単位でキャッシュする・しないをコントロールすることができます。

スニペットはプラグインと違い、html上の任意の場所に動的出力を実装します。ブログパーツ感覚の手軽さが特長で、プログラミング初心者がphpに親しむにはちょうどいいでしょう。

上記の例では初心者が理解しやすいecho文を使っていますが、できればreturn文で最後にまとめて値を返すのがよいでしょう。

<?php
    $msg  = 'ハロー・ワールド。';
$msg .= date(ただいまH時i分s秒です。);
return $msg; ?>

たとえば上記のように書きます。
※ 「 .= 」というのは文字列を連結するための演算子です。

<?php
    $time = date('H時i分s秒');
    return sprintf('ハロー・ワールド。ただいま%sです。', $time);
?>

さらに分かりやすい書き方

プラグインを作ってみよう

最もシンプルなプラグインの作例を以下に示します。

$output = & $modx->documentOutput;
$now = date(ただいまH時i分s秒です。);
$output = str_replace('現在時刻を表示' , $now, $output);

システムイベント「OnParseDocument」にチェックを入れ、プラグイン名「現在時刻」として保存します。リソースまたはテンプレート中に「現在時刻を表示」という文字列を記述すると、これを現在時刻に変換して出力します。呼び出し場所の記述が必要なスニペットと違い、プラグインはMODXの機能(イベント)に関連付けてプログラムを実行します。一般的なCMSのプラグイン機能のイメージに近いものと言えます。

MODX の機能を拡張する上で、スニペット以上に自由度が高く対象を幅広く持つ実装が可能です。もともとMODXにはプラグイン機能はなく、コアファイルを改造す る形で機能を拡張していましたが、より安全で手間のかからない拡張を実現するためにプラグイン機能が実装されました。スニペットと違い管理画面の拡張も可 能で、TinyMCEやManagerManagerなどはプラグインとして構成されています。
※スニペットのように値を返す場合は$modx->event->output(返す値)メソッドを用います。

基本的なAPIメソッド

その他、SQL文を簡潔に記述するDBAPIが使用できます。

モジュールを作ってみよう(上級者向け)

モジュールを作ること自体は簡単にできます。

echo 'これは自作モジュールです';

上記のように書くだけで実行できます。

global $modx_lang_attribute,$modx_textdir, $manager_theme, $modx_manager_charset;
global $_lang, $_style, $SystemAlertMsgQueque, $content;

include('header.inc.php');
?>
<h1><?php echo $content['name']?></h1>
<div class="section">
<div class="sectionHeader">チュートリアル</div> <div class="sectionBody" style="padding:10px 20px;"> これは自作モジュールです。<br /> モジュール名は「<?php echo $content['name']?>」・モジュールIDは「<?php echo $content['id']?>」です。 </div> </div>
</div>
<?php include('footer.inc.php');

MODXの管理画面スタイルに合わせたい場合は上記のように記述します。
※将来的にはすっきり作れるようにメソッドを整備する予定です。

<h1><?php echo $content['name']?></h1>
<div class="tab-pane" id="pane1">
  <div class="tab-page" id="tab1">
    <h2 class="tab">タブ1</h2>
    <div class="sectionHeader">チュートリアル</div>
    <div class="sectionBody" style="padding:10px 20px;">
    これは自作モジュールです。
    </div>
  </div>
</div>
<script type="text/javascript">
pane1 = new WebFXTabPane(document.getElementById("pane1"),false);
</script>

タブを実装したい場合は上記のように記述します。セクション表現が不要な場合はsectionHeader・sectionBodyブロックを記述する必要はありません。

サイトツリーからリソースIDを取得する(モジュール作成)

サ イトツリーのリソースをクリックした時に実行する処理の内容を独自に実装できます。parent.tree.caフラグにparent・move・ linkいずれかの値をセットすることで、それぞれsetMoveValue・setParent・setLinkの各メソッドを呼び分け、リソース ID・リソース名を値として渡すことができます。詳しくは manager/frames/tree.php の treeActionメソッドを参照してください。

MODXのAPIを外部PHPアプリから利用する(上級者向け)

MODX Evolution 1.0.15J以降の場合

define('MODX_API_MODE', true);
include('/index.php');
$modx->getSettings();

MODX Evolution 1.0.5J-r11以降から1.0.14J-r9までの場合

define('MODX_API_MODE', true);
include('/index.php');
$modx = new DocumentParser;
$modx->db->connect();
$modx->getSettings();

MODX Evolution 1.0.5J-r10以前の場合

define('MODX_API_MODE', true);
iclude('/real_path/manager/includes/protect.inc.php');
include('/real_path/manager/includes/config.inc.php'); include(MODX_MANAGER_PATH . 'includes/document.parser.class.inc.php'); startCMSSession(); $modx = new DocumentParser; $modx->db->connect(); $modx->getSettings();

※さらに1.0.5J-r8以前の場合は、MODX_BASE_PATH・MODX_BASE_URLを先に定義する必要があります。

上記のように記述することで、$modx オブジェクトに自由にアクセスできるようになります。任意のチャンクやリソースの参照・スニペットの実行など、MODXの拡張機能と同等の機能を外部PHPアプリに持たせることができます。
※MODXとバッティングするグローバル変数がある場合は外部PHPアプリ側で先に宣言する必要があります。
MODXAPI Libraryを用いると、さらに手軽・具体的に実装できます。全APIにアクセスできるため、独自の管理画面・投稿画面を作ることも可能です。
※Evolution 1.0.5J-r11以降ではMODXAPI Libraryを使わずに同等のAPIアクセスが可能です。

Ajax処理を組み込む(スニペット作成)

MODXインストールディレクトリに配置されているindex-ajax.phpを、任意のスニペットなどに持たせたAjaxハンドラのエントリーポイントとして用いることができます。xmlHttpオブジェクトを用いて簡易に実装することもできますが、具体的な活用例として公式ドキュメント「Use AJAX with MODXAPI」(英語)が参考になります。同梱スニペットではajaxSearchがこのメソッドを利用しています。

var url    = MODX_BASE_URL . 'index-ajax.php';
var params = 'q=entry.php';
xmlHttp.open('POST',url,true);
xmlHttp.setRequestHeader('Content-type', 'application/x-www-form-urlencoded');
xmlHttp.setRequestHeader('Content-length', params.length);
xmlHttp.setRequestHeader('Connection', 'close');
xmlHttp.send(params);

たとえば接続部分に関しては上記のように記述します。任意のボタンをクリックした時などに、この処理を実行させます。 entry.phpの内部では実際の処理内容を記述しますが、スニペットを埋め込んだリソースを用いると、よりスマートに実装でき、メンテナンス性にも優 れます。

Ajax実装は技巧的には難しくありませんが、PHP・JavaScript・MySQL各種の技術を組み合わせるため複雑になりがちです。MODXが持つ各種メソッドを活用すると、シンプルにまとめることができます。

スニペット・プラグイン製作の参考情報

メインメソッドの実行順序

初めに$modx->executeParser()を実行

  1. $modx->db->connect()
  2. $modx->getSettings()
  3. $modx->checkSiteStatus()
  4. $modx->checkPublishStatus()
  5. $modx->getDocumentMethod()
  6. $modx->getDocumentIdentifier()
  7. $modx->documentMethodがaliasなら
    1. $modx->cleanDocumentIdentifier()
      リソースIDを特定したうえで$mdox->documentIdentifierをidにセット
  8. $modx->invokeEvent("OnLogPageHit")
  9. $modx->prepareResponse()

$modx->prepareResponse()

  1. $modx->checkCache()
  2. $modx->documentContentの中身が存在する場合(キャッシュが存在する場合)は
    1. $modx->invokeEvent("OnLoadWebPageCache")
  3. $modx->documentContentの中身が空の場合
    1. $modx->getDocumentObject()
  4. 条件判定の上で必要に応じて $modx->sendErrorPage()
  5. ウェブリンクの場合は $modx->makeUrl() または$modx->rewriteUrls()を実行し $modx->sendRedirect()

PR

  • KAGOYA
  • ASP at AKIHABARA Japan
  • CMS AWARDS 2007 Winner
ページトップへ