Markup

Helper / HelperObject

Author : trashtoy

Table of Contents

概要

Helper および HelperObject はノードの構築と出力をさらに簡略化するための API です. 例えば REST API を提供する Web サービスを開発する場合など, 似たようなフォーマットの XML 出力をする機能が多数存在するようなケースで役に立つでしょう.

HTML を生成する場合は Html という専用のユーティリティクラスが存在するので, そちらを使うことをお勧めします.

基本的な使い方

以下のような流れでノードを生成・出力します.

  1. Builder オブジェクトを指定して Helper オブジェクトを作成します.
  2. Helper の createObject() メソッドを使い, HelperObject オブジェクトを作成します.
  3. 生成した HelperObject の append() や attr() などのメソッドを使ってノードの中身を構築します. jQuery のようにメソッドチェインを利用して簡潔な記述が出来ます.
  4. write() メソッドでそのノードをマークアップして出力します.

HelperObject とは任意のノードをラップして糖衣構文を備えた Component です. createObject() の引数に文字列を指定することで, その文字列を要素名とする要素をあらわす HelperObject が生成されます.

サンプルコードを以下に掲載します.

  1. $helper = new Peach_Markup_Helper(new Peach_Markup_DefaultBuilder());
  2. $tag1   = $helper->createObject("tag")->attr("id", 1)->append("First")->append("Second")->append("Third");
  3. $tag2   = $helper->createObject("tag")->attr("id", 2)->append("Fourth")->append("Fifth");
  4. $root   = $helper->createObject("root")->append($tag1)->append($tag2);
  5. echo $root->write();
  6. /*
  7. Output:
  8. <root>
  9.     <tag id="1">
  10.         First
  11.         Second
  12.         Third
  13.     </tag>
  14.     <tag id="2">
  15.         Fourth
  16.         Fifth
  17.     </tag>
  18. </root>
  19.  */

EmptyElement と ContainerElement の出し分け

Helper を生成する際の引数で, 要素名によって空要素にするかどうかを設定することが出来ます. 以下のサンプルでは tag2, tag4 のみ空要素として扱うようにしています.

  1. $helper = new Peach_Markup_Helper(new Peach_Markup_DefaultBuilder(), array("tag2", "tag4"));
  2. echo $helper->createObject("root")
  3.     ->append($helper->createObject("tag1"))
  4.     ->append($helper->createObject("tag2"))
  5.     ->append($helper->createObject("tag3"))
  6.     ->append($helper->createObject("tag4"))
  7.     ->write();
  8. /*
  9. Output:
  10. <root>
  11.     <tag1></tag1>
  12.     <tag2 />
  13.     <tag3></tag3>
  14.     <tag4 />
  15. </root>
  16.  */

append と appendTo の違い

HelperObject にはノードを追加する手段として append() と appendTo() の 2 種類があります. append() が呼び出し元のノードの中に引数のノードを追加するのに対して, appendTo() は引数のノードの中に呼び出し元のノードを追加します. 以下の 2 種類のコードは同じ結果となります.

  1. $helper = new Peach_Markup_Helper(new Peach_Markup_DefaultBuilder());
  2.  
  3. // append を使う場合
  4. $tag1   = $helper->createObject("tag")->append("Test 1")->append("Test 2");
  5. $tag2   = $helper->createObject("tag")->append("Test 3")->append("Test 4");
  6. $root   = $helper->createObject("root")->append($tag1)->append($tag2);
  7.  
  8. // appendTo を使う場合
  9. $root   = $helper->createObject("root");
  10. $tag1   = $helper->createObject("tag")->append("Test 1")->append("Test 2")->appendTo($root);
  11. $tag2   = $helper->createObject("tag")->append("Test 3")->append("Test 4")->appendTo($root);