smarty/docs/ja/programmers/plugins/plugins-block-functions.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 2972 Maintainer: takagi Status: ready -->
<!-- CREDITS: mat-sh,daichi,joe -->
   <sect1 id="plugins.block.functions"><title>ブロック関数プラグイン</title>
    <funcsynopsis>
     <funcprototype>
      <funcdef>void <function>smarty_block_<replaceable>name</replaceable></function></funcdef>
      <paramdef>array <parameter>$params</parameter></paramdef>
      <paramdef>mixed <parameter>$content</parameter></paramdef>
      <paramdef>object <parameter>&amp;$smarty</parameter></paramdef>
      <paramdef>boolean <parameter>&amp;$repeat</parameter></paramdef>
     </funcprototype>
    </funcsynopsis>
    <para>
     ブロック関数は、<literal>{func} .. {/func}</literal> 形式の関数です。
     この関数によって囲まれたテンプレートのブロックの内容を処理します。
     ブロック関数は、同じ名前の
     <link linkend="language.custom.functions">カスタム関数</link>
     より優先されます。つまり、テンプレート関数
     <literal>{func}</literal> とブロック関数
     <literal>{func}..{/func}</literal> の両方を定義することはできません。
    </para>

    <itemizedlist>
    <listitem><para>
     デフォルトでは、実装された関数はSmartyによって２度
     （１度目は開始タグ、２度目は終端タグによって）呼び出されます
     （この動作の変更方法は次の <literal>$repeat</literal> を参照）。
    </para></listitem>
    <listitem><para>
     ブロック関数の開始タグのみ <link linkend="language.syntax.attributes">属性</link>
     を持つ場合があります。全ての属性はテンプレートからテンプレート関数に、
     連想配列として <parameter>$params</parameter> に格納された状態で渡されます。
     また、終端タグを処理している時に開始タグの属性にアクセスする事が可能です
    </para></listitem>
    <listitem><para>
     変数 <parameter>$content</parameter> の値は、
     関数が開始タグ又は終端タグのどちらから呼ばれるかによって変わります。
     開始タグの場合は &null;、終端タグの場合はテンプレートブロックのコンテンツです。
     テンプレートブロックが Smarty によって既に処理されている事に注意して下さい。
     つまり、受け取るのはテンプレートソースではなくテンプレートの出力です。
    </para></listitem>

    <listitem><para>
     <parameter>$repeat</parameter> パラメータは実装された関数に参照によって渡され、
     そのブロックが何回表示されるのかを操作する事ができます。
     デフォルトでは、最初のブロック関数の呼び出し(開始タグ)のとき
     <parameter>$repeat</parameter> は &true; で、その後に呼び出される場合(終端タグ)は、
     &false; となります。 実装された関数で <parameter>$repeat</parameter> を &true;
     とする事で、<literal>{func}...{/func}</literal> 間のコンテンツが再度評価され、
     <parameter>$content</parameter> パラメータに新しいブロックコンテンツが格納された状態で、
     再び呼び出されます。
    </para></listitem>
    </itemizedlist>

    <para>
     ネストしたブロック関数がある場合、変数
     <literal>$smarty->_tag_stack</literal>
     にアクセスする事で親のブロック関数を見つける事が可能です。
     <ulink url="&url.php-manual;var_dump"><varname>var_dump()</varname></ulink>
     を行い、構造をはっきりと理解すべきべきです。
    </para>

    <example>
     <title>ブロック関数プラグイン</title>
     <programlisting role="php">
<![CDATA[
<?php
/*
 * Smarty plugin
 * -------------------------------------------------------------
 * File:     block.translate.php
 * Type:     block
 * Name:     translate
 * Purpose:  テキストブロックを翻訳する
 * -------------------------------------------------------------
 */
function smarty_block_translate($params, $content, &$smarty, &$repeat)
{
    // 終了タグでのみ出力します
    if(!$repeat){
        if (isset($content)) {
            $lang = $params['lang'];
            // ここで $content に対する翻訳を行います
            return $translation;
        }
    }
}
?>
]]>
     </programlisting>
    </example>

<para>
 <link linkend="api.register.block"><varname>register_block()</varname></link>
 および
 <link linkend="api.unregister.block"><varname>unregister_block()</varname></link>
 も参照してください。
</para>

   </sect1>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->