Dojo には、オートコンプリートのためだけのウィジェットはありません。 しかし、ComboBox と FilteringSelect のふたつのウィジェットがオートコンプリート機能を持っています。 どちらのウィジェットも、QueryReadStore を実装したデータを必要とします。詳細は » dojo.data のドキュメントを参照ください。

Zend Framework では、単純な数値添字の配列を AutoCompleteDojo ヘルパーに渡します。 そうすると、適切な形式の JSON オブジェクトを返します。

<?php
// コントローラのアクション内で
$this->_helper->autoCompleteDojo($data);

dojo.provide("custom.TestNameReadStore");
dojo.declare("custom.TestNameReadStore", dojox.data.QueryReadStore, {
    fetch:function (request) {
        request.serverQuery = { test:request.query.name };
        return this.inherited("fetch", arguments);
    }
});

<?php
class TestController extends Zend_Controller_Action
{
    protected $_form;

    public function getForm()
    {   
        if (null === $this->_form) {
            require_once 'Zend/Form.php';
            $this->_form = new Zend_Form();
            $this->_form->setMethod('get')
                ->setAction($this->getRequest()->getBaseUrl() . '/test/process')
                ->addElements(array(
                    'test' => array('type' => 'text', 'options' => array(
                        'filters'        => array('StringTrim'),
                        'dojoType'       => array('dijit.form.ComboBox'),
                        'store'          => 'testStore',
                        'autoComplete'   => 'false',
                        'hasDownArrow'   => 'true',
                        'label' => 'Your input:',
                    )),
                    'go' => array('type' => 'submit', 'options' => array('label' => 'Go!'))
                ));
        }
        return $this->_form;
    }
}

<?php
class TestController extends Zend_Controller_Action
{
    // ...

    /**
     * 最初のページ
     */
    public function indexAction()
    {
        $this->view->form = $this->getForm();
    }

    public function autocompleteAction()
    {
        if ('ajax' != $this->_getParam('format', false)) {
            return $this->_helper->redirector('index');
        }
        if ($this->getRequest()->isPost()) {
            return $this->_helper->redirector('index');
        }

        $match = trim($this->getRequest()->getQuery('test', ''));

        $matches = array();
        foreach ($this->getData() as $datum) {
            if (0 === strpos($datum, $match)) {
                $matches[] = $datum;
            }
        }
        $this->_helper->autoCompleteDojo($matches);
    }
}

<? // データストアの準備 ?>
<div dojoType="custom.TestNameReadStore" jsId="testStore"
    url="<?= $this->baseUrl() ?>/unit-test/autocomplete/format/ajax" requestMethod="get"></div>

<? // フォームのレンダリング ?>
<?= $this->form ?>

<? // Dojo 関連の CSS の、HTML head での読み込み ?>
<? $this->headStyle()->captureStart() ?>
@import "<?= $this->baseUrl() ?>/javascript/dijit/themes/tundra/tundra.css";
@import "<?= $this->baseUrl() ?>/javascript/dojo/resources/dojo.css";
<? $this->headStyle()->captureEnd() ?>

<? // 必要な Dojo ライブラリを含む javascript の、
   // HTML head での読み込み ?>
<? $this->headScript()
        ->setAllowArbitraryAttributes(true)
        ->appendFile($this->baseUrl() . '/javascript/dojo/dojo.js', 
            'text/javascript', 
            array('djConfig' => 'parseOnLoad: true'))
        ->captureStart() ?>
djConfig.usePlainJson=true;
dojo.registerModulePath("custom","../custom");
dojo.require("dojo.parser");
dojo.require("dojox.data.QueryReadStore");
dojo.require("dijit.form.ComboBox");
dojo.require("custom.TestNameReadStore");
<? $this->headScript()->captureEnd() ?>

» Scriptaculous は、所定の形式の HTML レスポンスを受け取ることを想定しています。

このライブラリで使用するヘルパーは 'AutoCompleteScriptaculous' です。 このヘルパーにデータの配列を渡せば、Ajax.Autocompleter に対応した形式の HTML レスポンスができあがります。

ContextSwitch ヘルパーで 使用できるデフォルトのコンテキストは、json と xml のふたつです。

• JSON。JSON コンテキストは、 'Content-Type' レスポンスヘッダを 'application/json' に設定し、 ビュースクリプトのサフィックスを 'json.phtml' とします。

  しかし、デフォルトではビュースクリプトは不要です。 これは、すべてのビュー変数を単純にシリアライズして JSON レスポンスを直接発行するものです。

  自動 JSON シリアライズ機能を使わないようにすることもできます。

  <?php
  $this->_helper->contextSwitch()->setAutoJsonSerialization(false);
  ?>

• XML。XML コンテキストは、 'Content-Type' レスポンスヘッダを 'text/xml' に設定し、 ビュースクリプトのサフィックスを 'xml.phtml' とします。 このコンテキスト用に、新しいビュースクリプトを作成する必要があります。

