Location: PHPKode > projects > Runemaster > docs/variable.html
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>第3章 テンプレート変数</title>
<link rel="stylesheet" href="style.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2">
<link rel="start" href="index.html" title="Runemaster マニュアル">
<link rel="up" href="index.html" title="Runemaster マニュアル">
<link rel="prev" href="cast.and.selection.template.html" title="2.3. 描写とテンプレートファイル">
<link rel="next" href="template.foreach.html" title="3.2. 繰り返し処理 (foreach)">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr><th colspan="3" align="center">第3章 テンプレート変数</th></tr>
<tr>
<td width="20%" align="left">
<a accesskey="p" href="cast.and.selection.template.html">前のページ</a> </td>
<th width="60%" align="center"> </th>
<td width="20%" align="right"> <a accesskey="n" href="template.foreach.html">次のページ</a>
</td>
</tr>
</table>
<hr>
</div>
<div class="chapter" lang="ja">
<div class="titlepage"><div><div><h2 class="title">
<a name="variable"></a>第3章 テンプレート変数</h2></div></div></div>
<div class="toc">
<p><b>目次</b></p>
<dl>
<dt><span class="section"><a href="variable.html#template.variable">3.1. テンプレート変数による置換処理</a></span></dt>
<dd><dl>
<dt><span class="section"><a href="variable.html#replace.key.attribute.variable">3.1.1. key 属性による値の置換</a></span></dt>
<dt><span class="section"><a href="variable.html#replace.bracket.variable">3.1.2. 括弧による値の置換</a></span></dt>
<dt><span class="section"><a href="variable.html#variable.type">3.1.3. 配列、オブジェクトへのアクセス</a></span></dt>
<dt><span class="section"><a href="variable.html#execute.function">3.1.4. PHP 関数の実行</a></span></dt>
<dt><span class="section"><a href="variable.html#execute.class.method">3.1.5. クラスメソッドの実行</a></span></dt>
<dt><span class="section"><a href="variable.html#escape.html.variable">3.1.6. 変数値のエスケープ処理</a></span></dt>
<dt><span class="section"><a href="variable.html#element.omitter">3.1.7. テンプレート変数タグの除去</a></span></dt>
<dt><span class="section"><a href="variable.html#element.attrubute.replace">3.1.8. エレメント属性に対する置換</a></span></dt>
<dt><span class="section"><a href="variable.html#changing.variable.key">3.1.9. テンプレート変数属性名の「key」を変更する</a></span></dt>
</dl></dd>
<dt><span class="section"><a href="template.foreach.html">3.2. 繰り返し処理 (foreach)</a></span></dt>
<dd><dl>
<dt><span class="section"><a href="template.foreach.html#variable.foreach">3.2.1. 変数値による繰り返し処理</a></span></dt>
<dt><span class="section"><a href="template.foreach.html#nest.foreach">3.2.2. 繰り返し処理のネスト</a></span></dt>
</dl></dd>
<dt><span class="section"><a href="template.variable.evaluation.html">3.3. 条件判定 (if)</a></span></dt>
<dd><dl>
<dt><span class="section"><a href="template.variable.evaluation.html#if.variable.evaluation">3.3.1. 評価による表示/非表示切り替え</a></span></dt>
<dt><span class="section"><a href="template.variable.evaluation.html#evaluation.by.expression">3.3.2. 評価式による判定</a></span></dt>
<dt><span class="section"><a href="template.variable.evaluation.html#reversal.evaluation">3.3.3. 評価値の反転</a></span></dt>
</dl></dd>
</dl>
</div>
<div class="section" lang="ja">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="template.variable"></a>3.1. テンプレート変数による置換処理</h2></div></div></div>
<div class="section" lang="ja">
<div class="titlepage"><div><div><h3 class="title">
<a name="replace.key.attribute.variable"></a>3.1.1. key 属性による値の置換</h3></div></div></div>
<p>
      Runemaster ではテンプレート上の特定箇所を「テンプレート変数」として指定し、
      また PHP プログラムにてそれら変数に対し「値の割り当て処理」をすることで、
      描写の際に内容の置換処理を行うことができます。
    </p>
