switch to a 60 bit hash

[httpd-crcsyncproxy.git] / docs / manual / howto / ssi.xml.ja

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.ja.xsl"?>
<!-- English Revision: 659902 -->

<!--
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You under the Apache License, Version 2.0
 (the "License"); you may not use this file except in compliance with
 the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
-->

<manualpage metafile="ssi.xml.meta">
<parentdocument href="./">How-To / チュートリアル</parentdocument>

<title>Apache チュートリアル: Server Side Includes 入門</title>

<summary>
<p>サーバサイドインクルードによって、既存の HTML
ドキュメントに動的なコンテンツを追加することができます。</p>
</summary>

<section id="related"><title>はじめに</title>
 <related>
    <modulelist>
    <module>mod_include</module>
    <module>mod_cgi</module>
    <module>mod_expires</module>
    </modulelist>

    <directivelist>
    <directive module="core">Options</directive>
    <directive module="mod_include">XBitHack</directive>
    <directive module="mod_mime">AddType</directive>
    <directive module="core">SetOutputFilter</directive>
    <directive module="mod_setenvif">BrowserMatchNoCase</directive>
    </directivelist>
</related>

    <p>この記事は、通常は単に SSI と呼ばれる Server Side Includes
    を扱います。この記事においては、サーバでの SSI を許可するための設定と、
    現在の HTML ページに動的なコンテンツを加えるためのいくつかの基本的な
    SSI 技術を紹介します。</p>

    <p>記事の後半では、SSI ディレクティブで SSI
    と共に実行することができる条件文のような
    幾分高度な事柄について述べています。</p>

</section>

<section id="what"><title>SSI とは ?</title>

    <p>SSI (Server Side Includes) は、HTML
    ページ中に配置されるディレクティブであり、
    サーバでページを提供する時に評価されます。SSI は、CGI
    プログラムやその他の動的な技術で全てのページを提供せずに、
    動的に生成されたコンテンツを現在の HTML ページに加えます。</p>

    <p>どういう場合に SSI を使い、どういう場合にプログラムで
    ページを完全に生成するかは、ページのうちどの程度が静的であり、
    ページが提供されるたびに再計算する必要がどの程度あるかで通常は決定します。
    SSI は現在時刻のような小さい情報を加えるにはうってつけの方法です。
    しかし、そのページのほとんどの部分が提供時に生成される場合は、
    他の方法を探す必要があります。</p>
</section>

<section id="configuring">
<title>SSI を許可するためのサーバの設定</title>

    <p>サーバで SSI を許可するには、<code>httpd.conf</code>
    ファイルまたは <code>.htaccess</code>
    ファイルに次のディレクティブを指定する必要があります:</p>
<example>
        Options +Includes
</example>

    <p>この指定は、ファイルを SSI
    ディレクティブで解析させることを許可するということを Apache
    に伝えます。ほとんどの設定ではお互いを上書きできる、複数の
    <directive module="core">Options</directive> があることに
    注意してください。おそらく、設定が最後に評価されることを
    保証されるために、SSI を使用したいディレクトリに <code>Options</code>
    ディレクティブを適用する必要があるでしょう。</p>

    <p>全てのファイルが SSI
    ディレクティブで解析されるというわけではありません。
    どのファイルが解析されるかを Apache に伝える必要があります。
    これを行なうには二つ方法があります。
    次のディレクティブを使うことで、例えば <code>.shtml</code>
    のような特別なファイル拡張子を持つファイルを解析するよう
    Apache に伝えることができます:</p>
<example>
        AddType text/html .shtml<br />
        AddOutputFilter INCLUDES .shtml
</example>

    <p>この方法の欠点は、もし現在のページに SSI ディレクティブを加えたい場合、
    それらのディレクティブが実行されるように 
    <code>.shtml</code> 拡張子にするため、そのページの名前と、
    そのページへの全てのリンクを変更しなければならないことです。</p>

    <p>もう一つの方法は、<directive module="mod_include">XBitHack</directive>
    ディレクティブを使用することです:</p>