デフォルトのコンテキストだけでは対応しきれないこともあるでしょう。 たとえば結果を YAML で返したり、PHP のシリアライズ文字列で返したり、 あるいは RSS や ATOM フィードで返したりといったようにです。 ContextSwitch を使用すればそれも可能です。

新たなコンテキストを追加する最も簡単な方法は addContext() メソッドを使用することです。 このメソッドの引数は 2 つで、コンテキストの名前と 設定の配列を指定します。設定には、以下のうちのひとつあるいは複数を指定します。

• suffix: ViewRenderer で登録されているデフォルトのビューサフィックスの 前に追加するサフィックス。

• headers: ヘッダ/値 のペアの配列で、レスポンスとともに送信したいもの。

• callbacks: キー 'init' や 'post' を含む配列で、それぞれ コンテキストの初期化や後処理の際に使用する PHP コールバックを指定します。

  初期化コールバックは、ContextSwitch が コンテキストを検出した場合に実行されます。 これを使用して、任意のロジックを実行することができます。 たとえば JSON コンテキストでは、 このコールバックを使用して 自動 JSON シリアライズが有効な場合に ViewRenderer を無効化しています。

  後処理はアクションの postDispatch() で発生します。これを使用して、任意のロジックを実行することができます。 たとえば JSON コンテキストでは、このコールバックを使用して 自動 JSON シリアライズ機能が有効か無効かを調べています。 有効な場合はビュー変数を JSON にシリアライズしてレスポンスに送信し、 無効な場合は ViewRenderer を再度有効にします。

コンテキストを操作するメソッドには次のようなものがあります。

• addContext($context, array $spec): 新しいコンテキストを追加する。 そのコンテキストが既に存在する場合は例外をスローします。

• setContext($context, array $spec): 新しいコンテキストを追加、あるいは既存のコンテキストを上書きする。 addContext() と同じように指定します。

• addContexts(array $contexts): 複数のコンテキストを一度に追加する。配列 $contexts は、コンテキスト/設定 のペアの配列となります。 既に存在するコンテキストを指定した場合は例外をスローします。

• setContexts(array $contexts): 新しいコンテキストを追加、あるいは既存のコンテキストを上書きする。 addContexts() と同じように指定します。

• hasContext($context): そのコンテキストが存在する場合に true、存在しない場合に false を返します。

• getContext($context): 指定した名前のコンテキストを取得する。 addContext() で使用する設定とあわせた配列を返します。

• getContexts(): すべてのコンテキストを取得する。 コンテキスト/設定 のペアの配列を返します。

• removeContext($context): 指定した名前のコンテキストを削除する。成功した場合に true、 そのコンテキストが見つからない場合に false を返します。

• clearContexts(): すべてのコンテキストを削除する。

使用するコンテキストの設定には 2 通りの方法があります。 コントローラ内で手動で配列を作成する方法、 そして ContextSwitch のメソッドでそれを作成する方法です。

アクションとコンテキストの関連を追加するメソッドは addActionContext() です。 このメソッドには 2 つの引数を指定します。 ひとつはコンテキストを追加したいアクション、 もうひとつはコンテキスト名あるいはコンテキスト名の配列です。 たとえば、次のようなコントローラクラスを考えてみましょう。

<?php
class FooController extends Zend_Controller_Action
{
    public function listAction()
    {
    }

    public function viewAction()
    {
    }

    public function commentsAction()
    {
    }

    public function updateAction()
    {
    }
}
?>

ここで、'list' アクションに XML コンテキストを、 そして 'comments' アクションに XML コンテキストと JSON コンテキストを追加してみることにします。これは init() メソッドで行います。

<?php
class FooController extends Zend_Controller_Action
{
    public function init()
    {
        $this->_helper->contextSwitch()
             ->addActionContext('list', 'xml')
             ->addActionContext('comments', array('xml', 'json'))
             ->initContext();
    }
}
?>

あるいは、単純に配列プロパティ $contexts を設定することもできます。

<?php
class FooController extends Zend_Controller_Action
{
    public $contexts = array(
        'list'     => array('xml'),
        'comments' => array('xml', 'json')
    );

    public function init()
    {
        $this->_helper->contextSwitch()->initContext();
    }
}
?>

このほうがオーバーヘッドが少なくなりますが、 書き間違える可能性もあります。

コンテキストの関連付けを行うメソッドには次のようなものがあります。

• addActionContext($action, $context): ひとつあるいは複数のコンテキストを、あるアクションで使用できるようにする。 関連付けがすでに設定されている場合は、それに追記します。 $context は、単一のコンテキストか コンテキストの配列となります。

  コンテキストとして true を指定すると、 すべてのコンテキストをそのアクションで使用できるようにします。

  $context に空の値を指定すると、 そのアクションではどのコンテキストも使用できないようにします。

• setActionContext($action, $context): ひとつあるいは複数のコンテキストを、あるアクションで使用できるようにする。 関連付けがすでに設定されている場合は、指定したものでそれを置き換えます。 $context は、単一のコンテキストか コンテキストの配列となります。

