smarty/docs/ja/designers/language-builtin-functions/language-function-insert.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 1.10 Maintainer: takagi Status: ready -->
<!-- CREDITS: mat-sh,daichi,joe -->
<sect1 id="language.function.insert">
 <title>{insert}</title>
  <para>
   <varname>{insert}</varname> タグは <link
   linkend="language.function.include"><varname>{include}</varname></link>
   タグと似た動作をします。ただ <varname>{insert}</varname>
   タグは、テンプレートの <link linkend="caching">キャッシュ</link>
   が有効であってもキャッシュされません。
   テンプレートが呼び出されるたびに実行されます。
 </para>

 <informaltable frame="all">
  <tgroup cols="5">
   <colspec colname="param" align="center" />
   <colspec colname="type" align="center" />
   <colspec colname="required" align="center" />
   <colspec colname="default" align="center" />
   <colspec colname="desc" />
   <thead>
    <row>
     <entry>属性名</entry>
     <entry>型</entry>
     <entry>必須</entry>
     <entry>デフォルト</entry>
     <entry>概要</entry>
    </row>
   </thead>
   <tbody>
    <row>
     <entry>name</entry>
     <entry>string</entry>
     <entry>Yes</entry>
     <entry><emphasis>n/a</emphasis></entry>
     <entry>呼び出すinsert関数の名前(insert_name)</entry>
    </row>
    <row>
     <entry>assign</entry>
     <entry>string</entry>
     <entry>No</entry>
     <entry><emphasis>n/a</emphasis></entry>
     <entry>出力を格納するテンプレート変数名</entry>
    </row>
    <row>
     <entry>script</entry>
     <entry>string</entry>
     <entry>No</entry>
     <entry><emphasis>n/a</emphasis></entry>
     <entry>insert関数を呼び出す前にインクルードされるPHPスクリプト名</entry>
    </row>
    <row>
     <entry>[var ...]</entry>
     <entry>[var type]</entry>
     <entry>No</entry>
     <entry><emphasis>n/a</emphasis></entry>
     <entry>insert関数に渡す変数</entry>
    </row>
   </tbody>
  </tgroup>
 </informaltable>


 <para>
  例えば、ページの上部にバナーを表示するテンプレートを持っているとします。
  バナーにはHTML, images, flash等が混合して含まれます。
  したがってここに静的リンクを用いる事はできないので、
  バナーコンテンツをキャッシュの対象にしたくありません。
  そのためには、あらかじめ設定ファイルから取得した #banner_location_id#
  と #site_id# の値を渡し、バナーコンテンツを表示するために
  {insert} タグを呼び出す必要があります。
 </para>
 <example>
  <title>{insert} 関数</title>
<programlisting>
{* バナーを取得する例 *}
{insert name="getBanner" lid=#banner_location_id# sid=#site_id#}
</programlisting>
 </example>
 <para>
  この例では、name 属性に <quote>getBanner</quote> を指定し、
  パラメータに #banner_location_id# と #site_id# を渡しています。Smarty は
  PHP アプリケーション内の insert_getBanner() 関数を探し、第１パラメータとして
  #banner_location_id# と #site_id# の値を格納した連想配列を渡します。
  アプリケーションにおける全ての {insert} 関数の名前は、
  ネームスペースの衝突を避けるために "insert_" によって始まる必要があります。
  insert_getBanner() 関数は、渡された値によって何らかの処理を行い、結果を返すべきです。
  この結果はテンプレートの {insert} タグに置換されて表示されます。
  この例では、Smarty は insert_getBanner(array("lid" => "12345","sid" => "67890"));
  という関数を呼び出し、返された結果が {insert} タグの位置に表示されます。
  </para>
  <itemizedlist>
  <listitem><para>
   <parameter>assign</parameter> 属性を指定すると、
   <varname>{insert}</varname> タグの出力は
   ブラウザに表示される代わりにテンプレート変数に格納されます。
   <note>
   <para>
    出力をテンプレート変数に格納するのは、
    <link linkend="variable.caching">キャッシュ</link>
    が有効な状態ではあまり有益ではありません。
   </para>
  </note>
  </para></listitem>

  <listitem><para>
   <parameter>script</parameter> 属性を与えると、この PHP スクリプトは
   <varname>{insert}</varname> 関数が実行される前に
   (一度だけ) インクルードされます。
   これは、insert 関数がまだ存在しないかもしれない場合や、insert
   関数の動作のために PHP スクリプトを最初にインクルードする必要がある場合に指定します。
   </para>
   <para>
   パスには、絶対パスかあるいは
   <link linkend="variable.trusted.dir"><parameter>$trusted_dir</parameter></link>
   からの相対パスを指定します。<link
   linkend="variable.security"><parameter>$security</parameter></link>
   が有効な場合は、スクリプトは
   <link linkend="variable.trusted.dir"><parameter>$trusted_dir</parameter></link>
   内にある必要があります。
  </para></listitem>
  </itemizedlist>
  <para>
   Smarty オブジェクトは第２パラメータとして渡されます。
   これにより、<varname>{insert}</varname>
   関数から Smarty オブジェクトの情報の参照や修正が可能です。
  </para>
  <note>
   <title>テクニカルノート</title>
   <para>
    テンプレートには、キャッシュの対象外となる部分を持たせる事が可能です。
    <link linkend="caching">キャッシュ</link> が有効の場合でも、
    <varname>{insert}</varname> タグによる出力はキャッシュされません。
    そのページが呼び出される度に動的に実行されます。
    この動作は、バナー・投票・天気予報・検索結果・ユーザーフィードバックエリア等に向いています。
   </para>
  </note>
   <para>
  <link linkend="language.function.include"><varname>{include}</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
-->