smarty/docs/ja/getting-started.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 1.20 Maintainer: takagi Status: ready -->
<!-- CREDITS: mat-sh,daichi,joe -->
<part id="getting.started">
 <title>はじめに</title>

 <chapter id="what.is.smarty">
  <title>Smarty とは?</title>
  <para>
   Smarty は PHP のためのテンプレートエンジンです。具体的に言うと、php
   のプレゼンテーションからアプリケーションのロジックとコンテンツを分離して管理する事を容易にします。
   これは、プログラマーとテンプレートデザイナーの役割が異なり、
   これらの役割を違う人間が受け持っている場合に最適だと言えます。 
  </para>

  <para>
   例えば、新聞記事を表示するwebページを作成しているとします。
   </para>
   <itemizedlist>
   <listitem><para>
   記事の <literal>$headline</literal> (見出し)、<literal>$tagline</literal>
   (キャッチフレーズ)、<literal>$author</literal> (著者) および
   <literal>$body</literal> (本文) が中身を構成する要素となります。
   ここには、それをどのように表示するかという情報は含まれません。
   これらはアプリケーションによって Smarty に
   <link linkend="api.assign">渡されます</link>。
   </para></listitem>

   <listitem><para>
   テンプレートデザイナーはこのテンプレートを編集し、
   HTML タグや <link linkend="language.basic.syntax">テンプレートタグ</link>
   を使用して、これらの <link linkend="language.syntax.variables">変数</link>
   と要素 (テーブル、div、背景色、フォントサイズ、スタイルシート、svg など)
   の体裁を調整します。
   </para></listitem>

   <listitem><para>
   ある日、プログラマーが (アプリケーションロジックを変更したなどの理由で)
   記事の内容を取得する手段を変更する必要が出てきたとします。
   この変更はテンプレートデザイナーに影響がないため、
   記事には全く同じ内容のテンプレートが適用できるでしょう。
   </para></listitem>

   <listitem><para>
   同様に、もしテンプレートデザイナーがテンプレートを完全に作り直したい場合でも、
   アプリケーションロジックを変更する必要がありません。
   </para></listitem>

   <listitem><para>
   したがって、プログラマーはテンプレートを作り直す事なくアプリケーションロジックを変更する事ができ、
   テンプレートデザイナーはアプリケーションロジックを壊す事なくテンプレートを変更できます。
  </para></listitem>
  </itemizedlist>

  <para>
   Smarty の設計の目標の一つとして、
   ビジネスロジックとプレゼンテーションロジックの分離があります。
   </para>

   <itemizedlist>
   <listitem><para>
   これは、プレゼンテーションのためだけという条件の下で
   テンプレートにロジックを含める事が可能であるという事です。
   他のテンプレートを <link linkend="language.function.include">include</link>
   したり、テーブル行の色を
   <link linkend="language.function.cycle">変更</link> したり、変数を
   <link linkend="language.modifier.upper">大文字</link> にしたり、データの配列を
   <link linkend="language.function.foreach">ループ</link> させたり、それを
   <link linkend="api.display">表示</link>
   したりといったことが、プレゼンテーションロジックの例になります。
   </para></listitem>
   <listitem><para>
   これは、Smarty がビジネスロジックとプレゼンテーションロジックの分離を
   強制している訳ではない事を意味しています。
   Smarty はテンプレート内に置かれたものがビジネスロジックなのか何なのか全くわかりません。
   </para></listitem>
   <listitem><para>
   また、テンプレートにロジックを <emphasis>置きたくない</emphasis>
   ならば、テキストと変数のみでコンテンツを作り上げることも可能です。
  </para></listitem>
  </itemizedlist>

  <para>
   Smarty のユニークな特徴の一つは、テンプレートをコンパイルすることです。
   つまり、Smarty がテンプレートファイルを読み込み、
   それをもとにして PHP スクリプトを作成するということです。
   一度作成してしまえば、その後はコンパイルされた PHP スクリプトが実行されるので、
   各リクエスト時にテンプレートファイルのパースによるオーバーヘッドがありません。
   さらに各テンプレートは、
   <ulink url="&url.e-accel;">eAccelerator</ulink>、
   <ulink url="&url.ion-accel;">ionCube</ulink>、
   <ulink url="&url.mmcache-accel;">mmCache</ulink>
   あるいは <ulink url="&url.zend;">Zend Accelerator</ulink>
   のような PHP コンパイラやキャッシュソリューションを最大限に活用することができます。
  </para>
  <para>
   <emphasis role="bold">Smarty の特徴</emphasis>
  </para>
  <itemizedlist>
   <listitem>
    <para>
     非常に高速
    </para>
   </listitem>
   <listitem>
    <para>
     下仕事は PHP パーサが行うので能率的
    </para>
   </listitem>
   <listitem>
    <para>
     コンパイルは一度だけ行われるので、テンプレートのパースによるオーバーヘッドが無い
    </para>
   </listitem>
   <listitem>
    <para>
     <link linkend="variable.compile.check">再コンパイル</link>
     は変更があったテンプレートファイルのみで行うのでスマート
    </para>
   </listitem>
   <listitem>
    <para>
     簡単に独自の <link
     linkend="language.custom.functions">関数</link>
     や <link linkend="language.modifiers">変数の修飾子</link>
     を作成できるので、テンプレート言語を強力に拡張することが可能
    </para>
   </listitem>
   <listitem>
    <para>
     テンプレートの
     <link linkend="variable.left.delimiter">{デリミタ}</link>
     タグの記法を変更し、
     <literal>{$foo}</literal>、<literal>{{$foo}}</literal>、
     <literal>&lt;!--{$foo}--&gt;</literal> などを使用することが可能
    </para>
   </listitem>
   <listitem>
    <para>
     <link linkend="language.function.if">
     <literal>{if}..{elseif}..{else}..{/if}</literal></link>
     構文は PHP パーサが処理するので、<literal>{if...}</literal>
     の条件式にはシンプルなものから複雑なものまで自由に指定可能
    </para>
   </listitem>
   <listitem>
    <para>
     <link linkend="language.function.section">
     <varname>sections</varname></link> や <varname>if's</varname>
     などは無制限にネスト可能
    </para>
   </listitem>
   <listitem>
    <para>
     テンプレートファイル内に
     <link linkend="language.function.php">PHP コードを埋め込む</link>
     ことも可能。しかし、エンジン自体が
     <link linkend="plugins">カスタマイズ</link> できるので、
     これはおそらく不要 (そして非推奨)。
    </para>
   </listitem>
   <listitem>
    <para>
     組み込みで <link linkend="caching">キャッシュ機能</link> をサポート
    </para>
   </listitem>
   <listitem>
    <para>
     任意の <link linkend="template.resources">テンプレート</link> ソース
    </para>
   </listitem>
   <listitem>
    <para>
     カスタム <link
     linkend="section.template.cache.handler.func">キャッシュハンドラ</link>
     関数
    </para>
   </listitem>
   <listitem>
    <para>
     <link linkend="plugins">プラグイン</link> 機構
    </para>
   </listitem>
  </itemizedlist>
 </chapter>





 <chapter id="installation">
  <title>インストール</title>

  <sect1 id="installation.requirements">
   <title>必要条件</title>
   <para>
    Smarty は、PHP 4.0.6 以降が動作しているウェブサーバを必要とします。
   </para>
  </sect1>

  <sect1 id="installing.smarty.basic">
   <title>基本的なインストール</title>

   <para>
    Smarty のライブラリファイルを、ディストリビューションの
    <filename class="directory">/libs/</filename> サブディレクトリにインストールしてください。
    これらの <filename>.php</filename> を編集してはいけません。
    これらはすべてのアプリケーションで共有するものであり、
    Smarty を新しいバージョンにアップグレードする際にのみ更新します。
   </para>
   <para>以下の例で、Smarty の tarball の展開先は次のようになります。
   <itemizedlist>
   <listitem><para>*nix の場合は
   <filename class="directory">/usr/local/lib/Smarty-v.e.r/</filename>
   </para></listitem>
   <listitem><para>Windows 環境の場合は
   <filename class="directory">c:\webroot\libs\Smarty-v.e.r\</filename>
   </para></listitem>
   </itemizedlist>
   </para>

   <example>
    <title>必要な Smarty ライブラリファイル群</title>
    <screen>