• addActionContexts(array $contexts): いくつかの アクション/コンテキスト のペアを一度に追加する。 $contexts は、アクション/コンテキスト のペアの連想配列です。これは addActionContext() へのプロキシとなります。つまり、既に別のペアが登録されている場合は そこに追記します。

• setActionContexts(array $contexts): addActionContexts() と同様だが、既存の アクション/コンテキスト のペアは上書きする。

• hasActionContext($action, $context): 特定のアクションにそのコンテキストが存在するかどうかを調べる。

• getActionContexts($action = null): 指定したアクションのすべてのコンテキスト、 あるいはすべての アクション/コンテキスト のペアを返す。

• removeActionContext($action, $context): ひとつあるいは複数のコンテキストを、指定したアクションから削除する。 $context は、単一のコンテキストか コンテキストの配列となります。

• clearActionContexts($action = null): すべてのコンテキストを、指定したアクションから削除する。 あるいはすべてのアクションのすべてのコンテキストを削除する。

コンテキストスイッチを初期化するには、アクションコントローラで initContext() をコールする必要があります。

<?php
class NewsController extends Zend_Controller_Action
{
    public function init()
    {
        $this->_helper->contextSwitch()->initContext();
    }
}
?>

時には、使用するコンテキストを決めてしまいたいこともあるでしょう。 たとえば、コンテキストスイッチが起動したときには XML コンテキストだけを使わせたいという場合などです。 その場合は、そのコンテキストを initContext() に渡します。

<?php
$contextSwitch->initContext('xml');
?>

さまざまなメソッドを使用することで、 ContextSwitch ヘルパーの挙動を変更することができます。 たとえば次のようなメソッドが存在します。

• setAutoJsonSerialization($flag): デフォルトでは、JSON コンテキストはビュー変数をすべてシリアライズし、 JSON 記法にしたものをレスポンスとして返します。 レスポンスを自分で作成したい場合はこれをオフにしなければなりません。 これは、initContext() をコールする前に行う必要があります。

  <?php
  $contextSwitch->setAutoJsonSerialization(false);
  $contextSwitch->initContext();
  ?>

  このフラグの値を取得するには getAutoJsonSerialization() を使用します。

• setSuffix($context, $suffix, $prependViewRendererSuffix): このメソッドは、指定したコンテキストに対して 別のサフィックスを設定します。 3 番目の引数を使用すると、 ViewRenderer のサフィックスの前に 新しいサフィックスをつけるのかどうかを指定することができます。 このフラグはデフォルトで有効になっています。

  サフィックスに空の値を指定すると、 ViewRenderer のサフィックスのみを使用します。

• addHeader($context, $header, $content): 指定したコンテキストにレスポンスヘッダを追加します。 $header はヘッダの名前で、 $content はそのヘッダに渡す値となります。

  各コンテキストは複数のヘッダを持つことができます。 addHeader() は、 そのヘッダをコンテキストのヘッダスタックに追加します。

  指定した $header がそのコンテキストに既に存在する場合は、 例外をスローします。

• setHeader($context, $header, $content): setHeader() は addHeader() とほぼ同じですが、 既存のコンテキストヘッダを上書きします。

• addHeaders($context, array $headers): 指定したコンテキストに一度に複数のヘッダを追加します。 addHeader() へのプロキシとして動作するので、 そのヘッダがすでに存在する場合は例外をスローします。 $headers は ヘッダ/コンテキスト のペアの配列です。

• setHeaders($context, array $headers.): addHeaders() と似ていますが、これは setHeader() へのプロキシとして動作し、 既存のヘッダは上書きします。

• getHeader($context, $header): 指定したコンテキストのヘッダの値を取得します。 見つからない場合は null を返します。

• removeHeader($context, $header): 指定したコンテキストの単一のヘッダを削除します。

• clearHeaders($context, $header): 指定したコンテキストのすべてのヘッダを削除します。

• setCallback($context, $trigger, $callback): 指定したコンテキストにおける指定したトリガーのコールバックを設定します。 トリガーに指定できる値は 'init' あるいは 'post' (それぞれ、コンテキストの初期化時と postDispatch 時を表します) です。 $callback は PHP のコールバックとして正しい形式でなければなりません。

• setCallbacks($context, array $callbacks): 指定したコンテキストに複数のコールバックを設定します。 $callbacks は トリガー/コールバック のペアとなります。実際のところ、登録できるコールバックは ほとんどふたつだけで、初期化用のものと後処理ようのものです。

• getCallback($context, $trigger): 指定したコンテキストにおける指定したトリガーのコールバックを取得します。

• getCallbacks($context): 指定したコンテキストにおけるすべてのコールバックを取得します。 トリガー/コールバック のペアを返します。

• removeCallback($context, $trigger): 指定したコンテキストにおける指定したトリガーのコールバックを削除します。

• clearCallbacks($context): 指定したコンテキストにおけるすべてのコールバックを削除します。

• setContextParam($name): コンテキストスイッチが要求されたかどうかを調べるための リクエストパラメータを設定します。デフォルトは 'format' ですが、このアクセサを使用することで変更することができます。

  getContextParam() で、現在の値を取得することができます。