<p>
      テンプレート上で変数による置換処理を行う対象として指定を行うには、
      HTML タグの属性として「key="***"」という値を付与します。
      以下の例では、h1 タグへ key="title"を、
      span タグに key="message" を指定しています。
      これにより、このテンプレート上では title, message
      という二つのテンプレート変数が準備されていることになります。
    </p>
<div class="example">
<a name="id296431"></a><p class="title"><b>例 3.1. 置換のための変数指定を行ったテンプレート (Hello.html)</b></p>
<div class="example-contents"><pre class="programlisting">
&lt;html&gt;
&lt;head&gt;&lt;/head&gt;

&lt;body&gt;
&lt;h1 key="title"&gt;Hello, World!&lt;/h1&gt;

&lt;div&gt;
  &lt;span key="message"&gt;&lt;/span&gt;
&lt;/div&gt;
&lt;/body&gt;
&lt;/html&gt;</pre></div>
</div>
<br class="example-break"><p>
      これらテンプレート変数の値を指定するには、PHP プログラムにおいて
      Runemaster の assign メソッドを実行します。
    </p>
<p>
      assign メソッドへは、テンプレート変数名をキーにした連想配列、
      もしくはプロパティとしたオブジェクトをパラメータとして指定します。
    </p>
<div class="example">
<a name="id296455"></a><p class="title"><b>例 3.2. PHPによるテンプレート変数の値の割り当て (hello.php)</b></p>
<div class="example-contents"><pre class="programlisting">
require_once 'Rune/Master.php';

$templatesDirectory = '/path/to/templateDirectory';
$master = new Rune_Master($templatesDirectory);

$variable = new stdClass();
$variable-&gt;title = 'Hi, Runemaster!';
$variable-&gt;message = 'DOM accesses template engine.';
$master-&gt;assign($variable);

/* $variable = array('title' =&gt; 'Hi, Runemaster',                   */
/*                   'message' =&gt; 'DOM accesses template engine.'); */
/* $master-&gt;assign($variable);                                      */
/* でもよい。同じ結果となる。                                       */

$master-&gt;cast('Hello');</pre></div>
</div>
<br class="example-break"><p>
      このプログラムを実行すると、次のような HTML が画面に表示されます。
      title 部、message 部それぞれが assign メソッドで指定した内容に置換され表示されていることが確認できます。
    </p>
<div class="example">
<a name="id296479"></a><p class="title"><b>例 3.3. 変数置換 (hello.php) の実行結果</b></p>
<div class="example-contents"><pre class="programlisting">
&lt;html&gt;
&lt;head&gt;&lt;/head&gt;
&lt;body&gt;
&lt;h1 key="title"&gt;Hi, Runemaster!&lt;/h1&gt;

&lt;div&gt;
  &lt;span key="message"&gt;DOM accesses template engine.&lt;/span&gt;
&lt;/div&gt;
&lt;/body&gt;
&lt;/html&gt;</pre></div>
</div>
<br class="example-break">
</div>
<div class="section" lang="ja">
<div class="titlepage"><div><div><h3 class="title">
<a name="replace.bracket.variable"></a>3.1.2. 括弧による値の置換</h3></div></div></div>
<p>
      先ほどの例において、次のようなテンプレートの記述でも同じ置換結果が得られます。
    </p>
<div class="example">
<a name="id296508"></a><p class="title"><b>例 3.4. 括弧によるテンプレート変数置換</b></p>
<div class="example-contents"><pre class="programlisting">
&lt;html&gt;
&lt;head&gt;&lt;/head&gt;

&lt;body&gt;
&lt;h1&gt;{title}&lt;/h1&gt;

&lt;div&gt;
  &lt;span&gt;{message}&lt;/span&gt;
&lt;/div&gt;
&lt;/body&gt;
&lt;/html&gt;</pre></div>
</div>
<br class="example-break"><p>
      テンプレート変数による置換処理は key 属性だけでなく、
      「{}」括弧で指定することもできます。
      これは Smarty や PEAR HTML_Template_Flexy といった、
      これまでのテンプレートエンジンにおける変数置換に似た機構です。
      key 属性による置換機構と切り替えるための特別なコードなども一切なく、
      また同時に利用することもできます。
    </p>
