documentation/manual/ja/module_specs/Zend_View-Helpers-HeadScript.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <!-- EN-Revision: 19432 -->
   4 <sect3 id="zend.view.helpers.initial.headscript">
   5     <title>HeadScript ヘルパー</title>
   6
   7     <para>
   8         HTML の <code>&lt;script&gt;</code> 要素を使用して、
   9         クライアントサイトのスクリプトをインラインで指定したり
  10         外部のリソースからスクリプトのコードを読み込んだりします。
  11         <code>HeadScript</code> ヘルパーは、この両方の方式に対応しています。
  12     </para>
  13
  14     <para>
  15         <code>HeadScript</code> ヘルパーは、
  16         以下のメソッド群によってスクリプトの設定や追加をサポートします。
  17     </para>
  18
  19     <itemizedlist>
  20         <listitem><para><code>appendFile($src, $type = 'text/javascript',
  21                     $attrs = array())</code></para></listitem>
  22         <listitem><para><code>offsetSetFile($index, $src, $type = 'text/javascript',
  23                     $attrs = array())</code></para></listitem>
  24         <listitem><para><code>prependFile($src, $type = 'text/javascript',
  25                     $attrs = array())</code></para></listitem>
  26         <listitem><para><code>setFile($src, $type = 'text/javascript',
  27                     $attrs = array())</code></para></listitem>
  28         <listitem><para><code>appendScript($script, $type = 'text/javascript',
  29                     $attrs = array())</code></para></listitem>
  30         <listitem><para><code>offsetSetScript($index, $script, $type = 'text/javascript',
  31                     $attrs = array())</code></para></listitem>
  32         <listitem><para><code>prependScript($script, $type = 'text/javascript',
  33                     $attrs = array())</code></para></listitem>
  34         <listitem><para><code>setScript($script, $type = 'text/javascript',
  35                     $attrs = array())</code></para></listitem>
  36     </itemizedlist>
  37
  38     <para>
  39         <code>*File()</code> 系のメソッドでは、<varname>$src</varname>
  40         は読み込みたいリモートスクリプトの場所となります。
  41         通常は、<acronym>URL</acronym> あるいはパスの形式となります。<code>*Script()</code>
  42         系のメソッドでは、<varname>$script</varname>
  43         はその要素に使用したいクライアント側のスクリプトとなります。
  44     </para>
  45
  46     <note>
  47         <title>条件コメントの設定</title>
  48
  49         <para>
  50             <code>HeadScript</code> では、script タグを条件コメントで囲むことができます。
  51             そうすれば、特定のブラウザでだけスクリプトを実行しないこともできます。
  52             これを使用するには conditional タグを設定し、条件をメソッドコール時の
  53             <varname>$attrs</varname> パラメータで渡します。
  54         </para>
  55
  56         <example id="zend.view.helpers.initial.headscript.conditional">
  57             <title>Headscript で条件コメントを使う例</title>
  58             <programlisting language="php"><![CDATA[
  59 // スクリプトを追加します
  60 $this->headScript()->appendFile(
  61     '/js/prototype.js',
  62     'text/javascript',
  63     array('conditional' => 'lt IE 7')
  64 );
  65 ]]></programlisting>
  66         </example>
  67     </note>
  68
  69     <para>
  70         <code>HeadScript</code> はスクリプトのキャプチャも行います。
  71         これは、クライアント側スクリプトをプログラム上で作成してから
  72         どこか別の場所で使いたい場合に便利です。
  73         使用法は、以下の例で示します。
  74     </para>
  75
  76     <para>
  77         <methodname>headScript()</methodname> メソッドを使うと、
  78         スクリプト要素を手っ取り早く追加できます。
  79         シグネチャは
  80         <methodname>headScript($mode = 'FILE', $spec, $placement = 'APPEND')</methodname>
  81         です。<varname>$mode</varname> は 'FILE' あるいは 'SCRIPT' のいずれかで、
  82         スクリプトへのリンクを指定するのかスクリプト自体を定義するのかによって切り替えます。
  83         <varname>$spec</varname> は、リンクするスクリプトファイルあるいはスクリプトのソースとなります。
  84         <varname>$placement</varname> は 'APPEND'、'PREPEND' あるいは 'SET'
  85         のいずれかでなければなりません。
  86     </para>
  87
  88     <para>
  89         <code>HeadScript</code> は <methodname>append()</methodname> や
  90         <methodname>offsetSet()</methodname>、<methodname>prepend()</methodname>、そして <methodname>set()</methodname>
  91         をそれぞれオーバーライドして、上にあげた特別なメソッドを使用させるようにします。
  92         内部的には、各項目を <code>stdClass</code> のトークンとして保管し、
  93         あとで <methodname>itemToString()</methodname> メソッドでシリアライズします。
  94         これはスタック内の項目についてチェックを行い、
  95         オプションでそれを修正したものを返します。
  96     </para>
  97
  98     <para>
  99         <code>HeadScript</code> ヘルパーは、
 100         <link linkend="zend.view.helpers.initial.placeholder">Placeholder
 101         ヘルパー</link> の具象実装です。
 102     </para>
 103
 104     <note>
 105         <title>HTML Body スクリプトでの InlineScript の使用</title>
 106
 107         <para>
 108             HTML の <code>body</code> 部にスクリプトを埋め込みたい場合は、
 109             <code>HeadScript</code> の姉妹版である <link
 110                 linkend="zend.view.helpers.initial.inlinescript">InlineScript</link>
 111             を使わなければなりません。
 112             スクリプトをドキュメントの最後のほうに配置するようにすると、
 113             ページの表示速度が向上します。特に、
 114             サードパーティのアクセス解析用スクリプトを使用する場合などにこの効果が顕著にあらわれます。
 115         </para>
 116     </note>
 117
 118     <note>
 119         <title>すべての属性はデフォルトで無効</title>
 120
 121         <para>
 122             デフォルトでは、<code>HeadScript</code> がレンダリングする
 123             <code>&lt;script&gt;</code> の属性は W3C
 124             に認められているものだけです。
 125             'type' や 'charset'、'defer'、'language' そして 'src' が該当します。
 126             しかし、Javascript のフレームワーク
 127             (<ulink url="http://www.dojotoolkit.org/">Dojo</ulink> など)
 128             では独自の属性を用いることでその挙動を変更しています。
 129             このような属性を許可するには、
 130             <methodname>setAllowArbitraryAttributes()</methodname> メソッドを使用します。
 131         </para>
 132
 133         <programlisting language="php"><![CDATA[
 134 $this->headScript()->setAllowArbitraryAttributes(true);
 135 ]]></programlisting>
 136     </note>
 137
 138     <example id="zend.view.helpers.initial.headscript.basicusage">
 139         <title>HeadScript ヘルパーの基本的な使用法</title>
 140
 141         <para>
 142             上で説明したように、新しい script タグを、好きなときに指定できます。
 143             外部のリソースへのリンクも可能ですし、
 144             スクリプト自体を指定することも可能です。
 145         </para>
 146
 147         <programlisting language="php"><![CDATA[
 148 // スクリプトを追加します
 149 $this->headScript()->appendFile('/js/prototype.js')
 150                    ->appendScript($onloadScript);
 151 ]]></programlisting>
 152
 153         <para>
 154             クライアント側のスクリプトでは並び順が重要となります。
 155             指定した並び順で出力させる必要が出てくることでしょう。
 156             そのために使用するのが、append、prepend そして offsetSet
 157             といったディレクティブです。
 158         </para>
 159
 160         <programlisting language="php"><![CDATA[
 161 // スクリプトの順番を指定します
 162
 163 // 特定の位置を指定し、確実に最後に読み込まれるようにします
 164 $this->headScript()->offsetSetFile(100, '/js/myfuncs.js');
 165
 166 // scriptaculous のエフェクトを使用します (次のインデックスである 101 に追加されます)
 167 $this->headScript()->appendFile('/js/scriptaculous.js');
 168
 169 // でも、もととなる prototype スクリプトは常に最初に読み込まれるようにします
 170 $this->headScript()->prependFile('/js/prototype.js');
 171 ]]></programlisting>
 172
 173         <para>
 174             すべてのスクリプトを出力する準備が整ったら、
 175             あとはレイアウトスクリプトでそれを出力するだけです。
 176         </para>
 177
 178         <programlisting language="php"><![CDATA[
 179 <?php echo $this->headScript() ?>
 180 ]]></programlisting>
 181     </example>
 182
 183     <example id="zend.view.helpers.initial.headscript.capture">
 184         <title>HeadScript ヘルパーによるスクリプトのキャプチャ</title>
 185
 186         <para>
 187             時にはクライアント側のスクリプトをプログラムで生成しなければならないこともあるでしょう。
 188             文字列の連結やヒアドキュメント等を使っても構いませんが、
 189             ふつうにスクリプトを作成してそれを <acronym>PHP</acronym> のタグに埋め込めればより簡単です。
 190             <code>HeadScript</code> は、スタックにキャプチャすることでこれを実現します。
 191         </para>
 192
 193         <programlisting language="php"><![CDATA[
 194 <?php $this->headScript()->captureStart() ?>
 195 var action = '<?php echo $this->baseUrl ?>';
 196 $('foo_form').action = action;
 197 <?php $this->headScript()->captureEnd() ?>
 198 ]]></programlisting>
 199
 200         <para>
 201             前提条件は次のとおりです。
 202         </para>
 203
 204         <itemizedlist>
 205             <listitem><para>
 206                     スクリプトは、スタックの末尾に追加されていきます。
 207                     既存のスタックを上書きしたりスタックの先頭に追加したりしたい場合は、
 208                     それぞれ 'SET' あるいは 'PREPEND' を
 209                     <methodname>captureStart()</methodname> の最初の引数として渡します。
 210             </para></listitem>
 211
 212             <listitem><para>
 213                     スクリプトの <acronym>MIME</acronym> タイプは 'text/javascript' を想定しています。
 214                     別のものを指定したい場合は、それを
 215                     <methodname>captureStart()</methodname> の 2 番目の引数として渡します。
 216             </para></listitem>
 217
 218             <listitem><para>
 219                     <code>&lt;script&gt;</code> タグに追加の属性を指定したい場合は、
 220                     <methodname>captureStart()</methodname> の 3 番目の引数に配列形式で渡します。
 221             </para></listitem>
 222         </itemizedlist>
 223     </example>
 224 </sect3>
 225 <!--
 226 vim:se ts=4 sw=4 et:
 227 -->