<example>
        XBitHack on
</example>

    <p><directive module="mod_include">XBitHack</directive> 
    は、ファイルの実行ビットが立っている場合、
    SSI ディレクティブにより解析することを Apache に伝えます。
    従って、SSI ディレクティブを現在のページに加えるためには、
    ファイル名を変更しなくてもよく、単に <code>chmod</code>
    を使用してファイルを実行可能にするだけで済みます。</p>
<example>
        chmod +x pagename.html
</example>

    <p>行なうべきではないことに関する短いコメント。時々誰かが、全ての
    <code>.html</code> ファイルを SSI で解析するよう Apache に伝えれば、
    わざわざ <code>.shtml</code> というファイル名にする必要がないといって
    薦めるのを見ることでしょう。こういう人たちは、おそらく
    <directive module="mod_include">XBitHack</directive>
    について聞いたことがないのでしょう。
    この方法について注意することは、たとえ SSI
    ディレクティブを全く含まない場合でも、Apache がクライアントに
    送る全てのファイルを最後まで読み込ませることになります。
    この方法はかなり処理を遅くするものであり、良くないアイデアです。</p>

    <p>もちろん、Windows ではそのような実行ビットをセット
    するようなものはありませんのでオプションが少し制限されています。</p>

    <p>デフォルトの設定では、Apache は SSI ページについて最終変更時刻や
    コンテンツの長さを HTTP ヘッダに送りません。
    動的なコンテンツであるため、それらの値を計算するのが難しいからです。
    このためドキュメントがキャッシュされなくなり、
    結果としてクライアントの性能が遅くなったように感じさせることになります。
    これを解決する方法が二つあります:</p>

    <ol>
      <li><code>XBitHack Full</code> 設定を使用する。
      この設定により、もともと要求されたファイルの時刻を参照し、
      読み込まれるファイルの変更時刻を無視して最終変更時刻を決定するよう
      Apache に伝えます。</li>

      <li><a href="../mod/mod_expires.html">mod_expires</a>
      で提供されているディレクティブを使用して、
      ファイルが無効になる時刻を明示します。これにより、
      ブラウザとプロキシにキャッシュが有効であることを通知します。</li>
    </ol>
</section>

<section id="basic"><title>基本的な SSI ディレクティブ</title>

    <p>SSI ディレクティブは以下の文法で記述します:</p>
<example>
        &lt;!--#element attribute=value attribute=value ... --&gt;
</example>

    <p>HTML のコメントのような書式をしているので、もし SSI
    を正しく動作可能にしなければ、ブラウザはそれを無視するでしょう。
    しかし、HTML ソース中では見えます。もし SSI を正しく設定したなら、
    ディレクティブはその結果と置き換えられます。</p>

    <p>element はたくさんあるものから一つ指定することができます。
    指定できるものの大多数については、次回もう少し詳しく説明します。
    ここでは、SSI で行なうことができる例をいくつか示します。</p>

<section id="todaysdate"><title>今日の日付</title>

<example>
        &lt;!--#echo var="DATE_LOCAL" --&gt;
</example>

    <p><code>echo</code> 要素は単に変数の値を出力します。
    CGI プログラムに利用可能な環境変数の全ての
    セットを含む多くの標準変数があります。また、<code>set</code>
    要素を用いることで、独自の変数を定義することができます。
    </p>

    <p>出力される日付の書式が好きではない場合、その書式を修正するために、
    <code>config</code> 要素に <code>timefmt</code>
    属性を使用することができます。</p>

<example>
        &lt;!--#config timefmt="%A %B %d, %Y" --&gt;<br />
        Today is &lt;!--#echo var="DATE_LOCAL" --&gt;
</example>
</section>

<section id="lastmodified"><title>ファイルの変更日</title>