<p>
      どちらかの機構が優れているかや推奨するかといったことはありませんし、
      指定もしません。時として、ある目的を実現するためのテンプレート記述が、
      片方の機構のみで実現したがために可読性を著しく低下させることがあるかもしれません。
      目的を実現するため、シンプルに、かつスマートで変化に強いテンプレートを記述するために、
      どちらの機構も併用して利用することをお勧めします。
    </p>
</div>
<div class="section" lang="ja">
<div class="titlepage"><div><div><h3 class="title">
<a name="variable.type"></a>3.1.3. 配列、オブジェクトへのアクセス</h3></div></div></div>
<p>
      変数の値や配列やオブジェクトの場合、
      テンプレート上では次のようにテンプレート変数名を記述します。
      この例では key 属性による利用ですが、括弧変数による指定も同様になります。
    </p>
<div class="table">
<a name="id296553"></a><p class="title"><b>表 3.1. 配列、オブジェクトへのアクセス</b></p>
<div class="table-contents"><table summary="配列、オブジェクトへのアクセス" border="1">
<colgroup>
<col>
<col>
</colgroup>
<thead><tr>
<th align="center">タイプ</th>
<th align="center">テンプレート変数例</th>
<th align="center">PHP 変数値例</th>
</tr></thead>
<tbody><tr>
<td>
              通常(リテラル)
            </td>
<td>
              &lt;span key="class"&gt;&lt;/span&gt;
            </td>
<td>
              $class = 'Runemaster';
            </td>
</tr></tbody>
<tbody><tr>
<td>
              配列(リスト)
            </td>
<td>
              &lt;span key="items[0]"&gt;&lt;/span&gt;
            </td>
<td>
              $items = array('杖');
            </td>
</tr></tbody>
<tbody><tr>
<td>
              連想配列(ハッシュ)
            </td>
<td>
              &lt;span key="person.country"&gt;&lt;/span&gt;
            </td>
<td>
              $person = array('country' =&gt; 'スウェーデン');
            </td>
</tr></tbody>
<tbody><tr>
<td>
              オブジェクト
            </td>
<td>
              &lt;span key="book.name"&gt;&lt;/span&gt;
            </td>
<td>
              $book-&gt;name = 'Runemaster マニュアル';
            </td>
</tr></tbody>
</table></div>
</div>
<br class="table-break">
</div>
<div class="section" lang="ja">
<div class="titlepage"><div><div><h3 class="title">
<a name="execute.function"></a>3.1.4. PHP 関数の実行</h3></div></div></div>
<p>
      テンプレート変数の名称を指定する際には、あわせて
      PHP の組み込み関数も使用することができます。
      記述した PHP 関数の実行結果として返される値が、置換される内容として利用されます。
    </p>
<div class="example">
<a name="id342825"></a><p class="title"><b>例 3.5. テンプレート上での PHP 関数の実行と結果</b></p>
<div class="example-contents"><div class="variablelist"><dl>
<dt><span class="term">テンプレート</span></dt>
<dd><pre class="programlisting">
&lt;html&gt;
&lt;head&gt;&lt;/head&gt;
&lt;body&gt;
&lt;span key="count(items)"&gt;&lt;/span&gt;
&lt;span key="substr(class, 4)"&gt;&lt;/span&gt;
&lt;/body&gt;
&lt;/html&gt;</pre></dd>
<dt><span class="term">PHPコード</span></dt>
<dd><pre class="programlisting">
$variable-&gt;items = array('staff', 'book', 'stone');
$variable-&gt;class = 'Runemaster';
$master-&gt;assign($variable);
$master-&gt;cast('function');</pre></dd>
<dt><span class="term">実行結果</span></dt>
<dd><pre class="programlisting">
&lt;html&gt;
&lt;head&gt;&lt;/head&gt;
&lt;body&gt;
&lt;span key="count(items)"&gt;3&lt;/span&gt;
&lt;span key="substr(class, 4)"&gt;master&lt;/span&gt;
&lt;/body&gt;
&lt;/html&gt;</pre></dd>
</dl></div></div>
</div>
<br class="example-break">
</div>
<div class="section" lang="ja">
<div class="titlepage"><div><div><h3 class="title">
<a name="execute.class.method"></a>3.1.5. クラスメソッドの実行</h3></div></div></div>
<p>
      テンプレート変数に割り当てられた値がクラスのインスタンスである場合、
      テンプレート上でそのクラスインスタンスのメソッドを実行することができます。
      PHP 関数の実行と同様、メソッドの実行結果として返される値が、
      置換される内容として利用されます。
    </p>