<![CDATA[
Smarty-v.e.r/
   libs/
      Smarty.class.php
      Smarty_Compiler.class.php
      Config_File.class.php
      debug.tpl
      internals/*.php  (これら全て)
      plugins/*.php    (これら全て)
]]>
    </screen>
   </example>

   <para>
    Smarty は、<link linkend="constant.smarty.dir"><constant>SMARTY_DIR</constant></link>
    という名前の PHP の <ulink url="&url.php-manual;define">定数</ulink>
    を使用します。これは、Smarty の <filename>libs/</filename> ディレクトリへの
    <emphasis role="bold">絶対パス</emphasis> を表します。
    基本的にあなたのアプリケーションが <filename>Smarty.class.php</filename>
    ファイルを見つける事が出来るなら
    <link linkend="constant.smarty.dir"><constant>SMARTY_DIR</constant></link>
    を定義する必要はありません。Smarty は自分でそれを考えます。
    したがって、もし <filename>Smarty.class.php</filename> が
    <ulink url="&url.php-manual;ini.core.php#ini.include-path">include_path</ulink>
    にないか、あなたのアプリケーションにてそれらへの絶対パスが指定されていないなら、
    手動で <constant>SMARTY_DIR</constant> を定義する必要があります。
    <constant>SMARTY_DIR</constant> は、<emphasis role="bold">
    最後にスラッシュ / を含めなければなりません</emphasis>。
   </para>


   <informalexample>
   <para>
    次の例では、PHP スクリプト内での Smarty インスタンスの作成方法を示します。
   </para>
    <programlisting role="php">
<![CDATA[
<?php
// 注: Smarty の 'S' は大文字です
require_once('Smarty.class.php');
$smarty = new Smarty();
?>
]]>
    </programlisting>
   </informalexample>

   <para>
    上のスクリプトを実行してみてください。
    <filename>Smarty.class.php</filename> ファイルが見つからないというエラーが出た場合は、
    以下のいずれかを行う必要があります。
   </para>

   <example>
    <title>手動で SMARTY_DIR 定数を定義する</title>
    <programlisting role="php">
<![CDATA[
<?php
// *nix スタイル (大文字の 'S' に注意)
define('SMARTY_DIR', '/usr/local/lib/Smarty-v.e.r/libs/');

// windows スタイル
define('SMARTY_DIR', 'c:/webroot/libs/Smarty-v.e.r/libs/');

// *nixとwindowsで共通なハックバージョンの例
// Smarty は現在のスクリプトが 'includes/' ディレクトリの下にあると仮定します。
define('SMARTY_DIR',str_replace("\\","/",getcwd()).'/includes/Smarty-v.e.r/libs/');

require_once(SMARTY_DIR . 'Smarty.class.php');
$smarty = new Smarty();
?>
]]>
    </programlisting>
   </example>

   <example>
    <title>ライブラリファイルの絶対パスを指定する</title>
    <programlisting role="php">
<![CDATA[
<?php
// *nix スタイル (大文字の 'S' に注意)
require_once('/usr/local/lib/Smarty-v.e.r/libs/Smarty.class.php');

// windows スタイル
require_once('c:/webroot/libs/Smarty-v.e.r/libs/Smarty.class.php');

$smarty = new Smarty();
?>
]]>
    </programlisting>
   </example>

   <example>
    <title><filename>php.ini</filename> ファイルにライブラリへのパスを追加する</title>
     <programlisting role="php">
<![CDATA[
;;;;;;;;;;;;;;;;;;;;;;;;;
; Paths and Directories ;
;;;;;;;;;;;;;;;;;;;;;;;;;

; *nix: "/path1:/path2"
include_path = ".:/usr/share/php:/usr/local/lib/Smarty-v.e.r/libs/"

; Windows: "\path1;\path2"
include_path = ".;c:\php\includes;c:\webroot\libs\Smarty-v.e.r\libs\"
]]>
</programlisting>
</example>

<example>
    <title>PHP スクリプト内での <literal><ulink url="&url.php-manual;ini-set">ini_set()</ulink></literal>
     によるインクルードパスの追加</title>
    <programlisting role="php">
<![CDATA[
<?php
// *nix
ini_set('include_path', ini_get('include_path').PATH_SEPARATOR.'/usr/local/lib/Smarty-v.e.r/libs/');

// windows
ini_set('include_path', ini_get('include_path').PATH_SEPARATOR.'c:/webroot/lib/Smarty-v.e.r/libs/');
?>
]]>
    </programlisting>
   </example>

   <para>
    これでライブラリファイルは正常に設置できたので、
    今度はあなたのアプリケーション内に Smarty 用のディレクトリを セットアップしましょう。
   </para>

    <itemizedlist>
    <listitem><para>
    Smarty は、デフォルトで
    <filename class="directory">templates/</filename>、
    <filename class="directory">templates_c/</filename>、<filename
    class="directory">configs/</filename> および <filename
    class="directory">cache/</filename>
    と名づけられた４つのディレクトリが必要です。
    </para></listitem>

    <listitem><para>これらの名前は、それぞれ
    Smarty クラスのプロパティ
    <link linkend="variable.template.dir">
    <varname>$template_dir</varname></link>、
    <link linkend="variable.compile.dir">
    <varname>$compile_dir</varname></link>、
    <link linkend="variable.config.dir">
    <varname>$config_dir</varname></link> および
    <link linkend="variable.cache.dir">
    <varname>$cache_dir</varname></link> で定義することができます。
    </para></listitem>

    <listitem><para>
    Smarty を使用する各アプリケーションにおいて、
    これらのディレクトリを個別に設置する事を強く推奨します。
   </para></listitem>
    </itemizedlist>

    <para>
    インストール例として、ゲストブックアプリケーションの
    Smarty 環境をセットアップしてみます。 
    私達はディレクトリの命名規約の目的についてのみ取り上げました。
    例のアプリケーション名を <literal>guestbook/</literal>
    からあなたのアプリケーション名に置き換えれば、同様の環境を使用できます。 
    </para>


   <example>
    <title>ファイル構造</title>
    <screen>
<![CDATA[
/usr/local/lib/Smarty-v.e.r/libs/
        Smarty.class.php
        Smarty_Compiler.class.php
        Config_File.class.php
        debug.tpl
        internals/*.php
        plugins/*.php

/web/www.example.com/
        guestbook/
                templates/
                    index.tpl
                templates_c/
                configs/
                cache/
                htdocs/
                    index.php
]]>
    </screen>
   </example>

   <para>
    あなたは web サーバのドキュメントルートの位置を知っている必要があります。
    例ではドキュメントルートは <filename
    class="directory">/web/www.example.com/guestbook/htdocs/</filename>
    とします。Smarty ディレクトリは Smarty ライブラリによってのみアクセスされ、
    web ブラウザから直接アクセスされる事はありません。
    したがってセキュリティの心配を避けるために、
    これらのディレクトリをドキュメントルートの <emphasis>外部</emphasis>
    に配置する事を推奨します (ただし必須ではありません)。
   </para>

   <para>
    ドキュメントルート下には最低１つのファイルが必要であり、
    それは web ブラウザによってアクセスされるスクリプトです。
    この例ではドキュメントルート <filename class="directory">/htdocs/</filename>
    の下にサブディレクトリを作成し、その中に <filename>index.php</filename>
    を配置します。
   </para>


   <para>
    Smarty は
    <link linkend="variable.compile.dir">
    <parameter>$compile_dir</parameter></link> と
    <link linkend="variable.cache.dir">
    <parameter>$cache_dir</parameter></link>
    (<filename class="directory">templates_c/</filename> と
    <filename class="directory">cache/</filename>) に
    <emphasis role="bold">書き込み権限</emphasis> でアクセスする必要があるので、
    web サーバのユーザがこれらに書き込める必要があります
    (windows ユーザはこの話を無視してください)。

    <note><para>通常は、このユーザは <quote>nobody</quote> でグループは
    <quote>nobody</quote> です。OS X ユーザの場合は、デフォルトのユーザは
    <quote>www</quote> でグループは <quote>www</quote> です。
    もし Apache を使用しているなら、<filename>httpd.conf</filename>
    ファイルを見ればユーザ名とグループ名がわかります。</para></note>
    </para>

   <example>
    <title>パーミッションおよびディレクトリへの書き込み権限の付与</title>
    <programlisting role="shell">
<![CDATA[
chown nobody:nobody /web/www.example.com/guestbook/templates_c/
chmod 770 /web/www.example.com/guestbook/templates_c/

chown nobody:nobody /web/www.example.com/guestbook/cache/
chmod 770 /web/www.example.com/guestbook/cache/
]]>
    </programlisting>
   </example>

   <note>
    <title>注意</title>
    <para>
     <literal>chmod 770</literal> は強固なセキュリティです。
     これは、ユーザ <quote>nobody</quote> とグループ <quote>nobody</quote>
     のみにディレクトリのリード/ライトアクセスを許可します。
     もし誰にでもリードアクセスを可能にしたい場合
     (大抵はあなた自身がファイルを見るための利便性から)
     は、代わりに <literal>775</literal> を使う事が出来ます。
    </para>
   </note>

   <para>
    次に、Smarty が表示するファイル <filename>index.tpl</filename>
    を作成する必要があります。これは、<link linkend="variable.template.dir">
    <parameter>$template_dir</parameter></link> の中に配置しなければなりません。
   </para>

   <example>
    <title>/web/www.example.com/guestbook/templates/index.tpl</title>
    <screen>
<![CDATA[
{* Smarty *}

こんにちは、{$name}。ようこそ Smarty へ!
]]>
    </screen>
   </example>

   <note>
    <title>テクニカルノート</title>
    <para>
     <literal>{* Smarty *}</literal> はテンプレートの
     <link linkend="language.syntax.comments">コメント</link> です。
     これは必須ではありませんが、全てのテンプレートファイルのはじめに
     コメントを書くのは良い習慣です。
     これは、ファイルの拡張子に関わらずファイルを認識する事を簡単にします。
     例えば、テキストエディタはファイルを認識して特有のシンタックスハイライトを有効にするでしょう。
    </para>
   </note>

   <para>
    では、<filename>index.php</filename> を編集しましょう。
    Smarty のインスタンスを作成し、テンプレート変数を割り当て
    (<link linkend="api.assign"><varname>assign()</varname></link>)、
    <filename>index.tpl</filename> ファイルを表示
    (<link linkend="api.display"><varname>display()</varname></link>)
    します。
   </para>

   <example>
    <title>/web/www.example.com/docs/guestbook/index.php の編集</title>
    <programlisting role="php">
<![CDATA[
<?php

require_once(SMARTY_DIR . 'Smarty.class.php');

$smarty = new Smarty();

$smarty->template_dir = '/web/www.example.com/guestbook/templates/';
$smarty->compile_dir  = '/web/www.example.com/guestbook/templates_c/';
$smarty->config_dir   = '/web/www.example.com/guestbook/configs/';
$smarty->cache_dir    = '/web/www.example.com/guestbook/cache/';

$smarty->assign('name','Ned');

//** 次の行のコメントをはずすと、デバッギングコンソールを表示します
//$smarty->debugging = true;

$smarty->display('index.tpl');

?>
]]>
    </programlisting>
   </example>

   <note>
    <title>注意</title>
    <para>
     この例では、Smartyのディレクトリすべてを絶対パスで設定しています。
     もし <filename
     class="directory">/web/www.example.com/guestbook/</filename>
     が PHP の include_path にあるのなら、これらの設定は必要ありません。
     けれどもこれらを絶対パスで指定する方が より効率的で、(経験上)エラーが少なくなります。
     そうすれば、Smarty はあなたが意図したディレクトリからファイルを確実に取得できます。 
    </para>
   </note>

   <para>
    では、web ブラウザから <filename>index.php</filename> ファイルを読み込んでみましょう。
    <emphasis>"こんにちは、Ned。ようこそ Smarty へ!"</emphasis> と表示されるはずです。
   </para>
   <para>
    これで Smarty の基本的なセットアップは完了しました！
   </para>
  </sect1>





  <sect1 id="installing.smarty.extended">
   <title>拡張セットアップ</title>

   <para>
    これは、<link
    linkend="installing.smarty.basic">基本的なインストール</link>
    の続きです。まず先にこちらから読んで下さい！
   </para>
   <para>
    Smarty をより柔軟にするセットアップ方法は、
    <ulink url="&url.php-manual;ref.classobj">クラスを拡張</ulink>
    してあなたの Smarty の環境を初期化する事です。
    ディレクトリパスの設定を同じ変数に何度も割り当てる代わりに、一箇所でそれらを行う事が出来ます。
    </para>
    <para>
    新しいディレクトリ<filename
    class="directory">/php/includes/guestbook/</filename>
     を作成し、<filename>setup.php</filename> という新しいファイルを作成しましょう。
     この例の環境では <filename class="directory">/php/includes</filename>
     が <literal>include_path</literal> です。
     例と同じようにするか、あるいは絶対パスを使用して下さい。
   </para>

   <example>
    <title>/php/includes/guestbook/setup.php</title>
    <programlisting role="php">
<![CDATA[
<?php

// Smartyライブラリを読み込みます
require('Smarty.class.php');

// setup.phpはアプリケーションに必要なライブラリファイルを
// 読み込むのに適した場所です。それをここで行うことができます。例:
// require('guestbook/guestbook.lib.php');

class Smarty_GuestBook extends Smarty {

   function Smarty_GuestBook()
   {

        // クラスのコンストラクタ。
        // これらは新しいインスタンスで自動的にセットされます。

        $this->Smarty();

        $this->template_dir = '/web/www.example.com/guestbook/templates/';
        $this->compile_dir  = '/web/www.example.com/guestbook/templates_c/';
        $this->config_dir   = '/web/www.example.com/guestbook/configs/';
        $this->cache_dir    = '/web/www.example.com/guestbook/cache/';

        $this->caching = true;
        $this->assign('app_name', 'Guest Book');
   }

}
?>
]]>
    </programlisting>
   </example>

  <para>
   では、<filename>index.php</filename> ファイルを修正し、
   <filename>setup.php</filename> を使うようにしてみましょう。
  </para>

  <example>
   <title>/web/www.example.com/guestbook/htdocs/index.php</title>
   <programlisting role="php">
<![CDATA[
<?php

require('guestbook/setup.php');

$smarty = new Smarty_GuestBook();

$smarty->assign('name','Ned');

$smarty->display('index.tpl');
?>
]]>
   </programlisting>
  </example>

  <para>
   このように、アプリケーションのために全てを自動的に初期化する
   <literal>Smarty_GuestBook()</literal>
   クラスを使う事で、Smarty のインスタンスをとても簡単に作成することができました。 
  </para>

  </sect1>

 </chapter>
</part>

<!-- 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
-->