<example>
        This document last modified &lt;!--#flastmod file="index.html" --&gt;
</example>

    <p>この要素も <code>timefmt</code>
    フォーマットの設定に従います。</p>
</section>

<section id="cgi"><title>CGI プログラムの結果を取り込む</title>

    <p>これは、全ての人のお気に入りである ``ヒットカウンタ'' のような
    CGI プログラムの結果を出力する SSI
    のより一般的な使用のうちの一つです。</p>

<example>
        &lt;!--#include virtual="/cgi-bin/counter.pl" --&gt;
</example>

</section>
</section>

<section id="additionalexamples">
<title>追加の例</title>

    <p>以下は、SSI を使用して HTML
    ドキュメントにおいてできることのいくつかの特別な例です。</p>

<section id="docmodified"><title>いつこのドキュメントは修正されたのか
?</title>

    <p>先に、ドキュメントが最後に変更されたのはいつかを
    ユーザに通知するために SSI を使用することができることを述べました。
    しかしながら、実際の方法は、いくぶん問題のままにしておきました。
    HTML ドキュメントに配置された次のコードは、ページにそのような
    タイムスタンプを入れるでしょう。もちろん、上述のように、
    SSI を正しく動作可能にしておく必要があります。</p>
<example>
        &lt;!--#config timefmt="%A %B %d, %Y" --&gt;<br />
        This file last modified &lt;!--#flastmod file="ssi.shtml" --&gt;
</example>

    <p>もちろん、<code>ssi.shtml</code>
    の部分を実際の当該ファイル名と置き換える必要があります。
    もし、あらゆるファイルに張ることができる一般的なコードを探しているなら、
    これは不便であるかもしれません。おそらくその場合は、
    そうする代わりに変数 <code>LAST_MODIFIED</code>
    を使用したいと考えるでしょう:</p>
<example>
        &lt;!--#config timefmt="%D" --&gt;<br />
        This file last modified &lt;!--#echo var="LAST_MODIFIED" --&gt;
</example>

    <p><code>timefmt</code>
    書式についてのより詳細については、お好みの検索サイトに行き、
    <code>strftime</code> で検索してみてください。文法は同じです。</p>
</section>

<section id="standard-footer">
<title>標準のフッタを挿入する</title>

    <p>もし数ページを超えるページを持つサイトを管理しているならば、
    全ページに対して変項を行なうことが本当に苦痛となり得ることが
    分かるでしょう。全てのページに渡ってある種の標準的な外観を
    維持しようとしているならば特にそうでしょう。</p>

    <p>ヘッダやフッタ用の挿入用ファイルを使用することで、
    このような更新にかかる負担を減らすことができます。
    一つのフッタファイルを作成し、それを <code>include</code>
    SSI コマンドで各ページに入れるだけで済みます。<code>include</code>
    要素は、<code>file</code> 属性または <code>virtual</code>
    属性のいずれかを使用してどのファイルを挿入するかを決めることができます。
    <code>file</code> 属性は、<em>カレントディレクトリからの相対パスで示された
    </em>ファイルパスです。
    それは / で始まる絶対ファイルパスにはできず、また、そのパスの一部に ../
    を含むことができないことを意味します。<code>virtual</code>
    属性は、おそらくより便利だと思いますが、提供するドキュメントからの相対
    URL で指定すべきです。それは / で始めることができますが、
    提供するファイルと同じサーバ上に存在しなくてはなりません。</p>
<example>
        &lt;!--#include virtual="/footer.html" --&gt;
</example>

    <p>私は最後の二つを組み合わせて、<code>LAST_MODIFIED</code>
    ディレクティブをフッタファイルの中に置くことがよくあります。
    SSI ディレクティブは、挿入用のファイルに含ませたり、
    挿入ファイルのネストをしたりすることができます。すなわち、
    挿入用のファイルは他のファイルを再帰的に挿入することができます。</p>
</section>

</section>