• setAutoDisableLayout($flag): デフォルトでは、コンテキストスイッチが発生したときには レイアウト機能が無効になります。これは、 レイアウト機能は通常は普通のレスポンスの時に使用するものであって それ以外のコンテキストでは無意味だからです。 しかし、時にはレイアウト機能を使いたいこともあるでしょう (新しいコンテキスト用のレイアウトがある場合など)。 その場合は、setAutoDisableLayout() に true を渡します。これは、 initContext() をコールするより 前に 行わなければなりません。

  このフラグの現在の値を取得するには、アクセサ getAutoDisableLayout() を使用します。

• getCurrentContext() を使うと、 現在のコンテキストを取得することができます。 コンテキストスイッチが発生していない場合や initContext() の起動前にコールした場合は null を返します。

AjaxContext ヘルパーは ContextSwitch を継承したものです。 ContextSwitch の機能はすべて使用することができます。 しかし、いくつか重要な違いがあります。

まず、コンテキストを決めるアクションコントローラのプロパティは $ajaxable となります。これにより、 AJAX 用と通常の HTTP リクエスト用で別のコンテキストを使用できるようになります。 AjaxContext の *ActionContext*() 系のメソッドは、このプロパティに書き込みます。

次に、これは XmlHttpRequest が発生した場合にのみ起動します。 リクエストオブジェクトの isXmlHttpRequest() メソッドで判断します。したがって、たとえコンテキストパラメータ ('format') をリクエストで渡したとしても、そのリクエストが XmlHttpRequest でない場合はコンテキストスイッチが発生しません。

3 番目に、AjaxContext は HTML コンテキストを追加します。 このコンテキストでは、サフィックスを 'ajax.phtml' として通常のリクエストのコンテキストと区別しています。 追加のヘッダは返しません。

<?php
class CommentController extends Zend_Controller_Action
{
    public function init()
    {
        $ajaxContext = $this->_helper->getHelper('AjaxContext');
        $ajaxContext->addActionContext('view', 'html')
                    ->addActionContext('form', 'html')
                    ->addActionContext('process', 'json')
                    ->initContext();
    }

    public function viewAction()
    {
        // 単一のコメントを表示します
        // AjaxContext の場合は comment/view.ajax.phtml 
        // を使用します
    }

    public function formAction()
    {
        // 新規コメントの追加フォームをレンダリングします
        // AjaxContext の場合は comment/form.ajax.phtml 
        // を使用します
    }

    public function processAction()
    {
        // 新規コメントを処理します
        // 結果を JSON で返します。結果をビュー変数に格納するだけで、
        // JSON でそれを返してくれます
    }
}
?>

FlashMessenger ヘルパーは、 次のリクエストの際にユーザに見せる必要のあるメッセージを渡すためのものです。 この機能を実現するため、FlashMessenger は Zend_Session_Namespace を使用してメッセージを保管しています。 Zend_Session や Zend_Session_Namespace を使用する際には、起動ファイル中で Zend_Session::start() を実行するようにしましょう (詳細な使用例は Zend Session のドキュメントを参照ください)。

以下の使用例は、もっとも基本的なフラッシュメッセンジャーの使用法を示すものです。 アクション /some/my がコールされると、フラッシュメッセージに "Record Saved!" が保存されます。そして、その次のアクション /some/my-next-request へのリクエストの際にそれを取得 (そして削除) します。

<?php
class SomeController extends Zend_Controller_Action
{
    /**
     * FlashMessenger
     *
     * @var Zend_Controller_Action_Helper_FlashMessenger
     */
    protected $_flashMessenger = null;

    public function init()
    {
        $this->_flashMessenger = $this->_helper->getHelper('FlashMessenger');
        $this->initView();
    }

    public function myAction()
    {
        /**
         * Zend_Controller_Action_Helper_FlashMessenger
         * のインスタンスを必要に応じて取得するためのデフォルトメソッド
         */
        $this->_flashMessenger->addMessage('Record Saved!');
    }

    public function myNextRequestAction()
    {
        $this->view->messages = $this->_flashMessenger->getMessages();
        $this->render();
    }
}
        

Redirector ヘルパーは、 アプリケーション内で必要となるリダイレクト処理用のオブジェクトとして使用します。 _redirect() メソッドと比べた場合の利点としては、 サイト全体で使用する設定を事前に組み込んでおけることがあります。また、 Zend_Controller_Action::_forward() の場合と同様に、組み込みのインターフェイス goto($action, $controller, $module, $params) が使用できることも利点となります。

Redirector では、 リダイレクトの設定を行うメソッドとして次のようなものが用意されています。

• setCode() を使用して、 リダイレクトの際に使用する HTTP レスポンスコードを設定します。

• setExit() を使用して、 リダイレクトの後で強制的に exit() を実行させるようにします。 デフォルトは true です。

• setGoto() を使用して、goto() に何も渡されなかったときのデフォルトの URL を設定します。 Zend_Controller_Action::_forward() の API である setgoto($action, $controller = null, $module = null, array $params = array()); を使用します。