<div class="example">
<a name="id343405"></a><p class="title"><b>例 3.6. テンプレート上でのクラスメソッドの実行と結果</b></p>
<div class="example-contents"><div class="variablelist"><dl>
<dt><span class="term">テンプレート</span></dt>
<dd><pre class="programlisting">
&lt;html&gt;
&lt;head&gt;&lt;/head&gt;
&lt;body&gt;
&lt;span key="class.getName()"&gt;&lt;/span&gt;
&lt;span key="class.add(foo, 2)"&gt;&lt;/span&gt;
&lt;/body&gt;
&lt;/html&gt;</pre></dd>
<dt><span class="term">PHP コード</span></dt>
<dd><pre class="programlisting">
class MyClass
{
  function getName()
  {
      return 'Runemaster';
  }

  function add($a, $b)
  {
      return $a + $b;
  }
}
/* 中略 */
$variable-&gt;class = new MyClass();
$variable-&gt;foo = 10;
$master-&gt;assign($variable);
$master-&gt;cast('classMethod');</pre></dd>
<dt><span class="term">実行結果</span></dt>
<dd><pre class="programlisting">
&lt;html&gt;
&lt;head&gt;&lt;/head&gt;
&lt;body&gt;
&lt;span key="class.getName()"&gt;Runemaster&lt;/span&gt;
&lt;span key="class.add(foo, 2)"&gt;12&lt;/span&gt;
&lt;/body&gt;
&lt;/html&gt;</pre></dd>
</dl></div></div>
</div>
<br class="example-break">
</div>
<div class="section" lang="ja">
<div class="titlepage"><div><div><h3 class="title">
<a name="escape.html.variable"></a>3.1.6. 変数値のエスケープ処理</h3></div></div></div>
<p>
      assign メソッドによってテンプレート変数として割り当てられた値は、
      HTML エンティティに変換する処理が自動的に行われて利用されます。
    </p>
<div class="example">
<a name="id343478"></a><p class="title"><b>例 3.7. 文字列の HTML エンティティ自動変換</b></p>
<div class="example-contents"><div class="variablelist"><dl>
<dt><span class="term">PHPコード</span></dt>
<dd><pre class="programlisting">
$variable-&gt;br = '&lt;br /&gt;';
$master-&gt;assign($variable);
$master-&gt;cast('example');</pre></dd>
<dt><span class="term">実行結果</span></dt>
<dd><pre class="programlisting">
&lt;html&gt;
&lt;head&gt;&lt;/head&gt;
&lt;body&gt;
&lt;span key="br"&gt;&amp;lt;br /&amp;gt;&lt;/span&gt;
&lt;/body&gt;
&lt;/html&gt;</pre></dd>
</dl></div></div>
</div>
<br class="example-break"><p>
      もし値の自動変換処理を行いたくない場合があれば、その箇所のタグに対して
      key 属性とあわせて「html」属性を設定します。
    </p>
<div class="example">
<a name="id343523"></a><p class="title"><b>例 3.8. HTML エンティティ変換を行わない</b></p>
<div class="example-contents"><div class="variablelist"><dl>
<dt><span class="term">実行結果</span></dt>
<dd><pre class="programlisting">
&lt;html&gt;
&lt;head&gt;&lt;/head&gt;
&lt;body&gt;
&lt;span key="br" html="true"&gt;&lt;br /&gt;&lt;/span&gt;
&lt;/body&gt;
&lt;/html&gt;</pre></dd>
</dl></div></div>
</div>
<br class="example-break"><p>
      なお、括弧によるテンプレート変数に対しても同様の変換処理は行われます。
      この括弧変数の値に対して HTML エンティティ変換処理を行いたくない場合は、
      変数名のあとに「|html」(パイプライン記号のあとに html)と入力します。
    </p>