<section id="config">
<title>他に何が設定できるのか ?</title>

    <p>時刻書式を <code>config</code> で設定できることに加えて、
    更に二つ <code>config</code> で設定することができます。</p>

    <p>通常、SSI ディレクティブで何かがうまくいかないときは、
    次のメッセージが出力されます。</p>
<example>
        [an error occurred while processing this directive]
</example>

    <p>このメッセージを他のものにしたい場合、<code>config</code>
    要素の <code>errmsg</code> 属性で変更することができます:</p>
<example>
        &lt;!--#config errmsg="[It appears that you don't know how to use SSI]" --&gt;
</example>

    <p>おそらく、エンドユーザはこのメッセージを決して見ることはありません。
    なぜなら、そのサイトが生きた状態になる前に SSI ディレクティブに関する
    全ての問題を解決しているはずだからです。(そうですよね?)</p>

    <p>そして、<code>config</code> において <code>sizefmt</code>
    属性を使用することで、
    返されるファイルサイズの書式を設定することができます。
    バイト数には <code>bytes</code> を、適当に Kb や Mb
    に短縮させるには <code>abbrev</code> を指定することができます。</p>
    </section>

<section id="exec">
    <title>コマンドの実行</title>

    <p>今後数ヶ月のうちに、小さな CGI プログラムと SSI
    を使用する記事を出したいと考えています。ここではそれとは別に、
    <code>exec</code> 要素によって行なうことができることを示します。
    SSI にシェル (正確には <code>/bin/sh</code>。Win32 ならば DOS シェル)
    を使用してコマンドを実行させることができます。
    下記の例では、ディレクトリリスト出力を行ないます。</p>
<example>
        &lt;pre&gt;<br />
        &lt;!--#exec cmd="ls" --&gt;<br />
        &lt;/pre&gt;
</example>

    <p>Windows 上では、</p>
<example>
        &lt;pre&gt;<br />
        &lt;!--#exec cmd="dir" --&gt;<br />
        &lt;/pre&gt;
</example>

    <p>Windows 上では、このディレクティブによっていくつかの奇妙な
    書式に気づくでしょう。なぜなら <code>dir</code> の出力が文字列
    ``&lt;<code>dir</code>&gt;'' を含み、ブラウザを混乱させるからです。</p>

    <p>この機能は非常に危険であり、どんなコードでも <code>exec</code>
    タグに埋め込まれてしまえば実行することに注意してください。例えば 
    `` ゲストブック '' のように、もし、
    ユーザがページの内容を編集できる状況にあるならば、
    この機能を確実に抑制してください。<code>Options</code>
    ディレクティブの <code>IncludesNOEXEC</code> 引数を指定することで、
    SSI は許可するけれど <code>exec</code>
    機能は許可しないようにすることができます。</p>
    </section>

<section id="advanced">
<title>高度な SSI テクニック</title>

    <p>コンテンツを出力することに加え、Apache SSI は変数を設定し、
    そして比較と条件分岐にその変数を使用できる機能を提供しています。
    </p>

<section id="caveat"><title>警告</title>

    <p>この記事で述べた大部分の機能は、Apache 1.2
    以降を使用している場合のみ利用可能です。もちろん、もし Apache 1.2
    以降を使用してない場合、直ちにアップグレードする必要があります。
    さぁ、今それを行ないなさい。それまで待っています。</p>
</section>

<section id="variables"><title>変数を設定する</title>

    <p><code>set</code> ディレクティブを使用して、
    後で使用するために変数を設定することができます。
    これは後の説明で必要になるので、ここでそれについて述べています。
    文法は以下のとおりです:</p>
<example>
        &lt;!--#set var="name" value="Rich" --&gt;
</example>

    <p>このように単純に文字どおりに設定することに加え、
    <a href="../env.html">環境変数</a>や上記の変数
    (例えば <code>LAST_MODIFIED</code> のような)
    を含む他のあらゆる変数を値を設定するのに使用することができます。
    変数名の前にドル記号 ($) を使用することで、
    それがリテラル文字列ではなくて変数であることを示します。</p>