• setGotoRoute() を使用して、 登録済みのルートにもとづいた URL を設定します。 キー/値 のペアの配列とルート名を渡し、 それをもとにルートの型と定義から URL を作成します。

• setGotoUrl() を使用して、gotoUrl() に何も渡されなかったときのデフォルトの URL を設定します。 URL を表す文字列を受け取ります。

• setPrependBase() を使用して、 setGotoUrl()、gotoUrl() あるいは gotoUrlAndExit() で指定した URL の前にリクエストのベース URL を追加します。

• setUseAbsoluteUri() を使用すると、 Redirector がリダイレクトの際に絶対 URL を使用するようになります。 このオプションを設定すると、 $_SERVER['HTTP_HOST'] や $_SERVER['SERVER_PORT']、そして $_SERVER['HTTPS'] の内容をもとにして リダイレクト用の完全な URL を作成します。 このオプションのデフォルト値はオフですが、 将来のリリースではデフォルトで有効になるかもしれません。

さらに、実際のリダイレクトを行うためのメソッドとして以下のものが用意されています。

• goto() は、setGoto() (_forward() 風の API) を用いて作成した URL にリダイレクトします。

• gotoRoute() は、setGotoRoute() (ルートの作成) を用いて作成した URL にリダイレクトします。

• gotoUrl() は setGotoUrl() (URL 文字列の指定) を用いて作成した URL にリダイレクトします。

リダイレクト先の URL を知るには getRedirectUrl() を使用します。 これはいつでも使用できます。

ViewRenderer ヘルパーは、 以下のような要件を満たすために作られたものです。

• コントローラ内でいちいちビューオブジェクトのインスタンスを 作成しなくても済むようにする。 ビューオブジェクトは自動的にコントローラに登録されます。

• ビュースクリプトやヘルパー、そしてフィルタのパスを 現在のモジュールに基づいて自動的に設定し、 モジュール名をヘルパーやフィルタのクラス名の先頭に自動的に関連付ける。

• すべてのコントローラとアクションで使用できる グローバルなビューオブジェクトを作成する。

• すべてのコントローラで使用する、 デフォルトのビューレンダリングオプションを設定できるようにする。

• 何も指定しなくても、 自動的にビュースクリプトをレンダリングできる機能を追加する。

• ビューの基底パスやビュースクリプトのパスを 独自に指定できるようにする。

注意: _forward() やリダイレクト、あるいは手動でのレンダリングを行う場合は、 自動レンダリングは不要です。これらの処理を行う場合は、 出力を自前で行うことを ViewRenderer に対して指示します。

注意: ViewRenderer はデフォルトで有効になっています。 これを無効にするには、フロントコントローラのパラメータ noViewRenderer を指定する ($front->setParam('noViewRenderer', true)) か、 あるいはヘルパーブローカからヘルパーを削除 (Zend_Controller_Action_HelperBroker::removeHelper('viewRenderer')) します。
フロントコントローラでのディスパッチ処理の前に ViewRenderer の設定を変更したい場合は、 次のいずれかの方法を使用します。

• 独自の ViewRenderer のインスタンスを作成し、 ヘルパーブローカにそれを渡して登録する。

  <?php
  $viewRenderer = new Zend_Controller_Action_Helper_ViewRenderer();
  $viewRenderer->setView($view)
               ->setViewSuffix('php');
  Zend_Controller_Action_HelperBroker::addHelper($viewRenderer);
                      

• ViewRenderer オブジェクトを、 ヘルパーブローカから必要に応じて作成、取得する。

  <?php
  $viewRenderer = Zend_Controller_Action_HelperBroker::getStaticHelper('viewRenderer');
  $viewRenderer->setView($view)
               ->setViewSuffix('php');
                      

もっとも基本的な使用法は、単に ViewRenderer のインスタンスを作成してそれをヘルパーブローカに渡すというものです。 インスタンスの作成と登録を一度に行うには、ヘルパーブローカの getStaticHelper() メソッドを使用するのがいちばん簡単です。

<?php
Zend_Controller_Action_HelperBroker::getStaticHelper('viewRenderer');
        

アクションコントローラのインスタンスが最初に作成されたときに、 ViewRenderer がビューオブジェクトのインスタンスを作成します。 コントローラのインスタンスが作成されるたびに、ViewRenderer の init() がコールされます。 ここでアクションコントローラのビュープロパティを設定し、 現在のモジュールからの相対パスを指定して addScriptPath() をコールします。 これは現在のモジュール名に基づいたプレフィックスをクラス名の先頭につけてコールされるので、 ヘルパーやフィルタのクラスをモジュール内で効率的に管理することができます。

postDispatch() がコールされるたびに、現在のアクションの render() を自動的にコールします。

例として、次のようなクラスを考えてみましょう。

<?php
// foo モジュールのコントローラクラス
class Foo_BarController extends Zend_Controller_Action
{
    // デフォルトで bar/index.phtml をレンダリングするので、特に何もする必要はありません
    public function indexAction()
    {
    }

