Caution: The documentation you are viewing is
for an older version of Zend Framework.
You can find the documentation of the current version at:
https://docs.zendframework.com/
Action Helpers - Zend_Controller
Action Helpers allow developers to inject runtime and/or on-demand functionality into any Action Controllers that extend Zend_Controller_Action. Action Helpers aim to minimize the necessity to extend the abstract Action Controller in order to inject common Action Controller functionality.
There are a number of ways to use Action Helpers. Action Helpers employ the use of a brokerage system, similar to the types of brokerage you see in Zend_View_Helper, and that of Zend_Controller_Plugin. Action Helpers (like Zend_View_Helper) may be loaded and called on demand, or they may be instantiated at request time (bootstrap) or action controller creation time ( init()). To understand this more fully, please see the usage section below.
A helper can be initialized in several different ways, based on your needs as well as the functionality of that helper.
The helper broker is stored as the $_helper member of Zend_Controller_Action; use the broker to retrieve or call on helpers. Some methods for doing so include:
Explicitly using getHelper(). Simply pass it a name, and a helper object is returned:
Use the helper broker's __get() functionality and retrieve the helper as if it were a member property of the broker:
Finally, most action helpers implement the method direct() which will call a specific, default method in the helper. In the example of the FlashMessenger, it calls addMessage():
Note: All of the above examples are functionally equivalent.
You may also instantiate helpers explicitly. You may wish to do this if using the helper outside of an action controller, or if you wish to pass a helper to the helper broker for use by any action. Instantiation is as per any other PHP class.
Zend_Controller_Action_HelperBroker handles the details of registering helper objects and helper paths, as well as retrieving helpers on-demand.
To register a helper with the broker, use addHelper():
Of course, instantiating and passing helpers to the broker is a bit time and resource intensive, so two methods exists to automate things slightly: addPrefix() and addPath().
addPrefix() takes a class prefix and uses it to determine a path where helper classes have been defined. It assumes the prefix follows Zend Framework class naming conventions.
addPath() takes a directory as its first argument and a class prefix as the second argument (defaulting to 'Zend_Controller_Action_Helper'). This allows you to map your own class prefixes to specific directories.
Since these methods are static, they may be called at any point in the controller chain in order to dynamically add helpers as needed.
Internally, the helper broker uses a PluginLoader instance to maintain paths. You can retrieve the PluginLoader using the static method getPluginLoader(), or, alternately, inject a custom PluginLoader instance using setPluginLoader().
To determine if a helper exists in the helper broker, use hasHelper($name), where $name is the short name of the helper (minus the prefix):
There are also two static methods for retrieving helpers from the helper broker: getExistingHelper() and getStaticHelper(). getExistingHelper() will retrieve a helper only if it has previously been invoked by or explicitly registered with the helper broker; it will throw an exception if not. getStaticHelper() does the same as getExistingHelper(), but will attempt to instantiate the helper if has not yet been registered with the helper stack. getStaticHelper() is a good choice for retrieving helpers which you wish to configure.
Both methods take a single argument, $name, which is the short name of the helper (minus the prefix).
Finally, to delete a registered helper from the broker, use removeHelper($name), where $name is the short name of the helper (minus the prefix):
Zend Framework includes several action helpers by default: AutoComplete for automating responses for AJAX autocompletion; ContextSwitch and AjaxContext for serving alternate response formats for your actions; a FlashMessenger for handling session flash messages; Json for encoding and sending JSON responses; a Redirector, to provide different implementations for redirecting to internal and external pages from your application; and a ViewRenderer to automate the process of setting up the view object in your controllers and rendering views.
The ActionStack helper allows you to push requests to the ActionStack front controller plugin, effectively helping you create a queue of actions to execute during the request. The helper allows you to add actions either by specifying new request objects or action - controller - module sets.
Note: Invoking ActionStack Helper Initializes the ActionStack Plugin
Invoking the ActionStack helper implicitly registers the ActionStack plugin -- which means you do not need to explicitly register the ActionStack plugin to use this functionality.
Example #1 Adding a Task Using Action, Controller and Module Names
Often, it's simplest to simply specify the action, controller, and module (and optional request parameters), much as you would when calling Zend_Controller_Action::_forward():
Example #2 Adding a Task Using a Request Object
Sometimes the OOP nature of a request object makes most sense; you can pass such an object to the ActionStack helper as well.
Many AJAX javascript libraries offer functionality for providing autocompletion whereby a selectlist of potentially matching results is displayed as the user types. The AutoComplete helper aims to simplify returning acceptable responses to such methods.
Since not all JS libraries implement autocompletion in the same way, the AutoComplete helper provides some abstract base functionality necessary to many libraries, and concrete implementations for individual libraries. Return types are generally either JSON arrays of strings, JSON arrays of arrays (with each member array being an associative array of metadata used to create the selectlist), or HTML.
Basic usage for each implementation is the same:
By default, autocompletion does the following:
Disables layouts and ViewRenderer.
Sets appropriate response headers.
Sets response body with encoded or formatted autocompletion data.
Sends response.
Available methods of the helper include:
disableLayouts() can be used to disable layouts and the ViewRenderer. Typically, this is called within prepareAutoCompletion().
encodeJson($data, $keepLayouts = false) will encode data to JSON, optionally enabling or disabling layouts. Typically, this is called within prepareAutoCompletion().
prepareAutoCompletion($data, $keepLayouts = false) is used to prepare data in the response format necessary for the concrete implementation, optionally enabling or disabling layouts. The return value will vary based on the implementation.
sendAutoCompletion($data, $keepLayouts = false) is used to send data in the response format necessary for the concrete implementation. It calls prepareAutoCompletion(), and then sends the response.
direct($data, $sendNow = true, $keepLayouts = false) is used when calling the helper as a method of the helper broker. The $sendNow flag is used to determine whether to call sendAutoCompletion() or prepareAutoCompletion(), respectively.
Currently, AutoComplete supports the Dojo and Scriptaculous AJAX libraries.
Dojo does not have an AutoCompletion widget per se, but has two widgets that can perform AutoCompletion: ComboBox and FilteringSelect. In both cases, they require a data store that implements the QueryReadStore; for more information on these topics, see the » dojo.data documentation.
In Zend Framework, you can pass a simple indexed array to the AutoCompleteDojo helper, and it will return a JSON response suitable for use with such a store:
Example #3 AutoCompletion with Dojo Using Zend MVC
AutoCompletion with Dojo via the Zend MVC requires several things: generating a form object for the ComboBox on which you want AutoCompletion, a controller action for serving the AutoCompletion results, creating a custom QueryReadStore to connect to the AutoCompletion action, and generation of the javascript to use to initialize AutoCompletion on the server side.
First, let's look at the javascript necessary. Dojo offers a complete framework for creating OOP javascript, much as Zend Framework does for PHP. Part of that is the ability to create pseudo-namespaces using the directory hierarchy. We'll create a 'custom' directory at the same level as the Dojo directory that's part of the Dojo distribution. Inside that directory, we'll create a javascript file, TestNameReadStore.js, with the following contents:
This class is simply an extension of Dojo's own QueryReadStore, which is itself an abstract class. We simply define a method by which to request, and assigning it to the 'test' element.
Next, let's create the form element for which we want AutoCompletion:
Here, we simply create a form with 'test' and 'go' methods. The 'test' method adds several special, Dojo-specific attributes: dojoType, store, autoComplete, and hasDownArrow. The dojoType is used to indicate that we are creating a ComboBox, and we will link it to a data store (key 'store') of 'testStore' -- more on that later. Specifying 'autoComplete' as FALSE tells Dojo not to automatically select the first match, but instead show a list of matches. Finally, 'hasDownArrow' creates a down arrow similar to a select box so we can show and hide the matches.
Let's add a method to display the form, as well as an end point for processing AutoCompletion:
In our autocompleteAction() we do a number of things. First, we look to make sure we have a post request, and that there is a 'format' parameter set to the value 'ajax'; these are simply to help reduce spurious queries to the action. Next, we check for a 'test' parameter, and compare it against our data. (I purposely leave out the implementation of getData() here -- it could be any sort of data source.) Finally, we send our matches to our AutoCompletion helper.
Now that we have all the pieces on the backend, let's look at what we need to deliver in our view script for the landing page. First, we need to setup our data store, then render our form, and finally ensure that the appropriate Dojo libraries -- including our custom data store -- get loaded. Let's look at the view script, which comments the steps:
Note the calls to view helpers such as headStyle and headScript; these are placeholders, which we can then render in the HTML head section of our layout view script.
We now have all the pieces to get Dojo AutoCompletion working.
» Scriptaculous expects an HTML response in a specific format.
The helper to use with this library is 'AutoCompleteScriptaculous'. Simply provide it an array of data, and the helper will create an HTML response compatible with Ajax.Autocompleter.
The ContextSwitch action helper is intended for facilitating returning different response formats on request. The AjaxContext helper is a specialized version of ContextSwitch that facilitates returning responses to XmlHttpRequests.
To enable either one, you must provide hinting in your controller as to what actions can respond to which contexts. If an incoming request indicates a valid context for the given action, the helper will then:
Disable layouts, if enabled.
Set an alternate view suffix, effectively requiring a separate view script for the context.
Send appropriate response headers for the context desired.
Optionally, call specified callbacks to setup the context and/or perform post-processing.
As an example, let's consider the following controller:
Let's say that we want the listAction() to also be available in an XML format. Instead of creating a different action, we can hint that it can return an XML response:
What this will do is:
Set the 'Content-Type' response header to 'application/xml'.
Change the view suffix to 'xml.phtml' (or, if you use an alternate view suffix, 'xml.[your suffix]').
Now, you'll need to create a new view script, 'news/list.xml.phtml', which will create and render the XML.
To determine if a request should initiate a context switch, the helper checks for a token in the request object. By default, it looks for the 'format' parameter, though this may be configured. This means that, in most cases, to trigger a context switch, you can add a 'format' parameter to your request:
Via URL parameter: /news/list/format/xml (recall, the default routing schema allows for arbitrary key to value pairs following the action)
Via GET parameter: /news/list?format=xml
ContextSwitch allows you to specify arbitrary contexts, including what suffix change will occur (if any), any response headers that should be sent, and arbitrary callbacks for initialization and post processing.
By default, two contexts are available to the ContextSwitch helper: json and XML.
JSON. The JSON context sets the 'Content-Type' response header to 'application/json', and the view script suffix to 'json.phtml'.
By default, however, no view script is required. It will simply serialize all view variables, and emit the JSON response immediately.
This behaviour can be disabled by turning off the automatic JSON serialization:
XML. The XML context sets the 'Content-Type' response header to 'application/xml', and the view script suffix to 'xml.phtml'. You will need to create a new view script for the context.
Sometimes, the default contexts are not enough. For instance, you may wish to return YAML, or serialized PHP, an RSS or ATOM feed, etc. ContextSwitch allows you to do so.
The easiest way to add a new context is via the addContext() method. This method takes two arguments, the name of the context, and an array specification. The specification should include one or more of the following:
suffix: the suffix to prepend to the default view suffix as registered in the ViewRenderer.
headers: an array of header to value pairs you wish sent as part of the response.
callbacks: an array containing one or more of the keys 'init' or 'post', pointing to valid PHP callbacks that can be used for context initialization and post processing.
Initialization callbacks occur when the context is detected by ContextSwitch. You can use it to perform arbitrary logic that should occur. As an example, the JSON context uses a callback to disable the ViewRenderer when the automatic JSON serialization is on.
Post processing occurs during the action's postDispatch() routine, and can be used to perform arbitrary logic. As an example, the JSON context uses a callback to determine if the automatic JSON serialization is on; if so, it serializes the view variables to JSON and sends the response, but if not, it re-enables the ViewRenderer.
There are a variety of methods for interacting with contexts:
addContext($context, array $spec): add a new context. Throws an exception if the context already exists.
setContext($context, array $spec): add a new context or overwrite an existing context. Uses the same specification as addContext().
addContexts(array $contexts): add many contexts at once. The $contexts array should be an array of context to specification pairs. If any of the contexts already exists, it will throw an exception.
setContexts(array $contexts): add new contexts and overwrite existing ones. Uses the same specification as addContexts().
hasContext($context): returns TRUE if the context exists, FALSE otherwise.
getContext($context): retrieve a single context by name. Returns an array following the specification used in addContext().
getContexts(): retrieve all contexts. Returns an array of context to specification pairs.
removeContext($context): remove a single context by name. Returns TRUE if successful, FALSE if the context was not found.
clearContexts(): remove all contexts.
There are two mechanisms for setting available contexts. You can either manually create arrays in your controller, or use several methods in ContextSwitch to assemble them.
The principle method for adding action to context relations is addActionContext(). It expects two arguments, the action to which the context is being added, and either the name of a context or an array of contexts. As an example, consider the following controller class:
Let's say we wanted to add an XML context to the 'list' action, and XML and JSON contexts to the 'comments' action. We could do so in the init() method:
Alternately, you could simply define the array property $contexts:
The above is less overhead, but also prone to potential errors.
The following methods can be used to build the context mappings:
addActionContext($action, $context): marks one or more contexts as available to an action. If mappings already exists, simply appends to those mappings. $context may be a single context, or an array of contexts.
A value of TRUE for the context will mark all available contexts as available for the action.
An empty value for $context will disable all contexts for the given action.
setActionContext($action, $context): marks one or more contexts as available to an action. If mappings already exists, it replaces them with those specified. $context may be a single context, or an array of contexts.
addActionContexts(array $contexts): add several action to context pairings at once. $contexts should be an associative array of action to context pairs. It proxies to addActionContext(), meaning that if pairings already exist, it appends to them.
setActionContexts(array $contexts): acts like addActionContexts(), but overwrites existing action to context pairs.
hasActionContext($action, $context): determine if a particular action has a given context.
getActionContexts($action = null): returns either all contexts for a given action, or all action to context pairs.
removeActionContext($action, $context): remove one or more contexts from a given action. $context may be a single context or an array of contexts.
clearActionContexts($action = null): remove all contexts from a given action, or from all actions with contexts.
To initialize context switching, you need to call initContext() in your action controller:
In some cases, you may want to force the context used; for instance, you may only want to allow the XML context if context switching is activated. You can do so by passing the context to initContext():
A variety of methods can be used to alter the behaviour of the ContextSwitch helper. These include:
setAutoJsonSerialization($flag): By default, JSON contexts will serialize any view variables to JSON notation and return this as a response. If you wish to create your own response, you should turn this off; this needs to be done prior to the call to initContext().
You can retrieve the value of the flag with getAutoJsonSerialization().
setSuffix($context, $suffix, $prependViewRendererSuffix): With this method, you can specify a different suffix to use for a given context. The third argument is used to indicate whether or not to prepend the current ViewRenderer suffix with the new suffix; this flag is enabled by default.
Passing an empty value to the suffix will cause only the ViewRenderer suffix to be used.
addHeader($context, $header, $content): Add a response header for a given context. $header is the header name, and $content is the value to pass for that header.
Each context can have multiple headers; addHeader() adds additional headers to the context's header stack.
If the $header specified already exists for the context, an exception will be thrown.
setHeader($context, $header, $content): setHeader() acts just like addHeader(), except it allows you to overwrite existing context headers.
addHeaders($context, array $headers): Add multiple headers at once to a given context. Proxies to addHeader(), so if the header already exists, an exception will be thrown. $headers is an array of header to context pairs.
setHeaders($context, array $headers.): like addHeaders(), except it proxies to setHeader(), allowing you to overwrite existing headers.
getHeader($context, $header): retrieve the value of a header for a given context. Returns NULL if not found.
removeHeader($context, $header): remove a single header for a given context.
clearHeaders($context, $header): remove all headers for a given context.
setCallback($context, $trigger, $callback): set a callback at a given trigger for a given context. Triggers may be either 'init' or 'post' (indicating callback will be called at either context initialization or postDispatch). $callback should be a valid PHP callback.
setCallbacks($context, array $callbacks): set multiple callbacks for a given context. $callbacks should be trigger to callback pairs. In actuality, the most callbacks that can be registered are two, one for initialization and one for post processing.
getCallback($context, $trigger): retrieve a callback for a given trigger in a given context.
getCallbacks($context): retrieve all callbacks for a given context. Returns an array of trigger to callback pairs.
removeCallback($context, $trigger): remove a callback for a given trigger and context.
clearCallbacks($context): remove all callbacks for a given context.
setContextParam($name): set the request parameter to check when determining if a context switch has been requested. The value defaults to 'format', but this accessor can be used to set an alternate value.
getContextParam() can be used to retrieve the current value.
setAutoDisableLayout($flag): By default, layouts are disabled when a context switch occurs; this is because typically layouts will only be used for returning normal responses, and have no meaning in alternate contexts. However, if you wish to use layouts (perhaps you may have a layout for the new context), you can change this behaviour by passing a FALSE value to setAutoDisableLayout(). You should do this before calling initContext().
To get the value of this flag, use the accessor getAutoDisableLayout().
getCurrentContext() can be used to determine what context was detected, if any. This returns NULL if no context switch occurred, or if called before initContext() has been invoked.
The AjaxContext helper extends ContextSwitch, so all of the functionality listed for ContextSwitch is available to it. There are a few key differences, however.
First, it uses a different action controller property for determining contexts, $ajaxable. This is so you can have different contexts used for AJAX versus normal HTTP requests. The various * ActionContext()* methods of AjaxContext will write to this property.
Second, it will only trigger if an XmlHttpRequest has occurred, as determined by the request object's isXmlHttpRequest() method. Thus, if the context parameter ('format') is passed in the request, but the request was not made as an XmlHttpRequest, no context switch will trigger.
Third, AjaxContext adds an additional context, HTML. In this context, it sets the suffix to 'ajax.phtml' in order to differentiate the context from a normal request. No additional headers are returned.
Example #4 Allowing Actions to Respond To Ajax Requests
In this following example, we're allowing requests to the actions 'view', 'form', and 'process' to respond to AJAX requests. In the first two cases, 'view' and 'form', we'll return HTML snippets with which to update the page; in the latter, we'll return JSON.
On the client end, your AJAX library will simply request the endpoints '/comment/view', '/comment/form', and '/comment/process', and pass the 'format' parameter: '/comment/view/format/html', '/comment/form/format/html', '/comment/process/format/json'. (Or you can pass the parameter via query string: e.g., "?format=json".)
Assuming your library passes the 'X-Requested-With: XmlHttpRequest' header, these actions will then return the appropriate response format.
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.)
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.
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).
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 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:
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:
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().
The Redirector helper allows you to use a redirector object to fulfill your application's needs for redirecting to a new URL. It provides numerous benefits over the _redirect() method, such as being able to preconfigure sitewide behavior into the redirector object or using the built in gotoSimple($action, $controller, $module, $params) interface similar to that of Zend_Controller_Action::_forward().
The Redirector has a number of methods that can be used to affect the behaviour at redirect:
setCode() can be used to set the HTTP response code to use during the redirect.
setExit() can be used to force an exit() following a redirect. By default this is TRUE.
setGotoSimple() can be used to set a default URL to use if none is passed to gotoSimple(). Uses the API of Zend_Controller_Action::_forward(): setGotoSimple($action, $controller = null, $module = null, array $params = array())
setGotoRoute() can be used to set a URL based on a registered route. Pass in an array of key / value pairs and a route name, and it will assemble the URL according to the route type and definition.
setGotoUrl() can be used to set a default URL to use if none is passed to gotoUrl(). Accepts a single URL string.
setPrependBase() can be used to prepend the request object's base URL to a URL specified with setGotoUrl(), gotoUrl(), or gotoUrlAndExit().
setUseAbsoluteUri() can be used to force the Redirector to use absolute URIs when redirecting. When this option is set, it uses the value of $_SERVER['HTTP_HOST'], $_SERVER['SERVER_PORT'], and $_SERVER['HTTPS'] to form a full URI to the URL specified by one of the redirect methods. This option is off by default, but may be enabled by default in later releases.
Additionally, there are a variety of methods in the redirector for performing the actual redirects:
gotoSimple() uses setGotoSimple() ( _forward()-like API) to build a URL and perform a redirect.
gotoRoute() uses setGotoRoute() (route-assembly) to build a URL and perform a redirect.
gotoUrl() uses setGotoUrl() (URL string) to build a URL and perform a redirect.
Finally, you can determine the current redirect URL at any time using getRedirectUrl().
Example #5 Setting Options
This example overrides several options, including setting the HTTP status code to use in the redirect ('303'), not defaulting to exit on redirect, and defining a default URL to use when redirecting.
Example #6 Using Defaults
This example assumes that the defaults are used, which means that any redirect will result in an immediate exit().
Example #7 Using goto()'s _forward() API
gotoSimple()'s API mimics that of Zend_Controller_Action::_forward(). The primary difference is that it builds a URL from the parameters passed, and using the default :module/:controller/:action/* format of the default router. It then redirects instead of chaining the action.
Example #8 Using Route Assembly with gotoRoute()
The following example uses the router's assemble() method to create a URL based on an associative array of parameters passed. It assumes the following route has been registered:
Given an array with year set to 2006, month to 4, day to 24, and id to 42, it would then build the URL /blog/2006/4/24/42.
The ViewRenderer helper is designed to satisfy the following goals:
Eliminate the need to instantiate view objects within controllers; view objects will be automatically registered with the controller.
Automatically set view script, helper, and filter paths based on the current module, and automatically associate the current module name as a class prefix for helper and filter classes.
Create a globally available view object for all dispatched controllers and actions.
Allow the developer to set default view rendering options for all controllers.
Add the ability to automatically render a view script with no intervention.
Allow the developer to create her own specifications for the view base path and for view script paths.
Note: If you perform a _forward(), redirect(), or render() manually, autorendering will not occur, as by performing any of these actions you are telling the ViewRenderer that you are determining your own output.
Note: The ViewRenderer is enabled by default. You may disable it via the front controller noViewRenderer param ($front->setParam('noViewRenderer', true);) or removing the helper from the helper broker stack ( Zend_Controller_Action_HelperBroker::removeHelper('viewRenderer')).
If you wish to modify settings of the ViewRenderer prior to dispatching the front controller, you may do so in one of two ways:
Instantiate and register your own ViewRenderer object and pass it to the helper broker:
Initialize and/or retrieve a ViewRenderer object on demand via the helper broker:
At its most basic usage, you simply instantiate the ViewRenderer and pass it to the action helper broker. The easiest way to instantiate it and register in one go is to use the helper broker's getStaticHelper() method:
The first time an action controller is instantiated, it will trigger the ViewRenderer to instantiate a view object. Each time a controller is instantiated, the ViewRenderer's init() method is called, which will cause it to set the view property of the action controller, and call addScriptPath() with a path relative to the current module; this will be called with a class prefix named after the current module, effectively namespacing all helper and filter classes you define for the module.
Each time postDispatch() is called, it will call render() for the current action.
As an example, consider the following class:
The ViewRenderer also defines a number of accessors to allow setting and retrieving view options:
setView($view) allows you to set the view object for the ViewRenderer. It gets set as the public class property $view.
setNeverRender($flag = true) can be used to disable or enable autorendering globally, i.e., for all controllers. If set to TRUE, postDispatch() will not automatically call render() in the current controller. getNeverRender() retrieves the current value.
setNoRender($flag = true) can be used to disable or enable autorendering. If set to TRUE, postDispatch() will not automatically call render() in the current controller. This setting is reset each time preDispatch() is called (i.e., you need to set this flag for each controller for which you don't want autorenderering to occur). getNoRender() retrieves the current value.
setNoController($flag = true) can be used to tell render() not to look for the action script in a subdirectory named after the controller (which is the default behaviour). getNoController() retrieves the current value.
setNeverController($flag = true) is analogous to setNoController(), but works on a global level -- i.e., it will not be reset for each dispatched action. getNeverController() retrieves the current value.
setScriptAction($name) can be used to specify the action script to render. $name should be the name of the script minus the file suffix (and without the controller subdirectory, unless noController has been turned on). If not specified, it looks for a view script named after the action in the request object. getScriptAction() retrieves the current value.
setResponseSegment($name) can be used to specify which response object named segment to render into. If not specified, it renders into the default segment. getResponseSegment() retrieves the current value.
initView($path, $prefix, $options) may be called to specify the base view path, class prefix for helper and filter scripts, and ViewRenderer options. You may pass any of the following flags: neverRender, noRender, noController, scriptAction, and responseSegment.
setRender($action = null, $name = null, $noController = false) allows you to set any of scriptAction, responseSegment, and noController in one pass. direct() is an alias to this method, allowing you to call this method easily from your controller:
Note: setRender() and direct() don't actually render the view script, but instead set hints that postDispatch() and render() will use to render the view.
The constructor allows you to optionally pass the view object and ViewRenderer options; it accepts the same flags as initView():
There are several additional methods for customizing path specifications used for determining the view base path to add to the view object, and the view script path to use when autodetermining the view script to render. These methods each take one or more of the following placeholders:
:moduleDir refers to the current module's base directory (by convention, the parent directory of the module's controller directory).
:module refers to the current module name.
:controller refers to the current controller name.
:action refers to the current action name.
:suffix refers to the view script suffix (which may be set via setViewSuffix()).
The methods for controlling path specifications are:
setViewBasePathSpec($spec) allows you to change the path specification used to determine the base path to add to the view object. The default specification is :moduleDir/views. You may retrieve the current specification at any time using getViewBasePathSpec().
setViewScriptPathSpec($spec) allows you to change the path specification used to determine the path to an individual view script (minus the base view script path). The default specification is :controller/:action.:suffix. You may retrieve the current specification at any time using getViewScriptPathSpec().
setViewScriptPathNoControllerSpec($spec) allows you to change the path specification used to determine the path to an individual view script when noController is in effect (minus the base view script path). The default specification is :action.:suffix. You may retrieve the current specification at any time using getViewScriptPathNoControllerSpec().
For fine-grained control over path specifications, you may use Zend_Filter_Inflector. Under the hood, the ViewRenderer uses an inflector to perform path mappings already. To interact with the inflector -- either to set your own for use, or to modify the default inflector, the following methods may be used:
getInflector() will retrieve the inflector. If none exists yet in the ViewRenderer, it creates one using the default rules.
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) allows you to set a custom inflector for use with the ViewRenderer. If $reference is TRUE, it will set the suffix and module directory as static references to ViewRenderer properties, as well as the target.
Note: Default Lookup Conventions
The ViewRenderer does some path normalization to make view script lookups easier. The default rules are as follows:
:module: MixedCase and camelCasedWords are separated by dashes, and the entire string cast to lowercase. E.g.: "FooBarBaz" becomes "foo-bar-baz".
Internally, the inflector uses the filters Zend_Filter_Word_CamelCaseToDash and Zend_Filter_StringToLower.
:controller: MixedCase and camelCasedWords are separated by dashes; underscores are converted to directory separators, and the entire string cast to lower case. Examples: "FooBar" becomes "foo-bar"; "FooBar_Admin" becomes "foo-bar/admin".
Internally, the inflector uses the filters Zend_Filter_Word_CamelCaseToDash, Zend_Filter_Word_UnderscoreToSeparator, and Zend_Filter_StringToLower.
:action: MixedCase and camelCasedWords are separated by dashes; non-alphanumeric characters are translated to dashes, and the entire string cast to lower case. Examples: "fooBar" becomes "foo-bar"; "foo-barBaz" becomes "foo-bar-baz".
Internally, the inflector uses the filters Zend_Filter_Word_CamelCaseToDash, Zend_Filter_PregReplace, and Zend_Filter_StringToLower.
The final items in the ViewRenderer API are the methods for actually determining view script paths and rendering views. These include:
renderScript($script, $name) allows you to render a script with a path you specify, optionally to a named path segment. When using this method, the ViewRenderer does no autodetermination of the script name, but instead directly passes the $script argument directly to the view object's render() method.
Note: Once the view has been rendered to the response object, it sets the noRender to prevent accidentally rendering the same view script multiple times.
Note: By default, Zend_Controller_Action::renderScript() proxies to the ViewRenderer's renderScript() method.
getViewScript($action, $vars) creates the path to a view script based on the action passed and/or any variables passed in $vars. Keys for this array may include any of the path specification keys ('moduleDir', 'module', 'controller', 'action', and 'suffix'). Any variables passed will be used; otherwise, values based on the current request will be utlized.
getViewScript() will use either the viewScriptPathSpec or viewScriptPathNoControllerSpec based on the setting of the noController flag.
Word delimiters occurring in module, controller, or action names will be replaced with dashes ('-'). Thus, if you have the controller name 'foo.bar' and the action 'baz:bat', using the default path specification will result in a view script path of 'foo-bar/baz-bat.phtml'.
Note: By default, Zend_Controller_Action::getViewScript() proxies to the ViewRenderer's getViewScript() method.
render($action, $name, $noController) checks first to see if either $name or $noController have been passed, and if so, sets the appropriate flags (responseSegment and noController, respectively) in the ViewRenderer. It then passes the $action argument, if any, on to getViewScript(). Finally, it passes the calculated view script path to renderScript().
Note: Be aware of the side-effects of using render(): the values you pass for the response segment name and for the noController flag will persist in the object. Additionally, noRender will be set after rendering is completed.
Note: By default, Zend_Controller_Action::render() proxies to the ViewRenderer's render() method.
renderBySpec($action, $vars, $name) allows you to pass path specification variables in order to determine the view script path to create. It passes $action and $vars to getScriptPath(), and then passes the resulting script path and $name on to renderScript().
Example #9 Basic Usage
At its most basic, you simply initialize and register the ViewRenderer helper with the helper broker in your bootstrap, and then set variables in your action methods.
Note: Naming Conventions: Word Delimiters in Controller and Action Names
If your controller or action name is composed of several words, the dispatcher requires that these are separated on the URL by specific path and word delimiter characters. The ViewRenderer replaces any path delimiter found in the controller name with an actual path delimiter ('/'), and any word delimiter found with a dash ('-') when creating paths. Thus, a call to the action /foo.bar/baz.bat would dispatch to FooBarController::bazBatAction() in FooBarController.php, which would render foo-bar/baz-bat.phtml; a call to the action /bar_baz/baz-bat would dispatch to Bar_BazController::bazBatAction() in Bar/BazController.php (note the path separation) and render bar/baz/baz-bat.phtml.
Note that the in the second example, the module is still the default module, but that, because of the existence of a path separator, the controller receives the name Bar_BazController, in Bar/BazController.php. The ViewRenderer mimics the controller directory hierarchy.
Example #10 Disabling Autorender
For some actions or controllers, you may want to turn off the autorendering -- for instance, if you're wanting to emit a different type of output (XML, JSON, etc), or if you simply want to emit nothing. You have two options: turn off all cases of autorendering ( setNeverRender()), or simply turn it off for the current action ( setNoRender()).
Note: In most cases, it makes no sense to turn off autorendering globally (ala setNeverRender()), as the only thing you then gain from ViewRenderer is the autosetup of the view object.
Example #11 Choosing a Different View Script
Some situations require that you render a different script than one named after the action. For instance, if you have a controller that has both add and edit actions, they may both display the same 'form' view, albeit with different values set. You can easily change the script name used with either setScriptAction(), setRender(), or calling the helper as a method, which will invoke setRender().
Example #12 Modifying the Registered View
What if you need to modify the view object -- for instance, change the helper paths, or the encoding? You can do so either by modifying the view object set in your controller, or by grabbing the view object out of the ViewRenderer; both are references to the same object.
Example #13 Changing the Path Specifications
In some circumstances, you may decide that the default path specifications do not fit your site's needs. For instance, you may want to have a single template tree to which you may then give access to your designers (this is very typical when using » Smarty, for instance). In such a case, you may want to hardcode the view base path specification, and create an alternate specification for the action view script paths themselves.
For purposes of this example, let's assume that the base path to views should be '/opt/vendor/templates', and that you wish for view scripts to be referenced by ':moduleDir/:controller/:action.:suffix'; if the noController flag has been set, you want to render out of the top level instead of in a subdirectory (':action.:suffix'). Finally, you want to use 'tpl' as the view script filename suffix.
Example #14 Rendering Multiple View Scripts from a Single Action
At times, you may need to render multiple view scripts from a single action. This is very straightforward -- simply make multiple calls to render():
Action helpers extend Zend_Controller_Action_Helper_Abstract, an abstract class that provides the basic interface and functionality required by the helper broker. These include the following methods:
setActionController() is used to set the current action controller.
init(), triggered by the helper broker at instantiation, can be used to trigger initialization in the helper; this can be useful for resetting state when multiple controllers use the same helper in chained actions.
preDispatch(), is triggered prior to a dispatched action.
postDispatch() is triggered when a dispatched action is done -- even if a preDispatch() plugin has skipped the action. Mainly useful for cleanup.
getRequest() retrieves the current request object.
getResponse() retrieves the current response object.
getName() retrieves the helper name. It retrieves the portion of the class name following the last underscore character, or the full class name otherwise. As an example, if the class is named Zend_Controller_Action_Helper_Redirector, it will return Redirector; a class named FooMessage will simply return itself.
You may optionally include a direct() method in your helper class. If defined, it allows you to treat the helper as a method of the helper broker, in order to allow easy, one-off usage of the helper. As an example, the redirector defines direct() as an alias of goto(), allowing use of the helper like this:
Internally, the helper broker's __call() method looks for a helper named redirector, then checks to see if that helper has a defined direct() method, and calls it with the arguments provided.
Once you have created your own helper class, you may provide access to it as described in the sections above.