<example>
        &lt;!--#set var="modified" value="$LAST_MODIFIED" --&gt;
</example>

    <p>ドル記号 ($) を文字として変数の値に入れるには、
    バックスラッシュによってドル記号をエスケープする必要があります。</p>
<example>
        &lt;!--#set var="cost" value="\$100" --&gt;
</example>

    <p>最後になりますが、長い文字列の中に変数を置きたい場合で、
    変数名が他の文字とぶつかる可能性があり、
    それらの文字について混乱してしまう場合、この混乱を取り除くため、
    変数名を中括弧で囲むことができます
    (これについての良い例を示すのは難しいのですが、
    おそらく分かっていただけるでしょう)。
    </p>
<example>
        &lt;!--#set var="date" value="${DATE_LOCAL}_${DATE_GMT}" --&gt;
</example>
</section>

<section id="conditional">
<title>条件式</title>

    <p>さて、変数を持っていて、
    それらの値を設定して比較することができるのですから、
    条件を表すためにそれらを使用することができます。これにより
    SSI はある種の小さなプログラミング言語になっています。
    <module>mod_include</module> は条件を表現するために <code>if</code>,
    <code>elif</code>, <code>else</code>, <code>endif</code>
    構造を提供しています。これによって、
    一つの実際のページから複数の論理ページを効果的に生成することができます。</p>

    <p>条件構造は以下のとおりです:</p>
<example>
    &lt;!--#if expr="test_condition" --&gt;<br />
    &lt;!--#elif expr="test_condition" --&gt;<br />
    &lt;!--#else --&gt;<br />
    &lt;!--#endif --&gt;
</example>

    <p><em>test_condition</em>
    はあらゆる種類の論理的比較をすることができます。
    値を比較したり、その値が ``真'' かどうかを評価します
    (空でないなら与えられた文字列は真です)。
    利用可能な比較演算子の全てのリストについては、
    <module>mod_include</module> ドキュメンテーションを参照してください。
    ここでは、この構造をどう使用するかの例をいくつか示します。</p>

    <p>設定ファイルで次の行を記述します:</p>
<example>
        BrowserMatchNoCase macintosh Mac<br />
        BrowserMatchNoCase MSIE InternetExplorer
</example>

    <p>これはクライアントが Macintosh
    上でインターネットエクスプローラが動いている場合、環境変数
    ``Mac'' と ``InternetExplorer'' を真と設定します。</p>

    <p>次に、SSI が可能になったドキュメントで以下を行ないます:
    </p>
<example>
        &lt;!--#if expr="${Mac} &amp;&amp; ${InternetExplorer}" --&gt;<br />
        Apologetic text goes here<br />
        &lt;!--#else --&gt;<br />
        Cool JavaScript code goes here<br />
        &lt;!--#endif --&gt;
</example>

    <p>Mac 上の IE に対して何か思うところがあるわけでありません。
    他では実行できているいくつかの JavaScript を Mac 上の IE
    で実行させるのに、先週数時間苦労したというだけのことです。
    上の例はその暫定的な対処方法です。</p>

    <p>他のどんな変数 (あなたが定義するもの、
    または普通の環境変数のいずれか) も、条件文に使用することができます。
    Apache は <code>SetEnvIf</code> ディレクティブや他の関連
    ディレクティブを使用して環境変数を設定することができます。
    この機能により、CGI
    に頼ることなくかなり複雑な動的なことをさせることができます。</p>
</section>
</section>

<section id="conclusion"><title>終わりに</title>

    <p>SSI は確かに CGI
    や動的なウェブページを生成する他の技術に代わるものではありません。
    しかし、たくさんの余分な作業をせずに、
    少量の動的なコンテンツを加えるにはすぐれた方法です。</p>
</section>

</manualpage>