    // 変数 'foo' の値を 'bar' に設定して bar/populate.phtml をレンダリングします
    // ビューオブジェクトは既に preDispatch() で定義されているので、既に使用可能です
    public function populateAction()
    {
        $this->view->foo = 'bar';
    }
}

...

// ビュースクリプトの中では、たとえば次のように書きます
<?php $this->foo(); // Foo_View_Helper_Foo::foo() をコールします
        

ViewRenderer には、 ビューのオプションを取得したり設定したりするためのメソッドも豊富に用意されています。

• setView($view) は ViewRenderer が使用するビューオブジェクトを設定します。 これは、クラスのプロパティ $view の値を設定します。

• setNeverRender($flag = true) を使用すると、自動レンダリング機能を全体的に （すべてのコントローラに対して）無効にしたり有効にしたりできます。 true を指定すると、そのコントローラの postDispatch() では render() をコールしなくなります。 getNeverRender() は、現在の設定を取得します。

• setNoRender($flag = true) を使用すると、自動レンダリングを無効にしたり有効にしたりできます。 true を指定すると、現在のコントローラの postDispatch() では render() をコールしなくなります。 この設定は、preDispatch() がコールされるたびにいったんリセットされます (つまり、自動レンダリングを無効にしたいすべてのコントローラで 個々にこれを設定する必要があるということです)。 getNoRender() は、現在の設定を取得します。

• setNoController($flag = true) を使用すると、render() がコントローラ名のサブディレクトリにあるアクションスクリプトを 読みにいかなくすることができます (デフォルトでは読みにいきます)。 getNoController() は、現在の設定を取得します。

• setNeverController($flag = true) は setNoController() と似ていますが、 こちらは全体に影響を与えます。つまり、 ディスパッチ処理を行っても設定はリセットされません。 getNeverController() は、現在の設定を取得します。

• setScriptAction($name) を使用すると、レンダリングするアクションスクリプトを指定することができます。 $name は、スクリプト名から拡張子を除いたもの (そして、noController が指定されていない限り、 コントローラのディレクトリ名も除いたもの) となります。 指定しなかった場合は、リクエストオブジェクト内のアクションに基づいた名前の ビュースクリプトを探します。 getScriptAction() は、現在の設定を取得します。

• setResponseSegment($name) を使用すると、レンダリング結果を出力する レスポンスオブジェクトのセグメント名を指定することができます。 指定しなかった場合は、デフォルトのセグメントにレンダリングします。 getResponseSegment() は、現在の設定を取得します。

• initView($path, $prefix, $options) は、ビューの基底パスを指定します。 また、ヘルパースクリプトとフィルタスクリプトの先頭につけるクラスプレフィックスや ViewRenderer のオプションも設定します。 オプションには、 neverRender、noRender、 noController、scriptAction および responseSegment のいずれかのフラグを指定します。

• setRender($action = null, $name = null, $noController = false) を使用すると、scriptAction や responseSegment そして noController のいずれかまたは複数を 一度に指定することができます。direct() はこのメソッドのエイリアスで、コントローラ内から簡単にコールすることができます。

  // 現在のアクションスクリプトではなく 'foo' をレンダリングします
  $this->_helper->viewRenderer('foo');
  
  // form.phtml の内容をレスポンスセグメント 'html' にレンダリングします。
  // コントローラのビュースクリプト用サブディレクトリは使用しません。
  $this->_helper->viewRenderer('form', 'html', true);
  
                  

  注意: setRender() および direct() は、実際にはビュースクリプトをレンダリングしません。 実際にレンダリングを行うのは postDispatch() や render() で、それらのメソッドに対するヒントを指示するだけです。
  

コンストラクタのオプションとして、 ビューオブジェクトを渡したり ViewRenderer のオプションを渡したりすることができます。 このオプションで指定できるのは、initView() で説明したフラグと同じものです。

$view    = new Zend_View(array('encoding' => 'UTF-8'));
$options = array('noController' => true, 'neverRender' => true);
$viewRenderer = new Zend_Controller_Action_Helper_ViewRenderer($view, $options);

        

さらに追加のメソッドがあり、 ビューオブジェクトで使用するビューの基底パスを変更することができます。 また、ビュースクリプトが自動レンダリングを行う際に使用するパスも変更することができます。 これらのメソッドでは、以下のプレースホルダのいずれかあるいは複数が使用できます。

• :moduleDir は、現在のモジュールの基底ディレクトリを指します (規約では、これはモジュールのコントローラディレクトリの親ディレクトリとなります)。

• :module は、現在のモジュール名を指します。

• :controller は、現在のコントローラ名を指します。

• :action は、現在のアクション名を指します。

• :suffix は、ビュースクリプトのサフィックス (setViewSuffix() で設定したもの) を指します。

パス指定を制御するメソッドは次のとおりです。

• setViewBasePathSpec($spec) は、ビューオブジェクトを追加する際に使用する基底パスを 決める際に使用するパス指定を変更します。 デフォルトの設定は :moduleDir/views です。 現在の設定を取得するには getViewBasePathSpec() を使用します。