<pre class="programlisting">{br|html}</pre>
</div>
<div class="section" lang="ja">
<div class="titlepage"><div><div><h3 class="title">
<a name="element.omitter"></a>3.1.7. テンプレート変数タグの除去</h3></div></div></div>
<p>
      例えば、テンプレート変数によって置換された結果が次のようなものであったとします。
      ここでは name, email, lastLogin といった値がプログラムから与えられ、
      それぞれの変数箇所に値が適応されている状態となっています。
    </p>
<pre class="programlisting">
Welcome &lt;span key="name"&gt;Runemaster&lt;/span&gt;
(&lt;span key="email"&gt;hide@address.com&lt;/span&gt;),
last login &lt;span key="lastLogin"&gt;2008-04-01 10:30:00&lt;/span&gt;</pre>
<p>
      span をテンプレート変数タグとして表現していますが、
      時にこれらタグを出力時には除去したいと思うかもしれません。
    </p>
<p>
      そのような時には、key 属性とあわせて「omitter」属性を設定します。
      この omitter 属性を設定することで、
      テンプレート変数として値の置換が行われた後、そのときに利用したタグを除去します。
    </p>
<div class="example">
<a name="id343592"></a><p class="title"><b>例 3.9. テンプレート変数タグの除去</b></p>
<div class="example-contents"><div class="variablelist"><dl>
<dt><span class="term">テンプレート(一部)</span></dt>
<dd><pre class="programlisting">
Welcome &lt;span key="name" omitter="true"&gt;user name&lt;/span&gt;
(&lt;span key="email" omitter="true"&gt; user email&lt;/span&gt;),
last login &lt;span key="lastLogin" omitter="true"&gt; date (YYYY-MM-DD hh:mm:ss)&lt;/span&gt;</pre></dd>
<dt><span class="term">実行結果</span></dt>
<dd><pre class="programlisting">
Welcome Runemaster!
(hide@address.com),
last login 2008-04-01 10:30:00</pre></dd>
</dl></div></div>
</div>
<br class="example-break">
</div>
<div class="section" lang="ja">
<div class="titlepage"><div><div><h3 class="title">
<a name="element.attrubute.replace"></a>3.1.8. エレメント属性に対する置換</h3></div></div></div>
<p>
      エレメント(HTML タグ)の属性に対してテンプレート変数値で置換したい場合、
      括弧によるテンプレート変数指定で実現します。
    </p>
<pre class="programlisting">
&lt;font color="{color}"&gt;Hello, World!&lt;/font&gt;</pre>
<p>
      ただし、置換対象として指定できる箇所は属性の「値」のみです。
      次の例のような、属性の「キー(名前)」および属性全体を対象として指定することはできません。
    </p>
<pre class="programlisting">
■次の {color} は置換されない
&lt;font {color}="#FF0000"&gt;Hello, World!&lt;/font&gt;
&lt;font {color}&gt;Hello, World!&lt;/font&gt;</pre>
</div>
<div class="section" lang="ja">
<div class="titlepage"><div><div><h3 class="title">
<a name="changing.variable.key"></a>3.1.9. テンプレート変数属性名の「key」を変更する</h3></div></div></div>
<p>
      テンプレート変数による置換の対象とするために、タグ内に設定する属性は通常「key」ですが、
      setVariableKey メソッドを使用するとこの key を好きな名称に変更することができます。
    </p>
<pre class="programlisting">
// テンプレート変数による置換タグを id="***" とする
$master-&gt;setVariableKey('id');</pre>
</div>
</div>
</div>
<div class="navfooter">
<hr>
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left">
<a accesskey="p" href="cast.and.selection.template.html">前のページ</a> </td>
<td width="20%" align="center"> </td>
<td width="40%" align="right"> <a accesskey="n" href="template.foreach.html">次のページ</a>
</td>
</tr>
<tr>
<td width="40%" align="left" valign="top">2.3. 描写とテンプレートファイル </td>
<td width="20%" align="center"><a accesskey="h" href="index.html">ホーム</a></td>
<td width="40%" align="right" valign="top"> 3.2. 繰り返し処理 (foreach)</td>
</tr>
</table>
</div>
</body>
</html>
Return current item: Runemaster