アクションヘルパー
導入
アクションヘルパーを使用すると、Zend_Controller_Action
を継承した任意のアクションコントローラに対して
実行時やその他必要に応じて機能を追加できます。
アクションヘルパーの狙いは、
アクションコントローラに共通機能を追加するために
いちいち抽象クラスを継承する手間を省くことにあります。
アクションヘルパーにはさまざまな使用法があります。
たとえば、Zend_View_Helper
や Zend_Controller_Plugin
と同じように、処理の仲買をするために用いることもできます。
アクションヘルパーは (Zend_View_Helper と同様に)、
必要になった時点で読み込むこともできますし、
リクエスト時 (起動時) やアクションコントローラの作成時 ( init())
で読み込むこともできます。詳細は、以下の使用例を参照ください。
ヘルパーの初期化
ヘルパーを初期化するにはいくつかの方法があります。
必要に応じて、またそのヘルパーの機能に応じて使い分けましょう。
ヘルパーブローカは、Zend_Controller_Action
の $_helper に格納されます。
このブローカを使用して、ヘルパーを取得したりコールしたりします。
以下のような方法があります。
-
明示的に getHelper() を使用します。
ヘルパーの名前を指定すると、
そのヘルパーオブジェクトが返されます。
span style="color: #ff0000;">'FlashMessenger''先ほどのリクエストで、あることをしました');
-
ヘルパーブローカの __get() 機能を使用すると、
まるでブローカのプロパティであるかのようにヘルパーを操作できます。
span style="color: #ff0000;">'先ほどのリクエストで、あることをしました');
-
たいていのアクションヘルパーは
direct() メソッドを実装しており、
これはそのヘルパーのデフォルトメソッドをコールします。
FlashMessenger の例では、
addMessage() をコールします。
span style="color: #ff0000;">'先ほどのリクエストで、あることをしました');
Note:
これらの例は、すべて同じことを行っています。
ヘルパーのインスタンスを明示的に作成したいと考えるかもしれません。
たとえばアクションコントローラ以外からヘルパーを使用したいだとか、
すべてのアクションのヘルパーブローカに同じヘルパーを渡したいだとかいった場合です。
インスタンスを作成する方法は、通常の PHP のクラスと同じです。
ヘルパーブローカ
Zend_Controller_Action_HelperBroker
がヘルパーオブジェクトやそのパスの登録に関する詳細を処理します。
また、必要に応じてそこからヘルパーを取得できます。
ヘルパーをブローカに登録するには
addHelper() を使用します。
もちろん、ヘルパーのインスタンスを作成してそれをブローカに渡すという作業は
時間とリソースを消費します。これらの作業の手間をほんの少し省くためのメソッドとして、
addPrefix() と
addPath() が用意されています。
-
addPrefix() はクラスのプレフィックスを受け取り、
それをもとにヘルパークラスのパスを決定します。
プレフィックスが、Zend Framework のクラス命名規約に沿っているものとみなして、
パスを決定します。
// My/Action/Helpers/ にある、名前が My_Action_Helpers で始まるヘルパーを追加します
'My_Action_Helpers');
-
addPath() は、最初の引数にディレクトリ、
そして二番目の引数にクラスのプレフィックス
(デフォルトは 'Zend_Controller_Action_Helper') を指定します。
これは、指定したディレクトリにある指定したプレフィックスのクラスを追加します。
// Plugins/Helpers/ にある、名前が Helper で始まるヘルパーを追加します
'./Plugins/Helpers',
'Helper');
これらは静的メソッドなので、コントローラチェイン内の任意の場所で使用できます。
これにより、必要に応じて動的にヘルパーを追加できることになります。
内部的には、ヘルパーブローカは PluginLoader
のインスタンス を用いてパスを保持します。静的メソッド
getPluginLoader() で PluginLoader
を取得することもできますし、また独自の PluginLoader
インスタンスを setPluginLoader() で設定することもできます。
ヘルパークラスがヘルパーブローカ内に存在するかどうかを調べるには
hasHelper($name) を使用します。$name
には、ヘルパーのショートネーム (プレフィックスを除いたもの)
を指定します。
// 'redirector' ヘルパーがブローカに登録されているかどうかを調べます
'redirector''Redirector helper registered';
}
ヘルパーブローかからヘルパーを取得する静的メソッドには、さらに
getExistingHelper() と
getStaticHelper() のふたつがあります。
getExistingHelper() は、すでに起動されているか、
あるいは明示的にヘルパーブローカに登録されているヘルパーのみを取得します。
存在しない場合は例外をスローします。
getStaticHelper() は
getExistingHelper() と同じですが、
ヘルパースタックに登録されていないヘルパーについてはそのインスタンスを作成しようとします。
自分で設定をしたいヘルパーを取得するには
getStaticHelper() がおすすめです。
どちらのメソッドも、引数はひとつだけです。
この引数 $name
には、ヘルパーのショートネーム (プレフィックスを除いたもの)
を指定します。
// 'redirector' ヘルパーがブローカに登録されているかどうかを調べ、取得します
'redirector''redirector');
}
// あるいは、登録されているかどうかを気にせずに単純に取得します
'redirector');
}
最後に、登録済みのヘルパーをブローカから削除するには
removeHelper($name) を使用します。$name
には、ヘルパーのショートネーム (プレフィックスを除いたもの)
を指定します。
// 'redirector' ヘルパーがブローカに登録されている場合にはそれを削除します
'redirector''redirector')
}
組み込みのアクションヘルパー
Zend Framework には、いくつかのアクションヘルパーがデフォルトで組み込まれています。
AJAX のオートコンプリート機能用のレスポンスを作成する AutoComplete、
アクションに応じてレスポンスの形式を変更する ContextSwitch と
AjaxContext、セッション単位のフラッシュメッセージを扱う
FlashMessenger、JSON 形式へのエンコードとレスポンスの送信を行う
Json、
アプリケーション内から内部あるいは外部へのリダイレクトを実装できるようにする
Redirector、そして
コントローラ内でのビューオブジェクトの設定とビューのレンダリングを自動化する
ViewRenderer です。
ActionStack(日本語)
ActionStack ヘルパーは、リクエストをフロントコントローラの
ActionStack
プラグインに格納します。これにより、
リクエストの実行時にアクションのキューを作成しやすくなります。
このヘルパーは、アクションを追加する際に
新しいリクエストオブジェクトを指定するか
アクション - コントローラ - モジュール の設定を指定するかのいずれかを用います。
Note: ActionStack ヘルパーを起動すると ActionStack プラグインが初期化される
ActionStack を起動すると、暗黙のうちに
ActionStack プラグインを登録します。
つまり、この機能を使う際に明示的に ActionStack
プラグインを登録する必要はないということです。
Example #1 アクション、コントローラおよびモジュール名によるタスクの追加
単純にアクションとコントローラそしてモジュール
(およびオプションでリクエストパラメータ)
を指定して Zend_Controller_Action::_forward()
をコールするのが一番シンプルな方法です。
span style="color: #808080; font-style: italic;">// 2 つのアクションをスタックに格納して
// /foo/baz/bar/baz をコールします
// (FooController::bazAction() にリクエスト変数 bar == baz を指定したもの)
'baz',
'foo',
'default''bar' => 'baz'));
// /bar/bat のコール
// (BarController::batAction()) を追加します
'bat', 'bar');
}
}
Example #2 リクエストオブジェクトによるタスクの追加
時にはリクエストオブジェクトのオブジェクト指向的な部分が使いたいこともあるでしょう。
そんな場合はこのオブジェクトを ActionStack
ヘルパーに渡すこともできます。
span style="color: #808080; font-style: italic;">// 2 つのアクションをスタックに格納して
// /foo/baz/bar/baz をコールします
// (FooController::bazAction() にリクエスト変数 bar == baz を指定したもの)
$request = clone $this->getRequest();
// コントローラやモジュールは指定せず、現在の値を使用します
$request->setActionName('baz''bar' => 'baz'// /bar/bat のコール
// (BarController::batAction()) を追加します
$request = clone $this->getRequest();
// モジュールは指定せず、現在の値を使用します
$request->setActionName('bat')
->setControllerName('bar'
AutoComplete
多くの AJAX 用 javascript ライブラリでは、
オートコンプリート機能を提供しています。
これは、ユーザがタイプした内容にマッチする可能性のある候補の一覧を表示するものです。
AutoComplete ヘルパーは、
このような場合に使用できるレスポンスを返すためのものです。
オートコンプリート機能の実装方法は JS ライブラリによって異なるので、
AutoComplete では多くのライブラリで使用する共通機能を抽象化しています。
そして、個々のライブラリにあわせた実装を用意しています。
返り値の型は、JSON 形式の文字列の配列か
JSON 形式の配列の配列
(内部の配列は、選択リストを作成する際に使用するメタデータの連想配列)
あるいは HTML となります。
どの実装についての基本的な使用法は同じです。
span style="color: #808080; font-style: italic;">// 何かの処理をします...
// エンコードしたレスポンスを送信します
// あるいは明示的に
// あるいは単純にオートコンプリート用のレスポンスを準備します
デフォルトでは以下のような作業を行います。
このヘルパーでは次のようなメソッドが使用できます。
disableLayouts() は、レイアウト機能と
ViewRenderer を無効にします。一般に、これは
prepareAutoCompletion() の中でコールされます。
encodeJson($data, $keepLayouts = false)
はデータを JSON 形式にエンコードし、オプションでレイアウト機能の有効/無効
を切り替えます。一般に、これは
prepareAutoCompletion() の中でコールされます。
prepareAutoCompletion($data, $keepLayouts = false)
は、各種具象実装にあわせてレスポンスデータをフォーマットし、
オプションでレイアウト機能の有効/無効を切り替えます。
返り値は実装によって異なります。
sendAutoCompletion($data, $keepLayouts = false)
は、各種具象実装にあわせてフォーマットしたレスポンスデータを送信します。
これは、 prepareAutoCompletion() をコールしたあとでレスポンスを送信します。
direct($data, $sendNow = true, $keepLayouts =
false) は、このヘルパーをヘルパーブローカのメソッドとしてコールする場合に使用します。
$sendNow フラグは、
sendAutoCompletion() と
prepareAutoCompletion() のどちらをコールするかを指定するものです。
現在 AutoComplete がサポートしている AJAX
ライブラリは、Dojo と Scriptaculous です。
Dojo でのオートコンプリート
Dojo には、オートコンプリートのためだけのウィジェットはありません。
しかし、ComboBox と FilteringSelect
のふたつのウィジェットがオートコンプリート機能を持っています。
どちらのウィジェットも、QueryReadStore
を実装したデータを必要とします。詳細は
» dojo.data
のドキュメントを参照ください。
Zend Framework では、単純な数値添字の配列を
AutoCompleteDojo ヘルパーに渡します。
そうすると、適切な形式の JSON オブジェクトを返します。
Example #3 Zend MVC を使用した、Dojo でのオートコンプリート
Zend MVC で Dojo によるオートコンプリートを使用するには、
いくつかの準備が必要です。オートコンプリートを使用したい
ComboBox 用にフォームオブj稀有とを作成し、
オートコンプリートの結果を提供するためのコントローラアクションを作成し、
オートコンプリートアクションに接続するための
独自の QueryReadStore を作成し、
サーバ側でオートコンプリートを行わせるための javascript
を作成することになります。
まずは、必要となる javascript を見ていきましょう。
Dojo は javascript によるオブジェクト指向プログラミングを行うための
完全なフレームワークで、ちょうど PHP における Zend Framework
のようなものです。その中には、
ディレクトリ構造を用いて擬似的な名前空間を作成する機能もあります。
ここでは、Dojo の配布ファイルの Dojo
ディレクトリと同じ階層に 'custom' ディレクトリを作成します。
そのディレクトリの中に TestNameReadStore.js
という javascript ファイルを作成し、次のようなコードを書きます。
span style="color: #3366CC;">"custom.TestNameReadStore""custom.TestNameReadStore""fetch", arguments);
}
});
このクラスは、単に Dojo 自身の QueryReadStore
クラスを継承したものです。継承元のクラス自体は抽象クラスです。
そこにリクエスト用のメソッドを定義し、'test'
要素に割り当てています。
次に、オートコンプリートを行うためのフォーム要素を作成します。
span style="color: #ff0000;">'get''/test/process''test''type' => 'text', 'options''filters''StringTrim'),
'dojoType''dijit.form.ComboBox'),
'store' => 'testStore',
'autoComplete' => 'false',
'hasDownArrow' => 'true',
'label' => 'Your input:',
)),
'go''type' => 'submit',
'options''label' => 'Go!'
ここでは、単に 'test' と 'go' メソッドのみを持つフォームを作成します。
'test' メソッドは、特別な Dojo 固有の属性
dojoType、store、autoComplete および hasDownArrow
を追加します。dojoType では、これから ComboBox
を作成することを指定します。そして、それを 'testStore' のデータストア
(キー 'store') にリンクします。詳細は後ほど説明します。
'autoComplete' を FALSE に設定することで、
最初にマッチしたものを自動選択するのではなく
マッチしたものの一覧を表示するよう Dojo に指示します。
最後に 'hasDownArrow' でセレクトボックス風の下向き矢印を作ります。
これで、マッチしたものを表示したり隠したりできるようになります。
では、フォームを表示するためのメソッドと
オートコンプリートの処理用のエンドポイントを作成してみましょう。
span style="color: #808080; font-style: italic;">// ...
/**
* 最初のページ
*/'ajax''format''index''index''test', ''
autocompleteAction()
ではいくつかの作業を行っています。
まず、POST リクエストを受け取ったことを確実にし、
'format' パラメータの値を 'ajax' に設定します。
これにより、余計なクエリがアクションに送られることを減らします。
次に、'test' パラメータの内容を確認し、私たちのデータと比較します
(ここでは、 getData() の実装は意図的に控えています。
何らかのデータソースを使用することになるでしょう)。
最後に、マッチした内容を AutoCompletion ヘルパーに送信します。
これでバックエンド側の準備はすべて整いました。
次に、ページのビュースクリプト側ではどうすればいいのかを考えてみましょう。
まず、データストアを用意しなければなりません。
次にフォームをレンダリングし、最後に適切な Dojo ライブラリ
(使用するデータストアも含む) を読み込みます。
ビュースクリプトを見てみましょう。
適宜コメントを入れてあります。
span style="color: #808080; font-style: italic;">// データストアの準備 ?>
"custom.TestNameReadStore" jsId="testStore"
url="<?php echo $this->baseUrl() ?>/unit-test/autocomplete/format/ajax"
requestMethod="get"// フォームのレンダリング ?>
// Dojo 関連の CSS の、HTML head での読み込み ?>
"<?php echo $this->baseUrl()
?>/javascript/dijit/themes/tundra/tundra.css";
@import "<?php echo $this->baseUrl() ?>/javascript/dojo/resources/dojo.css"// 必要な Dojo ライブラリを含む javascript の、
// HTML head での読み込み ?>
'/javascript/dojo/dojo.js',
'text/javascript''djConfig' => 'parseOnLoad: true'"custom","../custom""dojo.parser""dojox.data.QueryReadStore""dijit.form.ComboBox""custom.TestNameReadStore"
headStyle や headScript といったビューヘルパーのコールに注意しましょう。
これらはプレースホルダで、ビュースクリプトをレンダリングする際に
HTML の head セクションとなります。
これで、Dojo のオートコンプリートを動作させるための準備がすべて整いました。
Scriptaculous でのオートコンプリート
» Scriptaculous
は、所定の形式の HTML レスポンスを受け取ることを想定しています。
このライブラリで使用するヘルパーは 'AutoCompleteScriptaculous' です。
このヘルパーにデータの配列を渡せば、Ajax.Autocompleter
に対応した形式の HTML レスポンスができあがります。
ContextSwitch および AjaxContext
ContextSwitch アクションヘルパーは、
リクエストに対してさまざまなレスポンスを返す機能を実現するためのものです。
AjaxContext ヘルパーは
ContextSwitch をより特化したもので、
レスポンスを XmlHttpRequests で返す機能を提供します。
いずれかを有効にするには、コントローラに対して
「どのアクションがどのコンテキストに対応するのか」
を教えてやる必要があります。
やってきたリクエストがそのアクションで有効なコンテキストである場合、
ヘルパーが行う処理は次のようになります。
レイアウト機能が有効な場合に、それを無効にする。
別のビューサフィックスを設定し、
コンテキストに応じて別のビュースクリプトを効率よく扱えるようにする。
コンテキストに応じて適切なレスポンスヘッダを送信する。
オプションで、指定したコールバックを実行して
コンテキストの設定や後処理を行う。
たとえば、次のようなコントローラを考えてみましょう。
span style="color: #808080; font-style: italic;">/**
* トップページは listAction() に転送します
*/'list');
}
/**
* ニュースの一覧
*//**
* ニュースの閲覧
*/
ここで、 listAction()
の結果を XML 形式でも返せるようにしたくなったとしましょう。
わざわざ別のアクションを作らなくても、
XML でレスポンスを返すように指示できます。
span style="color: #ff0000;">'contextSwitch''list', 'xml')
->initContext();
}
// ...
}
これが何を行っているかというと、
さて、次は新しいビュースクリプト 'news/list.xml.phtml'
を作成しましょう。これが XML の作成とレンダリングを行います。
あるリクエストがコンテキストスイッチを起動するかどうかを判断するために、
このヘルパーはリクエストオブジェクト内のトークンを調べます。
デフォルトでは 'format' というパラメータを調べることになっていますが、
これは変更することもできます。つまり、
ほとんどの場合は、リクエストに 'format' パラメータを追加するだけで
コンテキストスイッチを行えるということです。
ContextSwitch では任意のコンテキストを指定できます。
つまり (もし存在するなら) サフィックスを自由に変更したり
送信するレスポンスヘッダを任意のものに変更したり、
任意のコールバックで初期化や後処理を行ったりができるということです。
デフォルトで使用できるコンテキスト
ContextSwitch ヘルパーで
使用できるデフォルトのコンテキストは、json と XML のふたつです。
-
JSON。JSON コンテキストは、
'Content-Type' レスポンスヘッダを 'application/json' に設定し、
ビュースクリプトのサフィックスを 'json.phtml' とします。
しかし、デフォルトではビュースクリプトは不要です。
これは、すべてのビュー変数を単純にシリアライズして
JSON レスポンスを直接発行するものです。
自動 JSON シリアライズ機能を使わないようにすることもできます。
-
XML。XML コンテキストは、
'Content-Type' レスポンスヘッダを 'application/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 つの引数を指定します。
ひとつはコンテキストを追加したいアクション、
もうひとつはコンテキスト名あるいはコンテキスト名の配列です。
たとえば、次のようなコントローラクラスを考えてみましょう。
ここで、'list' アクションに XML コンテキストを、
そして 'comments' アクションに XML コンテキストと JSON
コンテキストを追加してみることにします。これは
init() メソッドで行います。
span style="color: #ff0000;">'list', 'xml')
->addActionContext('comments''xml', 'json'))
->initContext();
}
}
あるいは、単純に配列プロパティ
$contexts を設定することもできます。
span style="color: #ff0000;">'list''xml'),
'comments''xml', 'json'
このほうがオーバーヘッドが少なくなりますが、
書き間違える可能性もあります。
コンテキストの関連付けを行うメソッドには次のようなものがあります。
-
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() をコールする必要があります。
時には、使用するコンテキストを決めてしまいたいこともあるでしょう。
たとえば、コンテキストスイッチが起動したときには
XML コンテキストだけを使わせたいという場合などです。
その場合は、そのコンテキストを
initContext() に渡します。
span style="color: #ff0000;">'xml');
追加機能
さまざまなメソッドを使用することで、
ContextSwitch ヘルパーの挙動を変更できます。
たとえば次のようなメソッドが存在します。
-
setAutoJsonSerialization($flag):
デフォルトでは、JSON コンテキストはビュー変数をすべてシリアライズし、
JSON 記法にしたものをレスポンスとして返します。
レスポンスを自分で作成したい場合はこれをオフにしなければなりません。
これは、 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()
に FALSE を渡します。これは、
initContext() をコールするより
前に 行わなければなりません。
このフラグの現在の値を取得するには、アクセサ
getAutoDisableLayout() を使用します。
-
getCurrentContext() を使うと、
現在のコンテキストを取得できます。
コンテキストスイッチが発生していない場合や
initContext() の起動前にコールした場合は
NULL を返します。
AjaxContext の機能
AjaxContext ヘルパーは
ContextSwitch を継承したものです。
ContextSwitch の機能はすべて使用できます。
しかし、いくつか重要な違いがあります。
まず、コンテキストを決めるアクションコントローラのプロパティは
$ajaxable となります。これにより、
AJAX 用と通常の HTTP リクエスト用で別のコンテキストを使用できるようになります。
AjaxContext の *ActionContext()*
系のメソッドは、このプロパティに書き込みます。
次に、これは XmlHttpRequest が発生した場合にのみ起動します。
リクエストオブジェクトの isXmlHttpRequest()
メソッドで判断します。したがって、たとえコンテキストパラメータ
('format') をリクエストで渡したとしても、そのリクエストが
XmlHttpRequest でない場合はコンテキストスイッチが発生しません。
3 番目に、AjaxContext は HTML コンテキストを追加します。
このコンテキストでは、サフィックスを 'ajax.phtml'
として通常のリクエストのコンテキストと区別しています。
追加のヘッダは返しません。
Example #4 Ajax リクエストに対してアクションに応答させる
この例では、アクション 'view'、'form' および 'process'
に対する AJAX リクエストにレスポンスを返させるようにしています。
最初のふたつ 'view' および 'form' では、HTML
コード片を返してページを更新させます。最後の 'process'
については JSON を返しています。
span style="color: #ff0000;">'AjaxContext');
$ajaxContext->addActionContext('view', 'html')
->addActionContext('form', 'html')
->addActionContext('process', 'json'// 単一のコメントを表示します
// AjaxContext の場合は comment/view.ajax.phtml
// を使用します
// 新規コメントの追加フォームをレンダリングします
// AjaxContext の場合は comment/form.ajax.phtml
// を使用します
// 新規コメントを処理します
// 結果を JSON で返します。結果をビュー変数に格納するだけで、
// JSON でそれを返してくれます
}
}
クライアント側では、AJAX ライブラリからエンドポイント
'/comment/view'、'/comment/form' そして
'/comment/process' へリクエストを送ることになります。
その際に、'format' パラメータを
'/comment/view/format/html'、'/comment/form/format/html' そして
'/comment/process/format/json' のように指定します
(あるいはクエリ文字列で "?format=json" のようにしてもかまいません)。
ライブラリ側で 'X-Requested-With:
XmlHttpRequest' ヘッダが設定されていれば、
このアクションは適切な形式でレスポンスを返します。
FlashMessenger
Introduction
The FlashMessenger helper allows you to pass messages
that the user may need to see on the next request. To accomplish
this, FlashMessenger uses
Zend_Session_Namespace to store messages for future or
next request retrieval. It is generally a good idea that if you
plan on using Zend_Session or
Zend_Session_Namespace, that you initialize with
Zend_Session::start() in your bootstrap file. (See the
Zend_Session
documentation for more details on its usage.)
Available Methods
General methods:
-
setNamespace($namespace='default') is used to set the namespace
into which messages are stored by default.
-
getNamespace() is used to retrieve the name of the
default namespace. The default namespace is 'default'.
-
resetNamespace() is used to reset the namespace name
to the default value, 'default'.
Methods for manipulating messages set in the previous request:
-
hasMessages($namespace=NULL) is used to determine
if messages have been carried from a previous request by the flash messenger. The
optional argument $namespace specifies which namespace to look in.
If the $namespace argument is omitted, the value returned by
getNamespace() will be used.
-
getMessages($namespace=NULL) is used to retrieve the
messages which have been carried from a previous request by the flash messenger. The
optional argument $namespace specifies which namespace to pull from.
If the $namespace argument is omitted, the value returned by
getNamespace() will be used.
-
getIterator($namespace=NULL) wraps the return value of
getMessages() in an instance of ArrayObject.
If the $namespace argument is omitted, the value returned by
getNamespace() will be used.
-
count($namespace=NULL) returns the number of messages contained
in the specified namespace. If the $namespace argument is omitted, the
value returned by getNamespace() will be used.
-
clearMessages($namespace=NULL) is used to clear all the
messages which have been carried from a previous request by the flash messenger. The
optional argument $namespace specifies which namespace to clear out.
If the $namespace argument is omitted, the value returned by
getNamespace() will be used.
Methods for manipulating messages set in the current request:
-
addMessage($message, $namespace=NULL) is used to add a new
message to the current request. $message contains the message
to be added, and the optional argument $namespace will specify
the namespace. If the $namespace argument is omitted, the value
returned by getNamespace() will be used.
-
hasCurrentMessages($namespace=NULL) is used to determine
if messages have been added to the flash messenger during the current request. The
optional argument $namespace specifies which namespace to look in.
If the $namespace argument is omitted, the value returned by
getNamespace() will be used.
-
getCurrentMessages($namespace=NULL) is used to retrieve the
messages which have been added to the flash messenger during the current request. The
optional argument $namespace specifies which namespace to pull from.
If the $namespace argument is omitted, the value returned by
getNamespace() will be used.
-
clearCurrentMessages($namespace=NULL) is used to clear all the
messages which have been added to the flash messenger during the current request. The
optional argument $namespace specifies which namespace to clear out.
If the $namespace argument is omitted, the value returned by
getNamespace() will be used.
Basic Usage Example
The usage example below shows the use of the flash messenger at its
most basic. When the action /some/my is called, it adds
the flash message "Record Saved!" A subsequent request to the action
/some/my-next-request will retrieve it (and thus delete
it as well).
span style="color: #808080; font-style: italic;">/**
* FlashMessenger
*
* @var Zend_Controller_Action_Helper_FlashMessenger
*/'FlashMessenger'/**
* default method of getting
* Zend_Controller_Action_Helper_FlashMessenger instance
* on-demand
*/'Record Saved!'
JSON
JSON responses are rapidly becoming the response of choice when dealing
with AJAX requests that expect dataset responses;
JSON can be immediately parsed on the client-side, leading to quick
execution.
Usage
Usage is simple: either call it as a method of the helper broker, or
call one of the methods encodeJson() or
sendJson():
direct($data, $sendNow = true, $keepLayouts = false, $encodeData = true)
sendJson($data, $keepLayouts = false, $encodeData = true)
encodeJson($data, $keepLayouts = false, $encodeData = true)
-
$data: data to encode as JSON
-
$sendNow: flag to define whether
to send the JSON data immediately. When true, the helper
will immediately set the respose body and exit.
-
$keepLayouts: flag to define whether
to enable or disable layours. When false, all layouts
are disabled. Optionally, this can be an array of options
to pass as the second argument to Zend_Json::encode().
This array of options allows enabling layouts and encoding using
Zend_Json_Expr.
-
$encodeData: flag to define whether
$data is already JSON-encoded. When
true, this helper will not encode $data
to JSON before sending.
Note: Keeping Layouts
If you have a separate layout for JSON responses -- perhaps to wrap
the JSON response in some sort of context -- each method in the
JSON helper accepts an optional argument $keepLayouts: a flag to enable or
disable layouts. Passing a boolean TRUE value will keep
layouts enabled:
Optionally, you can pass an array as the third parameter. This
array may contain a variety of options, including the
keepLayouts option:
// Direct helper call
'keepLayouts'// ...or, call a method of the helper
'keepLayouts'
Note: Enabling encoding using Zend_Json_Expr
Zend_Json::encode() allows the encoding of native
JSON expressions using Zend_Json_Expr
objects. This option is disabled by default. To enable this option, pass a boolean
TRUE value to the enableJsonExprFinder
option:
span style="color: #ff0000;">'enableJsonExprFinder'
If you desire to do this, you must pass an
array as the third argument. This also allows you to combine other
options, such as the keepLayouts option. All such
options are then passed to Zend_Json::encode().
span style="color: #ff0000;">'enableJsonExprFinder''keepLayouts'
Example
span style="color: #808080; font-style: italic;">// do some processing...
// Send the JSON response:
// or...
// or retrieve the json:
Redirector(日本語)
導入
Redirector ヘルパーは、
アプリケーション内で必要となるリダイレクト処理用のオブジェクトとして使用します。
_redirect() メソッドと比べた場合の利点としては、
サイト全体で使用する設定を事前に組み込んでおけることがあります。また、
Zend_Controller_Action::_forward()
の場合と同様に、組み込みのインターフェイス
gotoSimple($action, $controller, $module, $params)
が使用できることも利点となります。
Redirector では、
リダイレクトの設定を行うメソッドとして次のようなものが用意されています。
-
setCode() を使用して、
リダイレクトの際に使用する HTTP レスポンスコードを設定します。
-
setExit() を使用して、
リダイレクトの後で強制的に exit() を実行させるようにします。
デフォルトは TRUE です。
-
setGotoSimple() を使用して、 gotoSimple()
に何も渡されなかったときのデフォルトの URL を設定します。
Zend_Controller_Action::_forward() の API である
setGotoSimple($action, $controller = null, $module = null, array
$params = array()) を使用します。
-
setGotoRoute() を使用して、
登録済みのルートにもとづいた URL を設定します。
キー/値 のペアの配列とルート名を渡し、
それをもとにルートの型と定義から URL を作成します。
-
setGotoUrl() を使用して、 gotoUrl()
に何も渡されなかったときのデフォルトの URL を設定します。
URL を表す文字列を受け取ります。
-
setPrependBase() を使用して、
setGotoUrl()、 gotoUrl()
あるいは gotoUrlAndExit()
で指定した URL の前にリクエストのベース URL を追加します。
-
setUseAbsoluteUri() を使用すると、
Redirector がリダイレクトの際に絶対
URI を使用するようになります。
このオプションを設定すると、
$_SERVER['HTTP_HOST'] や
$_SERVER['SERVER_PORT']、そして
$_SERVER['HTTPS'] の内容をもとにして
リダイレクト用の完全な URI を作成します。
このオプションのデフォルト値はオフですが、
将来のリリースではデフォルトで有効になるかもしれません。
さらに、実際のリダイレクトを行うためのメソッドとして以下のものが用意されています。
-
gotoSimple() は、 setGotoSimple()
( _forward() 風の API) を用いて作成した URL
にリダイレクトします。
-
gotoRoute() は、 setGotoRoute()
(ルートの作成) を用いて作成した URL
にリダイレクトします。
-
gotoUrl() は setGotoUrl()
(URL 文字列の指定) を用いて作成した URL
にリダイレクトします。
リダイレクト先の URL を知るには
getRedirectUrl() を使用します。
これはいつでも使用できます。
基本的な使用例
この例ではデフォルトのオプションを少し変更します。
HTTP ステータスコードを 303 にし、リダイレクト後に
exit() しないようにして、そしてリダイレクトの際のデフォルト
URL を指定しています。
span style="color: #808080; font-style: italic;">/**
* Redirector - defined for code completion
*
* @var Zend_Controller_Action_Helper_Redirector
*/'Redirector');
// リダイレクタのデフォルトのオプションを設定します
// このオブジェクトはヘルパーブローカに登録されるので、
// これ以降のすべてのアクションで有効となります
"this-action",
"some-controller"/* 何かを行います */
// 先ほど登録した URL にリダイレクトし、その後で
// exit() します
// 決してここには到達しません
}
}
この例ではデフォルト設定を使用しています。
つまり、リダイレクトするとすぐに
exit() が実行されるということです。
// 別の例
/**
* Redirector - defined for code completion
*
* @var Zend_Controller_Action_Helper_Redirector
*/'Redirector'/* 何かを行います */'/my-controller/my-action/param1/test/param2/test2'// リダイレクト後に自動的に exit() されるので、決してここには到達しません
}
}
Example #7 goto() での _forward() API の使用
gotoSimple() の API は、
Zend_Controller_Action::_forward()
と同じ形式です。違う点は、このメソッドは渡されたパラメータから URL
を作成し、デフォルトルータのデフォルトフォーマットである
:module/:controller/:action/* を使用するということです。
また、アクションチェインではなくリダイレクトを行います。
span style="color: #808080; font-style: italic;">/**
* Redirector - defined for code completion
*
* @var Zend_Controller_Action_Helper_Redirector
*/'Redirector'/* 何かを行います */
// 現在のモジュールの 'my-controller' コントローラの
// 'my-action' アクションにリダイレクトします。
// パラメータは param1 => test、param2 => test2 となります。
'my-action',
'my-controller''param1' => 'test',
'param2' => 'test2'
)
);
}
}
Example #8 gotoRoute() でのルートアセンブリの使用
次の例は、ルータ
の assemble() メソッドを使用して、
パラメータで指定した連想配列に基づく URL を作成しています。
次のようなルートが登録されているものと仮定します。
span style="color: #ff0000;">'blog/:year/:month/:day/:id''controller' => 'archive',
'module' => 'blog',
'action' => 'view')
);
$router->addRoute('blogArchive', $route);
year を 2006、month を 4、day を 24、そして ID を 42
として配列を渡すと、結果の URL は
/blog/2006/4/24/42 となります。
span style="color: #808080; font-style: italic;">/**
* Redirector - defined for code completion
*
* @var Zend_Controller_Action_Helper_Redirector
*/'Redirector'/* 何かを行います */
// blog の過去記事にリダイレクトします。URL は
// /blog/2006/4/24/42 になります。
'year' => 2006,
'month' => 4,
'day' => 24,
'id' => 42),
'blogArchive'
);
}
}
ViewRenderer(日本語)
導入
ViewRenderer ヘルパーは、
以下のような要件を満たすために作られたものです。
-
コントローラ内でいちいちビューオブジェクトのインスタンスを
作成しなくても済むようにする。
ビューオブジェクトは自動的にコントローラに登録されます。
-
ビュースクリプトやヘルパー、そしてフィルタのパスを
現在のモジュールに基づいて自動的に設定し、
モジュール名をヘルパーやフィルタのクラス名の先頭に自動的に関連付ける。
-
すべてのコントローラとアクションで使用できる
グローバルなビューオブジェクトを作成する。
-
すべてのコントローラで使用する、
デフォルトのビューレンダリングオプションを設定できるようにする。
-
何も指定しなくても、
自動的にビュースクリプトをレンダリングできる機能を追加する。
-
ビューの基底パスやビュースクリプトのパスを
独自に指定できるようにする。
Note:
_forward() や redirect()、
あるいは手動での render() を行う場合は、
自動レンダリングは不要です。これらの処理を行う場合は、
出力を自前で行うことを ViewRenderer
に対して指示します。
Note:
ViewRenderer はデフォルトで有効になっています。
これを無効にするには、フロントコントローラのパラメータ
noViewRenderer を指定する
($front->setParam('noViewRenderer', true);) か、
あるいはヘルパーブローカからヘルパーを削除
( Zend_Controller_Action_HelperBroker::removeHelper('viewRenderer'))
します。
フロントコントローラでのディスパッチ処理の前に
ViewRenderer の設定を変更したい場合は、
次のいずれかの方法を使用します。
|
|