• setViewScriptPathSpec($spec) は、個々のビュースクリプトのパス (からビュースクリプトの基底パスを除いた部分) を決める際に使用するパス指定を変更します。 デフォルトの設定は :controller/:action.:suffix です。 現在の設定を取得するには getViewScriptPathSpec() を使用します。

• setViewScriptPathNoControllerSpec($spec) は、noController が有効な場合に 個々のビュースクリプトのパス (からビュースクリプトの基底パスを除いた部分) を決める際に使用するパス指定を変更します。 デフォルトの設定は :action.:suffix です。 現在の設定を取得するには getViewScriptPathNoControllerSpec() を使用します。

パス指定をよりきめ細かく行うには、 Zend_Filter_Inflector を使用します。実は、ViewRenderer はパスのマッピングを行う際に既にインフレクタを使用しています。 インフレクタに手を入れたい (独自のインフレクタを使用したり、 デフォルトのインフレクタに手を加えたりしたい) 場合は、 以下のメソッドを使用します。

• getInflector() は、インフレクタを取得します。 まだ ViewRenderer にインフレクタが存在しない場合は、 デフォルトの規則にもとづいたインフレクタを作成します。

  By default, it uses static rule references for the suffix and module directory, as well as a static target; this allows various ViewRenderer properties the ability to dynamically modify the inflector.

• setInflector($inflector, $reference) は、 ViewRenderer で使用する独自のインフレクタを設定します。 $reference が true の場合は、 対象だけでなくサフィックスやモジュールディレクトリも ViewRenderer のプロパティへの静的な参照とします。

注意: デフォルトの検索方式
ViewRenderer は、 パスの正規化を行ってビュースクリプトによる検索を簡単にします。 デフォルトのルールは次のようなものです。

• :module: MixedCase および camelCase 形式の単語がダッシュで分割され、 すべて小文字になります。たとえば "FooBarBaz" は "foo-bar-baz" となります。

  内部的には、インフレクタはフィルタ Zend_Filter_Word_CamelCaseToDash および Zend_Filter_StringToLower を使用します。

• :controller: MixedCase および camelCase 形式の単語がダッシュで分割され、 アンダースコアはディレクトリ区切り文字に変換され、 すべて小文字になります。たとえば "FooBar" は "foo-bar" となり、そして "FooBar_Admin" は "foo-bar/admin" となります。

  内部的には、インフレクタはフィルタ Zend_Filter_Word_CamelCaseToDash、 Zend_Filter_Word_UnderscoreToSeparator および Zend_Filter_StringToLower を使用します。

• :action: MixedCase および camelCase 形式の単語がダッシュで分割され、 英数字以外の文字はダッシュに変換され、 すべて小文字になります。たとえば "fooBar" は "foo-bar" となり、"foo-barBaz" は "foo-bar-baz" となります。

  内部的には、インフレクタはフィルタ Zend_Filter_Word_CamelCaseToDash、 Zend_Filter_PregReplace および Zend_Filter_StringToLower を使用します。

ViewRenderer API の最後に紹介するのは、 実際にビュースクリプトのパスを決定するメソッドと ビューのレンダリングを行うメソッドです。以下をご覧ください。

• renderScript($script, $name) は、指定したパスのスクリプトをレンダリングします。 オプションで、パスセグメントの名前を指定することもできます。 このメソッドを使用する際には、ViewRenderer はスクリプト名を自動的に決定することはありません。 そのかわりに、$script で指定された内容を直接 ビューオブジェクトの render() メソッドに渡します。

  注意: レスポンスオブジェクトにビューがレンダリングされると、 自動的に noRender を設定します。 これにより、同じビュースクリプトを間違って複数回レンダリングしてしまうことを防ぎます。
  

  注意: デフォルトでは、 Zend_Controller_Action::renderScript() は ViewRenderer の renderScript() メソッドへのプロキシとなります。
  

• getViewScript($action, $vars) は、渡されたアクションや $vars で指定した変数の値に基づいてビュースクリプトのパスを作成します。 $vars 配列のキーは、パスを指定するためのキー ('moduleDir'、'module'、'controller'、'action' および 'suffix') のいずれかとなります。渡された変数の値をもとにしてパスを作成します。 なにも渡されなかった場合は、現在のリクエストの内容をもとにしてパスを作成します。

  getViewScript() は、noController フラグの内容によって viewScriptPathSpec あるいは viewScriptPathNoControllerSpec のいずれかを使用します。

  モジュール名やコントローラ名、アクション名にあらわれる 単語の区切りは、ダッシュ ('-') に置き換えられます。 したがって、たとえばコントローラ名が 'foo.bar' でアクション名が 'baz:bat' だったとすると、 デフォルトのパス指定をもとにしたビュースクリプトのパスは 'foo-bar/baz-bat.phtml' となります。

  注意: デフォルトでは、 Zend_Controller_Action::getViewScript() は ViewRenderer の getViewScript() メソッドへのプロキシとなります。
  

• render($action, $name, $noController) は、まず $name あるいは $noController が指定されているかどうかを調べます。 指定されている場合は、ViewRenderer の対応するフラグ (それぞれ responseSegment と noController) を設定します。 次に、$action 引数が指定されていれば、 それを getViewScript() に渡します。 最後に、取得したビュースクリプトのパスを renderScript() に渡します。

  注意: render() を使用する際には、その副作用に注意しましょう。 レスポンスセグメント名や noController フラグに指定した内容は、そのオブジェクト内で残り続けます。 さらに、レンダリングが完了した際に noRender も設定されます。
  

  注意: デフォルトでは、 Zend_Controller_Action::render() は ViewRenderer の render() メソッドへのプロキシとなります。
  

• renderBySpec($action, $vars, $name) は、パス指定用の変数を渡してビュースクリプトのパスを決定します。 $action および $vars の内容を getScriptPath() に、そしてその結果得られたスクリプトのパスと $name を renderScript() に渡します。

<?php
// 起動ファイル内で
Zend_Controller_Action_HelperBroker::getStaticHelper('viewRenderer');

...

<?php
// 'foo' モジュールの 'bar' コントローラ
class Foo_BarController extends Zend_Controller_Action
{
    // デフォルトで bar/index.phtml をレンダリングするので、特に何もする必要はありません
    public function indexAction()
    {
    }

    // 変数 'foo' の値を 'bar' に設定して bar/populate.phtml をレンダリングします
    // ビューオブジェクトは既に preDispatch() で定義されているので、既に使用可能です
    public function populateAction()
    {
        $this->view->foo = 'bar';
    }

    // 何もレンダリングせずに別のアクションに転送します
    // 転送先のアクションで何らかのレンダリングを行います
    public function bazAction()
    {
        $this->_forward('index');
    }

    // 何もレンダリングせず別の場所にリダイレクトします
    public function batAction()
    {
        $this->_redirect('/index');
    }
}
            

注意: 命名規約: コントローラ名やアクション名の単語の区切り
コントローラやアクションの名前が複数の単語からなるものである場合、 ディスパッチャには、特定のパスや区切り文字を使用して単語を区切った URL を指定しなければなりません。 ViewRenderer は、コントローラ名の中にあるパス区切り文字を 実際のパス区切り文字 ('/') に置き換え、単語区切り文字をダッシュ ('-') に置き換えてパスを作成します。したがって、 アクション /foo.bar/baz.bat をコールすると FooBarController.php の FooBarController::bazBatAction() へディスパッチされ、 foo-bar/baz-bat.phtml をレンダリングすることになります。 また、アクション /bar_baz/baz-bat をコールすると Bar/BazController.php (パス区切り文字に注意) の Bar_BazController::bazBatAction() へディスパッチされ、bar/baz/baz-bat.phtml をレンダリングすることになります。
二番目の例では、モジュールはデフォルトモジュールのままであることに注意しましょう。 しかし、パス区切り文字があるために、 Bar/BazController.php にある Bar_BazController を受け取ることになります。 ビューレンダラはコントローラのディレクトリ階層を模倣します。

<?php
// Bar モジュールの Baz コントローラクラス
class Bar_BazController extends Zend_Controller_Action
{
    public function fooAction()
    {
        // このアクションでは自動レンダリングを行いません
        $this->_helper->viewRenderer->setNoRender();
    }
}

// Bar モジュールの Bat コントローラクラス
class Bar_BatController extends Zend_Controller_Action
{
    public function preDispatch()
    {
        // このコントローラのアクションでは決して自動レンダリングを行いません
        $this->_helper->viewRenderer->setNoRender();
    }
}
            

注意: たいていの場合は、自動レンダリングを全体で無効にする (setNeverRender()) のは無意味です。 なぜなら、ViewRenderer の唯一の存在意義が、 ビューオブジェクトを自動的に設定することだからです。

<?php
// Foo モジュールの Bar コントローラクラス
class Foo_BarController extends Zend_Controller_Action
{
    public function addAction()
    {
        // 'bar/add.phtml' ではなく 'bar/form.phtml' をレンダリングします
        $this->_helper->viewRenderer('form');
    }

    public function editAction()
    {
        // 'bar/edit.phtml' ではなく 'bar/form.phtml' をレンダリングします
        $this->_helper->viewRenderer->setScriptAction('form');
    }

    public function processAction()
    {
        // 何かのチェックをした後で...
        if (!$valid) {
            // 'bar/process.phtml' ではなく 'bar/form.phtml' をレンダリングします
            $this->_helper->viewRenderer->setRender('form');
            return;
        }

        // その他の処理を続けます...
    }

}
            

<?php
// Foo モジュールの Bar コントローラクラス
class Foo_BarController extends Zend_Controller_Action
{
    public function preDispatch()
    {
        // ビューのエンコーディングを変更します
        $this->view->setEncoding('UTF-8');
    }

    public function bazAction()
    {
        // ビューオブジェクトを取得し、エスケープ用のコールバックを 'htmlspecialchars' に設定します
        $view = $this->_helper->viewRenderer->view;
        $view->setEscape('htmlspecialchars');
    }
}