View Helpers
In your view scripts, often it is necessary to perform certain
complex functions over and over: e.g., formatting a date,
generating form elements, or displaying action links. You can
use helper classes to perform these behaviors for you.
A helper is simply a class. Let's say we want a helper named 'fooBar'.
By default, the class is prefixed with 'Zend_View_Helper_'
(you can specify a custom prefix when setting a helper path), and the
last segment of the class name is the helper name; this segment should
be TitleCapped; the full class name is then:
Zend_View_Helper_FooBar. This class should contain at the
minimum a single method, named after the helper, and camelCased:
fooBar().
Note: Watch the Case
Helper names are always camelCased, i.e., they never begin with an
uppercase character. The class name itself is MixedCased, but the
method that is actually executed is camelCased.
Note: Default Helper Path
The default helper path always points to the Zend Framework view
helpers, i.e., 'Zend/View/Helper/'. Even if you call
setHelperPath() to overwrite the existing paths, this
path will be set to ensure the default helpers work.
To use a helper in your view script, call it using
$this->helperName(). Behind the scenes,
Zend_View will load the
Zend_View_Helper_HelperName class, create an object
instance of it, and call its helperName() method. The
object instance is persistent within the Zend_View
instance, and is reused for all future calls to
$this->helperName().
Initial Helpers
Zend_View comes with an initial set of helper classes,
most of which relate to form element generation and perform
the appropriate output escaping automatically. In addition, there
are helpers for creating route-based URLs and HTML
lists, as well as declaring variables. The currently shipped helpers include:
-
declareVars(): Primarily for use when using
strictVars(), this helper can be used to declare
template variables that may or may not already be set in the
view object, as well as to set default values. Arrays passed as
arguments to the method will be used to set default values;
otherwise, if the variable does not exist, it is set to an empty string.
-
fieldset($name, $content, $attribs): Creates an
XHTML fieldset. If $attribs contains a
'legend' key, that value will be used for the fieldset legend. The
fieldset will surround the $content as provided to
the helper.
-
form($name, $attribs, $content): Generates an
XHTML form. All $attribs are escaped and
rendered as XHTML attributes of the form tag. If
$content is present and not a boolean
FALSE, then that content is rendered within the start and
close form tags; if $content is a boolean
FALSE (the default), only the opening form tag is
generated.
-
formButton($name, $value, $attribs): Creates an
<button /> element.
-
formCheckbox($name, $value, $attribs, $options):
Creates an <input type="checkbox" /> element.
By default, when no $value is provided and no $options are
present, '0' is assumed to be the unchecked value, and '1'
the checked value. If a $value is passed, but no $options
are present, the checked value is assumed to be the value
passed.
$options should be an array. If the array is indexed, the
first value is the checked value, and the second the
unchecked value; all other values are ignored. You may also
pass an associative array with the keys 'checked' and
'unChecked'.
If $options has been passed, if $value matches the checked
value, then the element will be marked as checked. You may
also mark the element as checked or unchecked by passing a
boolean value for the attribute 'checked'.
The above is probably best summed up with some examples:
// '1' and '0' as checked/unchecked options; not checked
echo $this-> formCheckbox('foo');
// '1' and '0' as checked/unchecked options; checked
echo $this-> formCheckbox('foo', null, array('checked' => true));
// 'bar' and '0' as checked/unchecked options; not checked
echo $this-> formCheckbox('foo', 'bar');
// 'bar' and '0' as checked/unchecked options; checked
echo $this-> formCheckbox('foo', 'bar', array('checked' => true));
// 'bar' and 'baz' as checked/unchecked options; unchecked
echo $this-> formCheckbox('foo', null, null, array('bar', 'baz'));
// 'bar' and 'baz' as checked/unchecked options; unchecked
echo $this-> formCheckbox('foo', null, null, array(
'checked' => 'bar',
'unChecked' => 'baz'
));
// 'bar' and 'baz' as checked/unchecked options; checked
echo $this-> formCheckbox('foo', 'bar', null, array('bar', 'baz'));
echo $this-> formCheckbox('foo',
null,
array('checked' => true),
// 'bar' and 'baz' as checked/unchecked options; unchecked
echo $this-> formCheckbox('foo', 'baz', null, array('bar', 'baz'));
echo $this-> formCheckbox('foo',
null,
array('checked' => false),
In all cases, the markup prepends a hidden element with the
unchecked value; this way, if the value is unchecked, you
will still get a valid value returned to your form.
-
formErrors($errors, $options): Generates an
XHTML unordered list to show errors.
$errors should be a string or an array of strings;
$options should be any attributes you want
placed in the opening list tag.
You can specify alternate opening, closing, and separator
content when rendering the errors by calling several methods
on the helper:
-
setElementStart($string); default is
'<ul class="errors"%s"><li>', where %s
is replaced with the attributes as specified in
$options.
-
setElementSeparator($string); default
is '</li><li>'.
-
setElementEnd($string); default is
'</li></ul>'.
-
formFile($name, $attribs): Creates an
<input type="file" /> element.
-
formHidden($name, $value, $attribs): Creates an
<input type="hidden" /> element.
-
formLabel($name, $value, $attribs): Creates a
<label> element, setting the for attribute to
$name, and the actual label text to
$value. If disable is passed in
attribs, nothing will be returned.
-
formMultiCheckbox($name, $value, $attribs, $options,
$listsep): Creates a list of checkboxes.
$options should be an associative array, and may be
arbitrarily deep. $value may be a single value or
an array of selected values that match the keys in the
$options array. $listsep is an
HTML break ("<br />") by default. By default, this
element is treated as an array; all checkboxes share the same name, and are
submitted as an array.
-
formPassword($name, $value, $attribs): Creates an
<input type="password" /> element.
-
formRadio($name, $value, $attribs, $options):
Creates a series of <input type="radio" /> elements, one
for each of the $options elements. In the $options array, the
element key is the radio value, and the element value is the
radio label. The $value radio will be preselected for you.
-
formReset($name, $value, $attribs): Creates an
<input type="reset" /> element.
-
formSelect($name, $value, $attribs, $options):
Creates a <select>...</select> block, with one
<option>one for each of the $options elements. In the
$options array, the element key is the option value, and the
element value is the option label. The $value option(s) will be
preselected for you.
-
formSubmit($name, $value, $attribs): Creates an
<input type="submit" /> element.
-
formText($name, $value, $attribs): Creates an
<input type="text" /> element.
-
formTextarea($name, $value, $attribs): Creates a
<textarea>...</textarea> block.
-
url($urlOptions, $name, $reset): Creates a
URL string based on a named route.
$urlOptions should be an associative array of key/value pairs
used by the particular route.
-
htmlList($items, $ordered, $attribs, $escape):
generates unordered and ordered lists based on the $items
passed to it. If $items is a multidimensional
array, a nested list will be built. If the $escape
flag is TRUE (default), individual items will be escaped
using the view objects registered escaping mechanisms; pass a
FALSE value if you want to allow markup in your lists.
Using these in your view scripts is very easy, here is an example.
Note that you all you need to do is call them; they will load
and instantiate themselves as they are needed.
// inside your view script, $this refers to the Zend_View instance.
//
// say that you have already assigned a series of select options under
// the name $countries as array('us' => 'United States', 'il' =>
// 'Israel', 'de' => 'Germany').
?>
<form action="action.php" method="post">
<p><label>Your Email:
<?php echo $this-> formText('email', 'you@example.com', array('size' => 32)) ?>
</label></p>
<p><label>Your Country:
<?php echo $this-> formSelect('country', 'us', null, $this-> countries) ?>
</label></p>
<p><label>Would you like to opt in?
<?php echo $this-> formCheckbox('opt_in', 'yes', null, array('yes', 'no')) ?>
</label></p>
</form>
The resulting output from the view script will look something like this:
<form action="action.php" method="post">
<p><label>Your Email:
<input type="text" name="email" value="you@example.com" size="32" />
</label></p>
<p><label>Your Country:
<select name="country">
<option value="us" selected="selected">United States</option>
<option value="il">Israel</option>
<option value="de">Germany</option>
</select>
</label></p>
<p><label>Would you like to opt in?
<input type="hidden" name="opt_in" value="no" />
<input type="checkbox" name="opt_in" value="yes" checked="checked" />
</label></p>
</form>
Action View Helper
The Action view helper enables view scripts to dispatch a
given controller action; the result of the response object following the
dispatch is then returned. These can be used when a particular action
could generate re-usable content or "widget-ized" content.
Actions that result in a _forward() or redirect are
considered invalid, and will return an empty string.
The API for the Action view helper follows that of
most MVC components that invoke controller actions:
action($action, $controller, $module = null, array $params = array()).
$action and $controller are required; if no
module is specified, the default module is assumed.
Example #1 Basic Usage of Action View Helper
As an example, you may have a CommentController with a
listAction() method you wish to invoke in order to pull
a list of comments for the current request:
<div id="sidebar right">
<div class="item">
<?php echo $this-> action('list',
'comment',
null,
array('count' => 10)); ?>
</div>
</div>
BaseUrl Helper
While most URLs generated by the framework have the base
URL prepended automatically, developers will need to prepend the
base URL to their own URLs in order for paths
to resources to be correct.
Usage of the BaseUrl helper is very straightforward:
/*
* The following assume that the base URL of the page/application is "/mypage".
*/
/*
* Prints:
* <base href="/mypage/" />
*/
<base href="<?php echo $this->baseUrl(); ?>" />
/*
* Prints:
* <link rel="stylesheet" type="text/css" href="/mypage/css/base.css" />
*/
<link rel="stylesheet" type="text/css"
href="<?php echo $this->baseUrl('css/base.css'); ?>" />
Note:
For simplicity's sake, we strip out the entry PHP file (e.g.,
"index.php") from the base URL that was
contained in Zend_Controller. However, in some situations
this may cause a problem. If one occurs, use
$this->getHelper('BaseUrl')->setBaseUrl() to set your
own BaseUrl.
Currency Helper
Displaying localized currency values is a common task; the
Zend_Currency view helper is intended to simply this task. See the
Zend_Currency documentation for specifics
on this localization feature. In this section, we will focus simply on usage of the view
helper.
There are several ways to initiate the Currency view helper:
-
Registered, through a previously registered instance in
Zend_Registry.
-
Afterwards, through the fluent interface.
-
Directly, through instantiating the class.
A registered instance of Zend_Currency is the preferred usage for
this helper. Doing so, you can select the currency to be used prior to adding the adapter to
the registry.
There are several ways to select the desired currency. First, you may simply provide a
currency string; alternately, you may specify a locale. The preferred way is to use a
locale as this information is automatically detected and selected via the
HTTP client headers provided when a user accesses your application, and
ensures the currency provided will match their locale.
Note:
We are speaking of "locales" instead of "languages" because a language may vary based on
the geographical region in which it is used. For example, English is spoken in different
dialects: British English, American English, etc. As a currency always correlates to a
country you must give a fully-qualified locale, which means providing both the language
and region. Therefore, we say "locale" instead of "language."
Example #2 Registered instance
To use a registered instance, simply create an instance of
Zend_Currency and register it within
Zend_Registry using Zend_Currency as its
key.
// our example currency
$currency = new Zend_Currency('de_AT');
Zend_Registry::set('Zend_Currency', $currency);
// within your view
echo $this-> currency(1234.56);
// this returns '€ 1.234,56'
If you are more familiar with the fluent interface, then you can also create an instance
within your view and configure the helper afterwards.
Example #3 Within the view
To use the fluent interface, create an instance of Zend_Currency,
call the helper without a parameter, and call the setCurrency()
method.
// within your view
$currency = new Zend_Currency('de_AT');
$this->currency()->setCurrency($currency)->currency(1234.56);
// this returns '€ 1.234,56'
If you are using the helper without Zend_View then you can
also use it directly.
// our example currency
$currency = new Zend_Currency('de_AT');
// initiate the helper
$helper = new Zend_View_Helper_Currency($currency);
echo $helper-> currency(1234.56); // this returns '€ 1.234,56'
As already seen, the currency() method is used to return the
currency string. Just call it with the value you want to display as a currency. It also
accepts some options which may be used to change the behaviour and output of the helper.
// our example currency
$currency = new Zend_Currency('de_AT');
// initiate the helper
$helper = new Zend_View_Helper_Currency($currency);
echo $helper-> currency(1234.56); // this returns '€ 1.234,56'
echo $helper-> currency(1234.56, array('precision' => 1));
// this returns '€ 1.234,6'
For details about the available options, search for Zend_Currency's
toCurrency() method.
Cycle Helper
The Cycle helper is used to alternate a set of values.
Example #6 Cycle Helper Basic Usage
To add elements to cycle just specify them in constructor
or use assign(array $data) function
<?php foreach ($this->books as $book):?>
<tr style="background-color:<?php echo $this->cycle(array("#F0F0F0",
"#FFFFFF"))
->next()?>">
<td><?php echo $this->escape($book['author']) ?></td>
</tr>
<?php endforeach;?>
// Moving in backwards order and assign function
$this->cycle()->assign(array("#F0F0F0","#FFFFFF"));
$this->cycle()->prev();
?>
<tr style="background-color:'#F0F0F0'">
<td>First</td>
</tr>
<tr style="background-color:'#FFFFFF'">
<td>Second</td>
</tr>
Example #7 Working with two or more cycles
To use two cycles you have to specify the names of cycles. Just set second parameter in
cycle method. $this->cycle(array("#F0F0F0","#FFFFFF"),'cycle2'). You
can also use setName($name) function.
<?php foreach ($this->books as $book):?>
<tr style="background-color:<?php echo $this->cycle(array("#F0F0F0",
"#FFFFFF"))
->next()?>">
<td><?php echo $this->cycle(array(1,2,3),'number')->next()?></td>
<td><?php echo $this->escape($book['author'])?></td>
</tr>
<?php endforeach;?>
Partial Helper
The Partial view helper is used to render a specified
template within its own variable scope. The primary use is for reusable
template fragments with which you do not need to worry about variable
name clashes. Additionally, they allow you to specify partial view
scripts from specific modules.
A sibling to the Partial, the PartialLoop view
helper allows you to pass iterable data, and render a partial for each
item.
Note: PartialLoop Counter
The PartialLoop view helper assigns a variable to the view named
partialCounter which passes the current position of the array to
the view script. This provides an easy way to have alternating colors on table rows for
example.
Example #8 Basic Usage of Partials
Basic usage of partials is to render a template fragment in its own
view scope. Consider the following partial script:
<?php // partial.phtml ?>
<ul>
<li>From: <?php echo $this-> escape($this-> from) ?></li>
<li>Subject: <?php echo $this-> escape($this-> subject) ?></li>
</ul>
You would then call it from your view script using the following:
<?php echo $this-> partial('partial.phtml', array(
'from' => 'Team Framework',
'subject' => 'view partials')); ?>
<ul>
<li>From: Team Framework</li>
<li>Subject: view partials</li>
</ul>
Note: What is a model?
A model used with the Partial view helper can be
one of the following:
-
Array. If an array is passed, it
should be associative, as its key/value pairs are
assigned to the view with keys as view variables.
-
Object implementing toArray() method. If an object is
passed an has a toArray() method, the results of
toArray() will be assigned to the view
object as view variables.
-
Standard object. Any other object
will assign the results of
object_get_vars() (essentially all public
properties of the object) to the view object.
If your model is an object, you may want to have it passed
as an object to the partial script, instead
of serializing it to an array of variables. You can do this by
setting the 'objectKey' property of the appropriate helper:
// Tell partial to pass objects as 'model' variable
$view->partial()->setObjectKey('model');
// Tell partial to pass objects from partialLoop as 'model' variable
// in final partial view script:
$view->partialLoop()->setObjectKey('model');
This technique is particularly useful when passing
Zend_Db_Table_Rowsets to
partialLoop(), as you then have full access to your
row objects within the view scripts, allowing you to call
methods on them (such as retrieving values from parent or
dependent rows).
Example #9 Using PartialLoop to Render Iterable Models
Typically, you'll want to use partials in a loop, to render the same
content fragment many times; this way you can put large blocks of
repeated content or complex display logic into a single location.
However this has a performance impact, as the partial helper needs
to be invoked once for each iteration.
The PartialLoop view helper helps solve this issue. It
allows you to pass an iterable item (array or object implementing
Iterator) as the model. It then iterates over this,
passing, the items to the partial script as the model. Items in the
iterator may be any model the Partial view helper
allows.
Let's assume the following partial view script:
<?php // partialLoop.phtml ?>
<dt><?php echo $this-> key ?></dt>
<dd><?php echo $this-> value ?></dd>
And the following "model":
array('key' => 'Mammal', 'value' => 'Camel'),
array('key' => 'Bird', 'value' => 'Penguin'),
array('key' => 'Reptile', 'value' => 'Asp'),
array('key' => 'Fish', 'value' => 'Flounder'),
);
In your view script, you could then invoke the
PartialLoop helper:
<dl>
<?php echo $this-> partialLoop('partialLoop.phtml', $model) ?>
</dl>
<dl>
<dt>Mammal</dt>
<dd>Camel</dd>
<dt>Bird</dt>
<dd>Penguin</dd>
<dt>Reptile</dt>
<dd>Asp</dd>
<dt>Fish</dt>
<dd>Flounder</dd>
</dl>
Example #10 Rendering Partials in Other Modules
Sometime a partial will exist in a different module. If you know the
name of the module, you can pass it as the second argument to either
partial() or partialLoop(), moving the
$model argument to third position.
For instance, if there's a pager partial you wish to use that's in
the 'list' module, you could grab it as follows:
<?php echo $this-> partial('pager.phtml', 'list', $pagerData) ?>
In this way, you can re-use partials created specifically for other
modules. That said, it's likely a better practice to put re-usable
partials in shared view script paths.
Placeholder Helper
The Placeholder view helper is used to persist content
between view scripts and view instances. It also offers some useful
features such as aggregating content, capturing view script content
for later use, and adding pre- and post-text to content (and custom
separators for aggregated content).
Example #11 Basic Usage of Placeholders
Basic usage of placeholders is to persist view data. Each invocation
of the Placeholder helper expects a placeholder name;
the helper then returns a placeholder container object that you can
either manipulate or simply echo out.
<?php $this->placeholder('foo')->set("Some text for later") ?>
<?php
echo $this-> placeholder('foo');
// outputs "Some text for later"
?>
Example #12 Using Placeholders to Aggregate Content
Aggregating content via placeholders can be useful at times as well.
For instance, your view script may have a variable array from which
you wish to retrieve messages to display later; a later view script
can then determine how those will be rendered.
The Placeholder view helper uses containers that extend
ArrayObject, providing a rich featureset for
manipulating arrays. In addition, it offers a variety of methods for
formatting the content stored in the container:
-
setPrefix($prefix) sets text with which to
prefix the content. Use getPrefix() at any time
to determine what the current setting is.
-
setPostfix($prefix) sets text with which to
append the content. Use getPostfix() at any time
to determine what the current setting is.
-
setSeparator($prefix) sets text with which to
separate aggregated content. Use getSeparator()
at any time to determine what the current setting is.
-
setIndent($prefix) can be used to set an
indentation value for content. If an integer is passed,
that number of spaces will be used; if a string is passed,
the string will be used. Use getIndent()
at any time to determine what the current setting is.
<!-- first view script -->
<?php $this->placeholder('foo')->exchangeArray($this->data) ?>
<!-- later view script -->
<?php
$this->placeholder('foo')->setPrefix("<ul>\n <li>")
->setSeparator("</li><li>\n")
->setIndent(4)
->setPostfix("</li></ul>\n");
?>
<?php
echo $this-> placeholder('foo');
// outputs as unordered list with pretty indentation
?>
Because the Placeholder container objects extend
ArrayObject, you can also assign content to a specific
key in the container easily, instead of simply pushing it into the
container. Keys may be accessed either as object properties or as
array keys.
<?php $this->placeholder('foo')->bar = $this->data ?>
<?php echo $this-> placeholder('foo')-> bar ?>
<?php
$foo = $this->placeholder('foo');
?>
Example #13 Using Placeholders to Capture Content
Occasionally you may have content for a placeholder in a view script
that is easiest to template; the Placeholder view
helper allows you to capture arbitrary content for later rendering
using the following API.
-
captureStart($type, $key) begins capturing
content.
$type should be one of the
Placeholder constants APPEND or
SET. If APPEND, captured content
is appended to the list of current content in the
placeholder; if SET, captured content is used
as the sole value of the placeholder (potentially replacing
any previous content). By default, $type is
APPEND.
$key can be used to specify a specific key in
the placeholder container to which you want content
captured.
captureStart() locks capturing until
captureEnd() is called; you cannot nest
capturing with the same placeholder container. Doing so will
raise an exception.
-
captureEnd() stops capturing content, and
places it in the container object according to how
captureStart() was called.
<!-- Default capture: append -->
<?php $this->placeholder('foo')->captureStart();
foreach ($this->data as $datum): ?>
<div class="foo">
<h2><?php echo $datum-> title ?></h2>
<p><?php echo $datum-> content ?></p>
</div>
<?php endforeach; ?>
<?php $this->placeholder('foo')->captureEnd() ?>
<?php echo $this-> placeholder('foo') ?>
<?php $this->placeholder('foo')->captureStart('SET', 'data');
foreach ($this->data as $datum): ?>
<div class="foo">
<h2><?php echo $datum-> title ?></h2>
<p><?php echo $datum-> content ?></p>
</div>
<?php endforeach; ?>
<?php $this->placeholder('foo')->captureEnd() ?>
<?php echo $this-> placeholder('foo')-> data ?>
Concrete Placeholder Implementations
Zend Framework ships with a number of "concrete" placeholder
implementations. These are for commonly used placeholders: doctype,
page title, and various <head> elements. In all cases, calling
the placeholder with no arguments returns the element itself.
Documentation for each element is covered separately, as linked
below:
Doctype Helper
Valid HTML and XHTML documents should include a
DOCTYPE declaration. Besides being difficult to remember, these can
also affect how certain elements in your document should be rendered (for instance,
CDATA escaping in <script> and
<style> elements.
The Doctype helper allows you to specify one of the
following types:
XHTML11
XHTML1_STRICT
XHTML1_TRANSITIONAL
XHTML1_FRAMESET
XHTML1_RDFA
XHTML_BASIC1
HTML4_STRICT
HTML4_LOOSE
HTML4_FRAMESET
HTML5
You can also specify a custom doctype as long as it is well-formed.
The Doctype helper is a concrete implementation of the
Placeholder helper.
Example #14 Doctype Helper Basic Usage
You may specify the doctype at any time. However, helpers that
depend on the doctype for their output will recognize it only after
you have set it, so the easiest approach is to specify it in your
bootstrap:
$doctypeHelper = new Zend_View_Helper_Doctype();
$doctypeHelper->doctype('XHTML1_STRICT');
And then print it out on top of your layout script:
<?php echo $this-> doctype() ?>
Example #15 Retrieving the Doctype
If you need to know the doctype, you can do so by calling
getDoctype() on the object, which is returned by
invoking the helper.
$doctype = $view->doctype()->getDoctype();
Typically, you'll simply want to know if the doctype is XHTML or
not; for this, the isXhtml() method will suffice:
if ($view->doctype()->isXhtml()) {
// do something differently
}
You can also check if the doctype represents an HTML5 document.
if ($view->doctype()->isHtml5()) {
// do something differently
}
Example #16 Choosing a Doctype to Use with the Open Graph Protocol
If you would like to implement the »
Open Graph Protocol, it is best to specify the XHTML1_RDFA doctype.
This doctype allows a developer to use the »
Resource Description Framework within an XHTML document.
$doctypeHelper = new Zend_View_Helper_Doctype();
$doctypeHelper->doctype('XHTML1_RDFA');
It is not required to use the XHTML1_RDFA doctype to enable the Open Graph Protocol, but it is required to enable the namespaces inside the html tag:
<?php echo $this->doctype() ?>
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:og="http://opengraphprotocol.org/schema/" xmlns:fb="http://www.facebook.com/2008/fbml">
In the above example, we specifed two namespaces in the html tag. One for the Open Graph and another for »
Facebook Open Graph.
Here is how to specify a meta tag with a property:
<meta property="og:type" content="musician" />
We set the property to og:type. The og references the Open Graph namespace we specified in the html tag. The content identifies the page as being about a musician.
Here is who you check if the doctype includes RFDa in the document.
<?php echo $this-> doctype() ?>
<?php if ($view->doctype()->isRdfa()): ?>
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:og="http://opengraphprotocol.org/schema/" xmlns:fb="http://www.facebook.com/2008/fbml">
<?php else: ?>
<html xmlns="http://www.w3.org/1999/xhtml">
<?php endif; ?>
Gravatar View Helper
The Gravatar view helper is used to received avatars from Gravatar's
service.
Example #17 Basic Usage of Gravatar View Helper
// From a view script (using XHTML DOCTYPE):
echo $this-> gravatar('example@example.com');
/* results in the following output:
<img src="http://www.gravatar.com/avatar/23463b99b62a72f26ed677cc556c44e8?s=80&d=mm&r=g" />
*/
Note:
Of course we can configure this helper. We can change height of image (by default it is
80px), and add CSS class or other attributes to image tag. The above
simply shows the most basic usage.
WarningUse a valid email address!
The email address you provide the helper should be valid. This class does not validate
the address (only the rating parameter). It is recommended to validate your email
address within your model layer.
Example #18 Advanced Usage of Gravatar View Helper
There are several ways to configure the returned gravatar. In most cases, you may either
pass an array of options as a second argument to the helper, or call methods on the
returned object in order to configure it.
-
The img_size option can be used to specify an alternate
height; alternately, call setImgSize().
-
The secure option can be used to force usage of SSL in
the returned image URI by passing a boolean true value (or
disabling SSL usage by passing false). Alternately, call
the setSecure() method. (By default, the setting
follows the same security as the current page request.)
-
To add attributes to the image, pass an array of key/value pairs as the
third argument to the helper, or call the
setAttribs() method.
// Within the view script (using HTML DOCTYPE)
echo $this-> gravatar('example@example.com',
array('imgSize' => 90, 'defaultImg' => 'monsterid', 'secure' => true),
array('class' => 'avatar', 'title' => 'Title for this image')
);
// Or use mutator methods
$this->gravatar()
->setEmail('example@example.com')
->setImgSize(90)
->setDefaultImg(Zend_View_Helper_Gravatar::DEFAULT_MONSTERID)
->setSecure(true)
-> setAttribs(array('class' => 'avatar', 'title' => 'Title for this image'));
/* Both generate the following output:
<img class="avatar" title="Title for this image"
src="https://secure.gravatar.com/avatar/23463b99b62a72f26ed677cc556c44e8?s=90&d=monsterid&r=g" >
*/
Options
Zend_Service_Gravatar Options
-
- img_size
-
An integer describing the height of the avatar, in pixels; defaults to "80".
-
- default_img
-
Image to return if the gravatar service is unable to match the email address
provided. Defaults to "mm", the "mystery man" image.
-
- rating
-
Audience rating to confine returned images to. Defaults to "g"; may be one
of "g", "pg", "r", or "x", in order of least offensive to most offensive.
-
- secure
-
Whether or not to load the image via an SSL connection. Defaults to the what
is detected from the current request.
HeadLink Helper
The HTML <link> element is increasingly used
for linking a variety of resources for your site: stylesheets, feeds,
favicons, trackbacks, and more. The HeadLink helper
provides a simple interface for creating and aggregating these elements
for later retrieval and output in your layout script.
The HeadLink helper has special methods for adding
stylesheet links to its stack:
-
appendStylesheet($href, $media, $conditionalStylesheet, $extras)
-
offsetSetStylesheet($index, $href, $media, $conditionalStylesheet,
$extras)
-
prependStylesheet($href, $media, $conditionalStylesheet, $extras)
-
setStylesheet($href, $media, $conditionalStylesheet, $extras)
The $media value defaults to 'screen', but may be any valid
media value. $conditionalStylesheet is a string or boolean
FALSE, and will be used at rendering time to determine if special
comments should be included to prevent loading of the stylesheet on certain platforms.
$extras is an array of any extra values that you want to be added
to the tag.
Additionally, the HeadLink helper has special methods for
adding 'alternate' links to its stack:
-
appendAlternate($href, $type, $title, $extras)
-
offsetSetAlternate($index, $href, $type, $title, $extras)
-
prependAlternate($href, $type, $title, $extras)
-
setAlternate($href, $type, $title, $extras)
The headLink() helper method allows specifying all
attributes necessary for a <link> element, and allows
you to also specify placement -- whether the new element replaces all
others, prepends (top of stack), or appends (end of stack).
The HeadLink helper is a concrete implementation of the
Placeholder
helper.
Example #19 HeadLink Helper Basic Usage
You may specify a headLink at any time. Typically, you
will specify global links in your layout script, and application
specific links in your application view scripts. In your layout
script, in the <head> section, you will then echo the helper
to output it.
<?php // setting links in a view script:
$this->headLink()->appendStylesheet('/styles/basic.css')
-> headLink(array('rel' => 'favicon',
'href' => '/img/favicon.ico'),
'PREPEND')
->prependStylesheet('/styles/moz.css',
'screen',
true,
array('id' => 'my_stylesheet'));
?>
<?php // rendering the links: ?>
<?php echo $this-> headLink() ?>
HeadScript Helper
The HTML <script> element is used to either
provide inline client-side scripting elements or link to a remote resource
containing client-side scripting code. The HeadScript
helper allows you to manage both.
The HeadScript helper supports the following methods for
setting and adding scripts:
-
appendFile($src, $type = 'text/javascript', $attrs = array())
-
offsetSetFile($index, $src, $type = 'text/javascript', $attrs =
array())
-
prependFile($src, $type = 'text/javascript', $attrs = array())
-
setFile($src, $type = 'text/javascript', $attrs = array())
-
appendScript($script, $type = 'text/javascript', $attrs =
array())
-
offsetSetScript($index, $script, $type = 'text/javascript', $attrs =
array())
-
prependScript($script, $type = 'text/javascript', $attrs =
array())
-
setScript($script, $type = 'text/javascript', $attrs = array())
In the case of the * File() methods, $src is
the remote location of the script to load; this is usually in the form
of a URL or a path. For the * Script() methods,
$script is the client-side scripting directives you wish to
use in the element.
Note: Setting Conditional Comments
HeadScript allows you to wrap the script tag in conditional
comments, which allows you to hide it from specific browsers. To add the conditional
tags, pass the conditional value as part of the $attrs parameter in
the method calls.
Example #21 Headscript With Conditional Comments
// adding scripts
$this->headScript()->appendFile(
'/js/prototype.js',
'text/javascript',
array('conditional' => 'lt IE 7')
);
HeadScript also allows capturing scripts; this can be
useful if you want to create the client-side script programmatically,
and then place it elsewhere. The usage for this will be showed in an
example below.
Finally, you can also use the headScript() method to
quickly add script elements; the signature for this is
headScript($mode = 'FILE', $spec, $placement = 'APPEND').
The $mode is either 'FILE' or 'SCRIPT', depending on if
you're linking a script or defining one. $spec is either
the script file to link or the script source itself.
$placement should be either 'APPEND', 'PREPEND', or 'SET'.
HeadScript overrides each of append(),
offsetSet(), prepend(), and
set() to enforce usage of the special methods as listed above.
Internally, it stores each item as a stdClass token, which it later
serializes using the itemToString() method. This allows you
to perform checks on the items in the stack, and optionally modify these
items by simply modifying the object returned.
The HeadScript helper is a concrete implementation of the
Placeholder helper.
Note: Use InlineScript for HTML Body Scripts
HeadScript's sibling helper, InlineScript,
should be used when you wish to include scripts inline in the HTML
body. Placing scripts at the end of your document is a
good practice for speeding up delivery of your page, particularly
when using 3rd party analytics scripts.
Note: Arbitrary Attributes are Disabled by Default
By default, HeadScript only will render
<script> attributes that are blessed by the W3C.
These include 'type', 'charset', 'defer', 'language', and 'src'.
However, some javascript frameworks, notably » Dojo, utilize custom
attributes in order to modify behavior. To allow such attributes,
you can enable them via the
setAllowArbitraryAttributes() method:
$this->headScript()->setAllowArbitraryAttributes(true);
Example #22 HeadScript Helper Basic Usage
You may specify a new script tag at any time. As noted above, these
may be links to outside resource files or scripts themselves.
// adding scripts
$this->headScript()->appendFile('/js/prototype.js')
->appendScript($onloadScript);
Order is often important with client-side scripting; you may need to
ensure that libraries are loaded in a specific order due to
dependencies each have; use the various append, prepend, and
offsetSet directives to aid in this task:
// Putting scripts in order
// place at a particular offset to ensure loaded last
$this->headScript()->offsetSetFile(100, '/js/myfuncs.js');
// use scriptaculous effects (append uses next index, 101)
$this->headScript()->appendFile('/js/scriptaculous.js');
// but always have base prototype script load first:
$this->headScript()->prependFile('/js/prototype.js');
When you're finally ready to output all scripts in your layout
script, simply echo the helper:
<?php echo $this-> headScript() ?>
Example #23 Capturing Scripts Using the HeadScript Helper
Sometimes you need to generate client-side scripts programmatically.
While you could use string concatenation, heredocs, and the like,
often it's easier just to do so by creating the script and
sprinkling in PHP tags. HeadScript lets you do
just that, capturing it to the stack:
<?php $this->headScript()->captureStart() ?>
var action = '<?php echo $this->baseUrl ?>';
$('foo_form').action = action;
<?php $this->headScript()->captureEnd() ?>
The following assumptions are made:
-
The script will be appended to the stack. If you wish for it
to replace the stack or be added to the top, you will need
to pass 'SET' or 'PREPEND', respectively, as the first
argument to captureStart().
-
The script MIME type is assumed to be 'text/javascript'; if
you wish to specify a different type, you will need to pass it
as the second argument to captureStart().
-
If you wish to specify any additional attributes for the
<script> tag, pass them in an array as
the third argument to captureStart().
HeadStyle Helper
The HTML <style> element is used to include
CSS stylesheets inline in the HTML
<head> element.
Note: Use HeadLink to link CSS files
HeadLink
should be used to create <link> elements for
including external stylesheets. HeadStyle is used when
you wish to define your stylesheets inline.
The HeadStyle helper supports the following methods for
setting and adding stylesheet declarations:
-
appendStyle($content, $attributes = array())
-
offsetSetStyle($index, $content, $attributes = array())
-
prependStyle($content, $attributes = array())
-
setStyle($content, $attributes = array())
In all cases, $content is the actual CSS declarations.
$attributes are any additional attributes you wish to provide to the
style tag: lang, title, media, or dir are all permissible.
Note: Setting Conditional Comments
HeadStyle allows you to wrap the style tag in conditional
comments, which allows you to hide it from specific browsers. To add the conditional
tags, pass the conditional value as part of the $attributes parameter
in the method calls.
Example #24 Headstyle With Conditional Comments
// adding scripts
$this-> headStyle()-> appendStyle($styles, array('conditional' => 'lt IE 7'));
HeadStyle also allows capturing style declarations; this
can be useful if you want to create the declarations programmatically,
and then place them elsewhere. The usage for this will be showed in an
example below.
Finally, you can also use the headStyle() method to
quickly add declarations elements; the signature for this is
headStyle($content$placement = 'APPEND', $attributes = array()).
$placement should be either 'APPEND', 'PREPEND', or 'SET'.
HeadStyle overrides each of append(),
offsetSet(), prepend(), and
set() to enforce usage of the special methods as listed above.
Internally, it stores each item as a stdClass token, which it later
serializes using the itemToString() method. This allows you
to perform checks on the items in the stack, and optionally modify these
items by simply modifying the object returned.
The HeadStyle helper is a concrete implementation of the
Placeholder
helper.
Note: UTF-8 encoding used by default
By default, Zend Framework uses UTF-8 as its default encoding, and,
specific to this case, Zend_View does as well. Character encoding
can be set differently on the view object itself using the
setEncoding() method (or the the encoding
instantiation parameter). However, since Zend_View_Interface does
not define accessors for encoding, it's possible that if you are using a custom view
implementation with this view helper, you will not have a
getEncoding() method, which is what the view helper uses
internally for determining the character set in which to encode.
If you do not want to utilize UTF-8 in such a situation, you will
need to implement a getEncoding() method in your custom view
implementation.
Example #25 HeadStyle Helper Basic Usage
You may specify a new style tag at any time:
// adding styles
$this->headStyle()->appendStyle($styles);
Order is very important with CSS; you may need to ensure that
declarations are loaded in a specific order due to the order of the
cascade; use the various append, prepend, and offsetSet directives
to aid in this task:
// Putting styles in order
// place at a particular offset:
$this->headStyle()->offsetSetStyle(100, $customStyles);
// place at end:
$this->headStyle()->appendStyle($finalStyles);
// place at beginning
$this->headStyle()->prependStyle($firstStyles);
When you're finally ready to output all style declarations in your
layout script, simply echo the helper:
<?php echo $this-> headStyle() ?>
Example #26 Capturing Style Declarations Using the HeadStyle Helper
Sometimes you need to generate CSS style declarations
programmatically. While you could use string concatenation,
heredocs, and the like, often it's easier just to do so by creating
the styles and sprinkling in PHP tags.
HeadStyle lets you do just that, capturing it to the stack:
<?php $this->headStyle()->captureStart() ?>
body {
background-color: <?php echo $this-> bgColor ?>;
}
<?php $this->headStyle()->captureEnd() ?>
The following assumptions are made:
-
The style declarations will be appended to the stack. If you
wish for them to replace the stack or be added to the top,
you will need to pass 'SET' or 'PREPEND', respectively, as
the first argument to captureStart().
-
If you wish to specify any additional attributes for the
<style> tag, pass them in an array as
the second argument to captureStart().
HeadTitle Helper
The HTML <title> element is used to provide a
title for an HTML document. The HeadTitle helper
allows you to programmatically create and store the title for later retrieval and output.
The HeadTitle helper is a concrete implementation of the
Placeholder
helper. It overrides the toString() method to
enforce generating a <title> element, and adds a
headTitle() method for quick and easy setting and
aggregation of title elements. The signature for that method is
headTitle($title, $setType = null); by default, the
value is appended to the stack (aggregating title segments) if left at null, but you may
also specify either 'PREPEND' (place at top of stack) or 'SET'
(overwrite stack).
Since setting the aggregating (attach) order on each call to
headTitle can be cumbersome, you can set a default attach order
by calling setDefaultAttachOrder() which is applied
to all headTitle() calls unless you explicitly
pass a different attach order as the second parameter.
Example #27 HeadTitle Helper Basic Usage
You may specify a title tag at any time. A typical usage would have
you setting title segments for each level of depth in your
application: site, controller, action, and potentially resource.
// setting the controller and action name as title segments:
$request = Zend_Controller_Front::getInstance()->getRequest();
$this->headTitle($request->getActionName())
->headTitle($request->getControllerName());
// setting the site in the title; possibly in the layout script:
$this->headTitle('Zend Framework');
// setting a separator string for segments:
$this->headTitle()->setSeparator(' / ');
When you're finally ready to render the title in your layout
script, simply echo the helper:
<!-- renders <action> / <controller> / Zend Framework -->
<?php echo $this-> headTitle() ?>
HTML Object Helpers
The HTML
<object> element is used for embedding
media like Flash or QuickTime in web pages. The object view helpers take
care of embedding media with minimum effort.
There are four initial Object helpers:
-
htmlFlash()
Generates markup for embedding Flash files.
-
htmlObject()
Generates markup for embedding a custom Object.
-
htmlPage()
Generates markup for embedding other (X)HTML pages.
-
htmlQuicktime()
Generates markup for embedding QuickTime files.
All of these helpers share a similar interface. For this reason, this
documentation will only contain examples of two of these helpers.
Embedding Flash in your page using the helper is pretty straight-forward.
The only required argument is the resource URI.
<?php echo $this-> htmlFlash('/path/to/flash.swf'); ?>
This outputs the following HTML:
<object data="/path/to/flash.swf"
type="application/x-shockwave-flash"
classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab">
</object>
Additionally you can specify attributes, parameters and content that can
be rendered along with the
<object>. This will
be demonstrated using the htmlObject() helper.
Example #29 Customizing the object by passing additional arguments
The first argument in the object helpers is always required. It is
the URI to the resource you want to embed. The second argument is
only required in the htmlObject() helper. The other helpers
already contain the correct value for this argument. The third
argument is used for passing along attributes to the object element.
It only accepts an array with key-value pairs. classid
and codebase are examples of such attributes. The fourth
argument also only takes a key-value array and uses them to create
<param> elements. You will see an example
of this shortly. Lastly, there is the option of providing additional
content to the object. Now for an example which utilizes all arguments.
'/path/to/file.ext',
'mime/type',
'attr1' => 'aval1',
'attr2' => 'aval2'
),
'param1' => 'pval1',
'param2' => 'pval2'
),
'some content'
);
/*
This would output:
<object data="/path/to/file.ext" type="mime/type"
attr1="aval1" attr2="aval2">
<param name="param1" value="pval1" />
<param name="param2" value="pval2" />
some content
</object>
*/
InlineScript Helper
The HTML <script> element is used to either
provide inline client-side scripting elements or link to a remote resource
containing client-side scripting code. The InlineScript
helper allows you to manage both. It is derived from HeadScript,
and any method of that helper is available; however, use the
inlineScript() method in place of
headScript().
Note: Use InlineScript for HTML Body Scripts
InlineScript, should be used when you wish to include
scripts inline in the HTML body. Placing scripts
at the end of your document is a good practice for speeding up delivery of
your page, particularly when using 3rd party analytics scripts.
Some JS libraries need to be included in the HTML
head; use HeadScript for those scripts.
JSON Helper
When creating views that return JSON, it's important to also set the
appropriate response header. The JSON view helper does exactly that. In
addition, by default, it disables layouts (if currently enabled), as
layouts generally aren't used with JSON responses.
The JSON helper sets the following header:
Content-Type: application/json
Most AJAX libraries look for this header when parsing responses to
determine how to handle the content.
Usage of the JSON helper is very straightforward:
<?php echo $this-> json($this-> data) ?>
Note: Keeping layouts and enabling encoding using Zend_Json_Expr
Each method in the JSON helper accepts a second, optional argument.
This second argument can be a boolean flag to enable or disable
layouts, or an array of options that will be passed to
Zend_Json::encode() and used internally to encode data.
To keep layouts, the second parameter needs to be boolean
TRUE. When the second parameter is an array, keeping
layouts can be achieved by including a keepLayouts key
with a value of a boolean TRUE.
// Boolean true as second argument enables layouts:
echo $this-> json($this-> data, true);
// Or boolean true as "keepLayouts" key:
echo $this-> json($this-> data, array('keepLayouts' => true));
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 to the enableJsonExprFinder key of
the options array:
'enableJsonExprFinder' => true,
'keepLayouts' => true,
)) ?>
Navigation Helpers
The navigation helpers are used for rendering navigational elements
from Zend_Navigation_Container
instances.
There are 5 built-in helpers:
-
Breadcrumbs,
used for rendering the path to the currently active page.
-
Links,
used for rendering navigational head links (e.g.
<link rel="next" href="..." />)
-
Menu,
used for rendering menus.
-
Sitemap,
used for rendering sitemaps conforming to the » Sitemaps XML
format.
-
Navigation,
used for proxying calls to other navigational helpers.
All built-in helpers extend
Zend_View_Helper_Navigation_HelperAbstract, which
adds integration with ACL and
translation. The abstract class
implements the interface
Zend_View_Helper_Navigation_Helper, which
defines the following methods:
-
getContainer() and setContainer()
gets and sets the navigation container the helper should operate on by default, and
hasContainer() checks if the helper
has container registered.
-
getTranslator() and
setTranslator() gets and sets the
translator used for translating labels and titles.
getUseTranslator() and
setUseTranslator() controls whether
the translator should be enabled. The method
hasTranslator() checks if the helper has
a translator registered.
-
getAcl(), setAcl(),
getRole() and setRole(),
gets and sets ACL (Zend_Acl) instance and
role ( String or
Zend_Acl_Role_Interface) used for
filtering out pages when rendering. getUseAcl() and
setUseAcl() controls whether ACL should
be enabled. The methods hasAcl() and
hasRole() checks if the helper has an
ACL instance or a role registered.
-
__toString(), magic method to ensure that
helpers can be rendered by echoing the helper instance directly.
-
render(), must be implemented by concrete
helpers to do the actual rendering.
In addition to the method stubs from the interface, the abstract
class also implements the following methods:
-
getIndent() and setIndent()
gets and sets indentation. The setter accepts a String or an
Integer . In the case of an Integer , the helper will use
the given number of spaces for indentation. I.e.,
setIndent(4) means 4 initial spaces of
indentation. Indentation can be specified for all helpers
except the Sitemap helper.
-
getMinDepth() and setMinDepth()
gets and sets the minimum depth a page must have to be included by the helper.
Setting NULL means no minimum depth.
-
getMaxDepth() and setMaxDepth()
gets and sets the maximum depth a page can have to be included by the helper.
Setting NULL means no maximum depth.
-
getRenderInvisible() and
setRenderInvisible() gets and sets whether to
render items that have been marked as invisible or not.
-
__call() is used for proxying calls to the
container registered in the helper, which means you can
call methods on a helper as if it was a container. See example
below.
-
findActive($container, $minDepth, $maxDepth)
is used for finding the deepest active page in the given
container. If depths are not given, the method will use
the values retrieved from getMinDepth() and
getMaxDepth(). The deepest active page must
be between $minDepth and $maxDepth
inclusively. Returns an array containing a reference to the
found page instance and the depth at which the page was
found.
-
htmlify() renders an 'a'
HTML element from a Zend_Navigation_Page
instance.
-
accept() is used for determining if a page
should be accepted when iterating containers. This method
checks for page visibility and verifies that the helper's
role is allowed access to the page's resource and privilege.
-
The static method setDefaultAcl() is used for setting
a default ACL object that will be used by helpers.
-
The static method setDefaultRole() is used for setting
a default ACL that will be used by helpers
If a navigation container is not explicitly set in a helper using
$helper->setContainer($nav), the helper will look
for a container instance with the key Zend_Navigation in
the registry.
If a container is not explicitly set or found in the registry, the
helper will create an empty Zend_Navigation
container when calling $helper->getContainer().
Example #30 Proxying calls to the navigation container
Navigation view helpers use the magic method __call()
to proxy method calls to the navigation container that is
registered in the view helper.
$this-> navigation()-> addPage(array(
'type' => 'uri',
'label' => 'New page'));
The call above will add a page to the container in the
Navigation helper.
Translation of labels and titles
The navigation helpers support translation of page labels and titles.
You can set a translator of type Zend_Translate
or Zend_Translate_Adapter in the helper using
$helper->setTranslator($translator), or like with other
I18n-enabled components; by adding the translator to
the registry by using the key
Zend_Translate.
If you want to disable translation, use
$helper->setUseTranslator(false).
The
proxy
helper will inject its own translator to the helper it
proxies to if the proxied helper doesn't already have a translator.
Note:
There is no translation in the sitemap helper, since there
are no page labels or titles involved in an XML sitemap.
Integration with ACL
All navigational view helpers support ACL inherently from the
class Zend_View_Helper_Navigation_HelperAbstract.
A Zend_Acl object can be assigned to
a helper instance with $helper->setAcl($acl) , and role
with $helper->setRole('member') or
$helper->setRole(new Zend_Acl_Role('member')) . If ACL
is used in the helper, the role in the helper must be allowed by
the ACL to access a page's resource and/or have the
page's privilege for the page to be included when
rendering.
If a page is not accepted by ACL, any descendant page will also
be excluded from rendering.
The
proxy
helper will inject its own ACL and role to the helper it
proxies to if the proxied helper doesn't already have any.
The examples below all show how ACL affects rendering.
Navigation setup used in examples
This example shows the setup of a navigation container for a
fictional software company.
Notes on the setup:
-
The domain for the site is www.example.com .
-
Interesting page properties are marked with a comment.
-
Unless otherwise is stated in other examples, the user
is requesting the URL
http://www.example.com/products/server/faq/ ,
which translates to the page labeled FAQ
under Foo Server .
-
The assumed ACL and router setup is shown below the
container setup.
/*
* Navigation container (config/array)
* Each element in the array will be passed to
* Zend_Navigation_Page::factory() when constructing
* the navigation container below.
*/
'label' => 'Home',
'title' => 'Go Home',
'module' => 'default',
'controller' => 'index',
'action' => 'index',
'order' => -100 // make sure home is the first page
),
'label' => 'Special offer this week only!',
'module' => 'store',
'controller' => 'offer',
'action' => 'amazing',
'visible' => false // not visible
),
'label' => 'Products',
'module' => 'products',
'controller' => 'index',
'action' => 'index',
'label' => 'Foo Server',
'module' => 'products',
'controller' => 'server',
'action' => 'index',
'label' => 'FAQ',
'module' => 'products',
'controller' => 'server',
'action' => 'faq',
'canonical' => 'http://www.example.com/?page=faq',
'module' => 'products',
'controller' => 'server',
'action' => 'faq',
'params' => array('format' => 'xml')
)
)
),
'label' => 'Editions',
'module' => 'products',
'controller' => 'server',
'action' => 'editions'
),
'label' => 'System Requirements',
'module' => 'products',
'controller' => 'server',
'action' => 'requirements'
)
)
),
'label' => 'Foo Studio',
'module' => 'products',
'controller' => 'studio',
'action' => 'index',
'label' => 'Customer Stories',
'module' => 'products',
'controller' => 'studio',
'action' => 'customers'
),
'label' => 'Support',
'module' => 'prodcts',
'controller' => 'studio',
'action' => 'support'
)
)
)
)
),
'label' => 'Company',
'title' => 'About us',
'module' => 'company',
'controller' => 'about',
'action' => 'index',
'label' => 'Investor Relations',
'module' => 'company',
'controller' => 'about',
'action' => 'investors'
),
'label' => 'News',
'class' => 'rss', // class
'module' => 'company',
'controller' => 'news',
'action' => 'index',
'label' => 'Press Releases',
'module' => 'company',
'controller' => 'news',
'action' => 'press'
),
'label' => 'Archive',
'route' => 'archive', // route
'module' => 'company',
'controller' => 'news',
'action' => 'archive'
)
)
)
)
),
'label' => 'Community',
'module' => 'community',
'controller' => 'index',
'action' => 'index',
'label' => 'My Account',
'module' => 'community',
'controller' => 'account',
'action' => 'index',
'resource' => 'mvc:community.account' // resource
),
'label' => 'Forums',
'uri' => 'http://forums.example.com/',
'class' => 'external' // class
)
)
),
'label' => 'Administration',
'module' => 'admin',
'controller' => 'index',
'action' => 'index',
'resource' => 'mvc:admin', // resource
'label' => 'Write new article',
'module' => 'admin',
'controller' => 'post',
'aciton' => 'write'
)
)
)
);
// Create container from array
$container = new Zend_Navigation($pages);
// Store the container in the proxy helper:
$view->getHelper('navigation')->setContainer($container);
// ...or simply:
$view->navigation($container);
// ...or store it in the reigstry:
Zend_Registry::set('Zend_Navigation', $container);
In addition to the container above, the following setup is assumed:
// Setup router (default routes and 'archive' route):
$front = Zend_Controller_Front::getInstance();
$router = $front->getRouter();
$router->addDefaultRoutes();
$router->addRoute(
'archive',
new Zend_Controller_Router_Route(
'/archive/:year',
'module' => 'company',
'controller' => 'news',
'action' => 'archive',
'year' => (int ) date('Y') - 1
),
)
);
// Setup ACL:
$acl = new Zend_Acl();
$acl->addRole(new Zend_Acl_Role('member'));
$acl->addRole(new Zend_Acl_Role('admin'));
$acl->add(new Zend_Acl_Resource('mvc:admin'));
$acl->add(new Zend_Acl_Resource('mvc:community.account'));
$acl->allow('member', 'mvc:community.account');
$acl->allow('admin', null);
// Store ACL and role in the proxy helper:
$view->navigation()->setAcl($acl)->setRole('member');
// ...or set default ACL and role statically:
Zend_View_Helper_Navigation_HelperAbstract::setDefaultAcl($acl);
Zend_View_Helper_Navigation_HelperAbstract::setDefaultRole('member');
Breadcrumbs Helper
Breadcrumbs are used for indicating where in a sitemap
a user is currently browsing, and are typically rendered
like this: "You are here: Home > Products > FantasticProduct 1.0".
The breadcrumbs helper follows the guidelines from » Breadcrumbs
Pattern - Yahoo! Design Pattern Library,
and allows simple customization (minimum/maximum depth, indentation,
separator, and whether the last element should be linked), or
rendering using a partial view script.
The Breadcrumbs helper works like this; it finds the deepest active
page in a navigation container, and renders an upwards path to
the root. For MVC pages, the "activeness" of a page is
determined by inspecting the request object, as stated in the
section on Zend_Navigation_Page_Mvc.
The helper sets the minDepth property to 1 by default,
meaning breadcrumbs will not be rendered if the deepest active page
is a root page. If maxDepth is specified, the helper
will stop rendering when at the specified depth (e.g. stop at level
2 even if the deepest active page is on level 3).
Methods in the breadcrumbs helper:
-
{get|set}Separator() gets/sets separator
string that is used between breadcrumbs. Defualt is
' > ' .
-
{get|set}LinkLast() gets/sets whether the
last breadcrumb should be rendered as an anchor or not.
Default is FALSE.
-
{get|set}Partial() gets/sets a partial view
script that should be used for rendering breadcrumbs.
If a partial view script is set, the helper's
render() method will use the
renderPartial() method. If no partial is
set, the renderStraight() method is used.
The helper expects the partial to be a String
or an Array with two elements. If the partial
is a String , it denotes the name of the partial
script to use. If it is an Array , the first
element will be used as the name of the partial view
script, and the second element is the module where the
script is found.
-
renderStraight() is the default render
method.
-
renderPartial() is used for rendering
using a partial view script.
Example #31 Rendering breadcrumbs
This example shows how to render breadcrumbs with default
settings.
In a view script or layout:
<?php echo $this-> navigation()-> breadcrumbs(); ?>
The two calls above take advantage of the magic __toString() method,
and are equivalent to:
<?php echo $this-> navigation()-> breadcrumbs()-> render(); ?>
Output:
<a href="/products">Products</a> > <a href="/products/server">Foo Server</a> > FAQ
Example #32 Specifying indentation
This example shows how to render breadcrumbs with initial
indentation.
Rendering with 8 spaces indentation:
<?php echo $this-> navigation()-> breadcrumbs()-> setIndent(8);?>
Output:
<a href="/products">Products</a> > <a href="/products/server">Foo Server</a> > FAQ
Example #33 Customize breadcrumbs output
This example shows how to customze breadcrumbs output by
specifying various options.
In a view script or layout:
<?php
->breadcrumbs()
->setLinkLast(true) // link last page
->setMaxDepth(1) // stop at level 1
->setSeparator(' ▶' . PHP_EOL); // cool separator with newline
?>
Output:
<a href="/products">Products</a> ▶
<a href="/products/server">Foo Server</a>
/////////////////////////////////////////////////////
Setting minimum depth required to render breadcrumbs:
<?php
$this->navigation()->breadcrumbs()->setMinDepth(10);
echo $this-> navigation()-> breadcrumbs();
?>
Output:
Nothing, because the deepest active page is not at level 10 or deeper.
Example #34 Rendering breadcrumbs using a partial view script
This example shows how to render customized breadcrumbs using
a partial vew script. By calling setPartial(),
you can specify a partial view script that will be used
when calling render(). When a partial is specified,
the renderPartial() method will be called. This
method will find the deepest active page and pass an array
of pages that leads to the active page to the partial view
script.
$partial = ;
echo $this-> navigation()-> breadcrumbs()
-> setPartial(array('breadcrumbs.phtml', 'default'));
Contents of
application/modules/default/views/breadcrumbs.phtml :
Products, Foo Server, FAQ
Links Helper
The links helper is used for rendering HTML LINK
elements. Links are used for describing document relationships
of the currently active page. Read more about links and link
types at » Document
relationships: the LINK element (HTML4 W3C Rec.)
and » Link types (HTML4 W3C
Rec.) in the HTML4 W3C Recommendation.
There are two types of relations; forward and reverse, indicated
by the keyords 'rel' and 'rev' . Most
methods in the helper will take a $rel param, which
must be either 'rel' or 'rev' . Most
methods also take a $type param, which is used
for specifying the link type (e.g. alternate, start, next, prev,
chapter, etc).
Relationships can be added to page objects manually, or found
by traversing the container registered in the helper. The method
findRelation($page, $rel, $type) will first try
to find the given $rel of $type from
the $page by calling $page->findRel($type)
or $page->findRel($type) . If the $page
has a relation that can be converted to a page instance, that
relation will be used. If the $page instance doesn't
have the specified $type, the helper will look for
a method in the helper named search$rel$type (e.g.
searchRelNext() or
searchRevAlternate()).
If such a method exists, it will be used for determining the
$page's relation by traversing the container.
Not all relations can be determined by traversing the container.
These are the relations that will be found by searching:
-
searchRelStart(), forward 'start'
relation: the first page in the container.
-
searchRelNext(), forward 'next'
relation; finds the next page in the container, i.e.
the page after the active page.
-
searchRelPrev(), forward 'prev'
relation; finds the previous page, i.e. the page before
the active page.
-
searchRelChapter(), forward 'chapter'
relations; finds all pages on level 0 except the 'start'
relation or the active page if it's on level 0.
-
searchRelSection(), forward 'section'
relations; finds all child pages of the active page if
the active page is on level 0 (a 'chapter').
-
searchRelSubsection(), forward 'subsection'
relations; finds all child pages of the active page if
the active pages is on level 1 (a 'section').
-
searchRevSection(), reverse 'section'
relation; finds the parent of the active page if the
active page is on level 1 (a 'section').
-
searchRevSubsection(), reverse 'subsection'
relation; finds the parent of the active page if the
active page is on level 2 (a 'subsection').
Note:
When looking for relations in the page instance
($page->getRel($type) or
$page->getRev($type) ), the helper accepts the
values of type String , Array ,
Zend_Config, or
Zend_Navigation_Page. If a string
is found, it will be converted to a
Zend_Navigation_Page_Uri. If an array
or a config is found, it will be converted to one or several
page instances. If the first key of the array/config is numeric,
it will be considered to contain several pages, and each
element will be passed to the
page factory.
If the first key is not numeric, the array/config will be
passed to the page factory directly, and a single page will
be returned.
The helper also supports magic methods for finding relations.
E.g. to find forward alternate relations, call
$helper->findRelAlternate($page) , and to find
reverse section relations, call
$helper->findRevSection($page) . Those calls correspond
to $helper->findRelation($page, 'rel', 'alternate');
and $helper->findRelation($page, 'rev', 'section');
respectively.
To customize which relations should be rendered, the helper
uses a render flag. The render flag is an integer value, and will be
used in a
» bitwse
and (& ) operation against the
helper's render constants to determine if the relation that belongs
to the render constant should be rendered.
See the
example
below for more information.
-
Zend_View_Helper_Navigation_Link::RENDER_ALTERNATE
-
Zend_View_Helper_Navigation_Link::RENDER_STYLESHEET
-
Zend_View_Helper_Navigation_Link::RENDER_START
-
Zend_View_Helper_Navigation_Link::RENDER_NEXT
-
Zend_View_Helper_Navigation_Link::RENDER_PREV
-
Zend_View_Helper_Navigation_Link::RENDER_CONTENTS
-
Zend_View_Helper_Navigation_Link::RENDER_INDEX
-
Zend_View_Helper_Navigation_Link::RENDER_GLOSSARY
-
Zend_View_Helper_Navigation_Link::RENDER_COPYRIGHT
-
Zend_View_Helper_Navigation_Link::RENDER_CHAPTER
-
Zend_View_Helper_Navigation_Link::RENDER_SECTION
-
Zend_View_Helper_Navigation_Link::RENDER_SUBSECTION
-
Zend_View_Helper_Navigation_Link::RENDER_APPENDIX
-
Zend_View_Helper_Navigation_Link::RENDER_HELP
-
Zend_View_Helper_Navigation_Link::RENDER_BOOKMARK
-
Zend_View_Helper_Navigation_Link::RENDER_CUSTOM
-
Zend_View_Helper_Navigation_Link::RENDER_ALL
The constants from RENDER_ALTERNATE to
RENDER_BOOKMARK denote standard HTML link types.
RENDER_CUSTOM denotes non-standard relations that
specified in pages. RENDER_ALL denotes standard and
non-standard relations.
Methods in the links helper:
-
{get|set}RenderFlag() gets/sets the render
flag. Default is RENDER_ALL. See examples
below on how to set the render flag.
-
findAllRelations() finds all relations of
all types for a given page.
-
findRelation() finds all relations of a given
type from a given page.
-
searchRel{Start|Next|Prev|Chapter|Section|Subsection}()
traverses a container to find forward relations to
the start page, the next page, the previous page,
chapters, sections, and subsections.
-
searchRev{Section|Subsection}() traverses
a container to find reverse relations to sections or
subsections.
-
renderLink() renders a single link
element.
Example #35 Specify relations in pages
This example shows how to specify relations in pages.
$container = new Zend_Navigation (array(
'label' => 'Relations using strings',
'alternate' => 'http://www.example.org/'
),
'alternate' => 'http://www.example.net/'
)
),
'label' => 'Relations using arrays',
'label' => 'Example.org',
'uri' => 'http://www.example.org/'
)
)
),
'label' => 'Relations using configs',
'alternate' => new Zend_Config (array(
'label' => 'Example.org',
'uri' => 'http://www.example.org/'
))
)
),
'label' => 'Relations using pages instance',
'alternate' => Zend_Navigation_Page:: factory(array(
'label' => 'Example.org',
'uri' => 'http://www.example.org/'
))
)
)
));
Example #36 Default rendering of links
This example shows how to render a menu from a container
registered/found in the view helper.
In a view script or layout:
<?php echo $this-> view-> navigation()-> links(); ?>
Output:
<link rel="alternate" href="/products/server/faq/format/xml">
<link rel="start" href="/" title="Home">
<link rel="next" href="/products/server/editions" title="Editions">
<link rel="prev" href="/products/server" title="Foo Server">
<link rel="chapter" href="/products" title="Products">
<link rel="chapter" href="/company/about" title="Company">
<link rel="chapter" href="/community" title="Community">
<link rel="canonical" href="http://www.example.com/?page=server-faq">
<link rev="subsection" href="/products/server" title="Foo Server">
Example #37 Specify which relations to render
This example shows how to specify which relations to find
and render.
$helper->setRenderFlag(Zend_View_Helper_Navigation_Links::RENDER_START |
Zend_View_Helper_Navigation_Links::RENDER_NEXT |
Zend_View_Helper_Navigation_Links::RENDER_PREV);
Output:
<link rel="start" href="/" title="Home">
<link rel="next" href="/products/server/editions" title="Editions">
<link rel="prev" href="/products/server" title="Foo Server">
Render only native link types:
$helper->setRenderFlag(Zend_View_Helper_Navigation_Links::RENDER_ALL ^
Zend_View_Helper_Navigation_Links::RENDER_CUSTOM);
Output:
<link rel="alternate" href="/products/server/faq/format/xml">
<link rel="start" href="/" title="Home">
<link rel="next" href="/products/server/editions" title="Editions">
<link rel="prev" href="/products/server" title="Foo Server">
<link rel="chapter" href="/products" title="Products">
<link rel="chapter" href="/company/about" title="Company">
<link rel="chapter" href="/community" title="Community">
<link rev="subsection" href="/products/server" title="Foo Server">
Render all but chapter:
$helper->setRenderFlag(Zend_View_Helper_Navigation_Links::RENDER_ALL ^
Zend_View_Helper_Navigation_Links::RENDER_CHAPTER);
Output:
<link rel="alternate" href="/products/server/faq/format/xml">
<link rel="start" href="/" title="Home">
<link rel="next" href="/products/server/editions" title="Editions">
<link rel="prev" href="/products/server" title="Foo Server">
<link rel="canonical" href="http://www.example.com/?page=server-faq">
<link rev="subsection" href="/products/server" title="Foo Server">
Sitemap Helper
The Sitemap helper is used for generating XML sitemaps, as
defined by the » Sitemaps XML
format. Read more about » Sitemaps on Wikpedia.
By default, the sitemap helper uses
sitemap validators
to validate each element that is rendered. This can be disabled by
calling $helper->setUseSitemapValidators(false) .
Note:
If you disable sitemap validators, the custom properties (see table)
are not validated at all.
The sitemap helper also supports » Sitemap XSD
Schema validation of the generated sitemap. This is disabled by default,
since it will require a request to the Schema file. It can be
enabled with
$helper->setUseSchemaValidation(true) .
Sitemap XML elements
Element |
Description |
loc |
Absolute URL to page. An absolute
URL will be generated by the helper.
|
lastmod |
The date of last modification of the file, in » W3C Datetime
format. This time portion can be omitted if desired, and only use
YYYY-MM-DD.
The helper will try to retrieve the
lastmod value from the page's
custom property lastmod if it
is set in the page. If the value is not a
valid date, it is ignored.
|
changefreq |
How frequently the page is likely to change.
This value provides general information to
search engines and may not correlate exactly
to how often they crawl the page. Valid
values are:
always
hourly
daily
weekly
monthly
yearly
never
The helper will try to retrieve the
changefreq value from the page's
custom property changefreq if it
is set in the page. If the value is not
valid, it is ignored.
|
priority |
The priority of this URL relative to other
URLs on your site. Valid values range from
0.0 to 1.0.
The helper will try to retrieve the
priority value from the page's
custom property priority if it
is set in the page. If the value is not
valid, it is ignored.
|
Methods in the sitemap helper:
-
{get|set}FormatOutput() gets/sets a flag
indicating whether XML output should be formatted. This
corresponds to the formatOutput property
of the native DOMDocument class.
Read more at
» PHP: DOMDocument - Manual.
Default is FALSE.
-
{get|set}UseXmlDeclaration() gets/sets a
flag indicating whether the XML declaration should be
included when rendering. Default is TRUE.
-
{get|set}UseSitemapValidators() gets/sets a
flag indicating whether sitemap validators should be
used when generating the DOM sitemap. Default is
TRUE.
-
{get|set}UseSchemaValidation() gets/sets a
flag indicating whether the helper should use XML Schema
validation when generating the DOM sitemap. Default is
FALSE. If TRUE.
-
{get|set}ServerUrl() gets/sets server URL
that will be prepended to non-absolute URLs in the
url() method. If no server URL is
specified, it will be determined by the helper.
-
url() is used to generate absolute
URLs to pages.
-
getDomSitemap() generates a DOMDocument
from a given container.
Example #48 Rendering an XML sitemap
This example shows how to render an XML sitemap based
on the setup we did further up.
// In a view script or layout:
// format output
$this->navigation()
->sitemap()
->setFormatOutput(true); // default is false
// other possible methods:
// ->setUseXmlDeclaration(false); // default is true
// ->setServerUrl('http://my.otherhost.com');
// default is to detect automatically
// print sitemap
echo $this-> navigation()-> sitemap();
Notice how pages that are invisible or pages with
ACL roles incompatible with the view helper are filtered
out:
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<url>
<loc>http://www.example.com/</loc>
</url>
<url>
<loc>http://www.example.com/products</loc>
</url>
<url>
<loc>http://www.example.com/products/server</loc>
</url>
<url>
<loc>http://www.example.com/products/server/faq</loc>
</url>
<url>
<loc>http://www.example.com/products/server/editions</loc>
</url>
<url>
<loc>http://www.example.com/products/server/requirements</loc>
</url>
<url>
<loc>http://www.example.com/products/studio</loc>
</url>
<url>
<loc>http://www.example.com/products/studio/customers</loc>
</url>
<url>
<loc>http://www.example.com/prodcts/studio/support</loc>
</url>
<url>
<loc>http://www.example.com/company/about</loc>
</url>
<url>
<loc>http://www.example.com/company/about/investors</loc>
</url>
<url>
<loc>http://www.example.com/company/news</loc>
</url>
<url>
<loc>http://www.example.com/company/news/press</loc>
</url>
<url>
<loc>http://www.example.com/archive</loc>
</url>
<url>
<loc>http://www.example.com/community</loc>
</url>
<url>
<loc>http://www.example.com/community/account</loc>
</url>
<url>
<loc>http://forums.example.com/</loc>
</url>
</urlset>
Render the sitemap using no ACL role (should filter out
/community/account):
->sitemap()
->setFormatOutput(true)
->setRole();
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<url>
<loc>http://www.example.com/</loc>
</url>
<url>
<loc>http://www.example.com/products</loc>
</url>
<url>
<loc>http://www.example.com/products/server</loc>
</url>
<url>
<loc>http://www.example.com/products/server/faq</loc>
</url>
<url>
<loc>http://www.example.com/products/server/editions</loc>
</url>
<url>
<loc>http://www.example.com/products/server/requirements</loc>
</url>
<url>
<loc>http://www.example.com/products/studio</loc>
</url>
<url>
<loc>http://www.example.com/products/studio/customers</loc>
</url>
<url>
<loc>http://www.example.com/prodcts/studio/support</loc>
</url>
<url>
<loc>http://www.example.com/company/about</loc>
</url>
<url>
<loc>http://www.example.com/company/about/investors</loc>
</url>
<url>
<loc>http://www.example.com/company/news</loc>
</url>
<url>
<loc>http://www.example.com/company/news/press</loc>
</url>
<url>
<loc>http://www.example.com/archive</loc>
</url>
<url>
<loc>http://www.example.com/community</loc>
</url>
<url>
<loc>http://forums.example.com/</loc>
</url>
</urlset>
Render the sitemap using a maximum depth of 1.
->sitemap()
->setFormatOutput(true)
->setMaxDepth(1);
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<url>
<loc>http://www.example.com/</loc>
</url>
<url>
<loc>http://www.example.com/products</loc>
</url>
<url>
<loc>http://www.example.com/products/server</loc>
</url>
<url>
<loc>http://www.example.com/products/studio</loc>
</url>
<url>
<loc>http://www.example.com/company/about</loc>
</url>
<url>
<loc>http://www.example.com/company/about/investors</loc>
</url>
<url>
<loc>http://www.example.com/company/news</loc>
</url>
<url>
<loc>http://www.example.com/community</loc>
</url>
<url>
<loc>http://www.example.com/community/account</loc>
</url>
<url>
<loc>http://forums.example.com/</loc>
</url>
</urlset>
Note: UTF-8 encoding used by default
By default, Zend Framework uses UTF-8 as its default encoding,
and, specific to this case, Zend_View does as well. Character
encoding can be set differently on the view object itself using the
setEncoding() method (or the the
encoding instantiation parameter). However, since
Zend_View_Interface does not define accessors for encoding,
it's possible that if you are using a custom view implementation with the Dojo view
helper, you will not have a getEncoding() method, which is
what the view helper uses internally for determining the character set in which to
encode.
If you do not want to utilize UTF-8 in such a situation, you will
need to implement a getEncoding() method in your custom
view implementation.
Navigation Helper
The Navigation helper is a proxy helper
that relays calls to other navigational helpers. It can be
considered an entry point to all navigation-related view tasks.
The aforementioned navigational helpers are in the namespace
Zend_View_Helper_Navigation, and would thus require
the path Zend/View/Helper/Navigation to be added as
a helper path to the view. With the proxy helper residing in the
Zend_View_Helper namespace, it will always be
available, without the need to add any helper paths to the view.
The Navigation helper finds other helpers that implement the
Zend_View_Helper_Navigation_Helper
interface, which means custom view helpers can also be proxied.
This would, however, require that the custom helper path is added
to the view.
When proxying to other helpers, the Navigation helper can inject
its container, ACL/role, and translator. This means that you
won't have to explicitly set all three in all navigational
helpers, nor resort to injecting by means of
Zend_Registry or static methods.
-
findHelper() finds the given helper,
verifies that it is a navigational helper, and injects
container, ACL/role and translator.
-
{get|set}InjectContainer() gets/sets a flag
indicating whether the container should be injected to
proxied helpers. Default is TRUE.
-
{get|set}InjectAcl() gets/sets a flag
indicating whether the ACL/role should be injected to
proxied helpers. Default is TRUE.
-
{get|set}InjectTranslator() gets/sets a flag
indicating whether the translator should be injected to
proxied helpers. Default is TRUE.
-
{get|set}DefaultProxy() gets/sets the default
proxy. Default is 'menu' .
-
render() proxies to the render method of
the default proxy.
TinySrc Helper
Overview
» tinysrc.net provides an API for automatic scaling
and image format conversion for use with mobile devices. The API is quite simple: you
simply create a standard HTML image tag, but append your image URL to a URL on the
tinysrc.net domain:
<img src="http://i.tinysrc.net/http://yourdomain.com/images/foo.jpg" />
Their service then sizes the image appropriately for the device requesting it.
You can control a number of aspects regarding image display, including:
-
Image dimensions. You may specify a width and optional
height. These dimensions can be in absolute pixels, or use one of the adaptive
mechanisms tinysrc.net offers. One is subtractive;
prepending a dimension with a minus ("-") indicates that the image should fill
the maximum physical dimensions, minus the value given in
pixels. The other is percentage based; prepending a
dimension with an "x" tells the service to size that dimension by that
percentage -- e.g., "x20" indicates "20%".
-
Image format. By default, tinysrc.net autodiscovers the
format. Internally, it supports only JPEG or
PNG, and autoconverts GIF to
PNG. You can specifically request that it should convert an
image to either PNG or JPEG, however.
The TinySrc view helper provides functionality around the
tinysrc.net API, and gives you the ability to:
-
selectively enable or disable whether it returns just the tinysrc.net URL or a
fully-populated HTML img tag (enabled by default);
-
specify default values for image format as well as width and height;
-
specify a default value for the base URL used (uses the BaseUrl view helper
by default);
-
override the default options on a per-image basis, via passed in options.
Quick Start
The most basic usage is simply to pass the path to an image, relative to your document
root or base URL, to create the appropriate image tag:
<?php echo $this-> tinySrc('/images/foo.png'); ?>
You may specify default values for the base URL, conversion format, dimensions, and
whether or not to create an img tag by default:
<?php $this->tinySrc()
->setBaseUrl('http://example.com/foo/')
->setCreateTag(false) // disable tag creation
->setDefaultFormat('png') // convert images to PNG
->setDefaultDimensions('-5', 'x20'); // width should be 5 less than screen width;
// height should be 20% of total screen height
?>
Finally, you can also pass in values as an array of options, passed as the second
parameter:
<?php echo $this-> tinySrc('/images/foo.png', array(
'format' => 'jpg', // convert to JPEG
'width' => 'x50', // 1/2 screen width
); ?>
Configuration Options
TinySrc Helper Options
The following options may be passed to the $options (second)
argument of the helper.
-
- base_url
-
The base URL, including scheme, host, and optionally port and/or path; this
value will be prepended to the image path provided in the first argument. By
default, this uses the BaseUrl and
ServerUrl view helpers to determine the value.
-
- create_tag
-
A boolean value indicating whether or not the helper should return an HTML
img tag, or simply the tinysrc.net URL. By default, this
flag is enabled.
-
- format
-
Should be one of the values "png" or "jpeg". If specified, this value will
be used to indicate the image conversion format. If not specified, the
default format will be used, or the format will be auto-determined based on
the image itself.
-
- width
-
This should be either null, or an integer (optionally
prefixed by "x" or "-"). If specified, this value will be used to determine
the converted image width. If null, neither a width nor a height value will
be used. If not specified, the default dimensions will be used.
-
- height
-
This should be either null, or an integer (optionally
prefixed by "x" or "-"). If specified, this value will be used to determine
the converted image height. If null, no height value will be used. If not
specified, the default height will be used.
Any other options provided will be used as attributes to the HTML img
tag (if created).
Available Methods
-
-
tinySrc
(
$image = null, array $options = array()
)
-
Called with no arguments, returns the helper instance. This is useful for
configuring the helper.
If the $image argument is provided, it will either create and
return the tinysrc.net URL for the image, or an image tag containing that URL as
the source, depending on the status of the "create tag" flag (either the default
value, or the value passed via $options).
See the configuration
section for details on the $options array.
-
-
setBaseUrl
(
$url
)
-
Use this method to manually specify the base URL to prepend to the
$image argument of the tinySrc()
method.
-
-
getBaseUrl
-
Retrieve the base URL for prepending to image URLs. By default, autodiscovers
this from the BaseUrl and
ServerUrl view helpers.
-
-
setDefaultFormat
(
$format = null
)
-
Specifiy the default image conversion format. If none provided, the value is
cleared. Otherwise, expects either "png" or "jpeg".
-
-
setDefaultDimensions
(
$width = null, $height = null
)
-
Set the default dimensions for image conversion. If no $width
is specified, an empty value is provided for all dimensions (setting the height
requires a width as well). Passing no value for the height will set only a
width. Dimensions should be specified as either pixel dimensions, or:
-
A pixel value, preceded by a "-" sign. This will indicate the width
should take the entire screen size, minus the number of pixels
specified.
-
A percentage of the total screen dimensions, expressed as "x" followed
by the percentage: "x20" is equivalent to 20%.
-
-
setCreateTag
(
$flag
)
-
Indicate whether the tinySrc() method should create an
HTML image tag. If boolean false, only a tinysrc.net URL
will be returned.
-
-
createTag
-
Returns the status of the "create tag" flag.
Examples
Example #49 Returning only a tinysrc.net URL
You may want to return only a tinysrc.net URL. To do this, you have two options:
make this the default behavior, or specify in your $options not
to create a tag.
// Specifying default behavior:
$this->tinySrc()->setCreateTag(false);
echo $this-> tinySrc('image.jpg');
// Per-image:
echo $this-> tinySrc('image.jpg', array('create_tag' => false));
Translate Helper
Often web sites are available in several languages. To translate the
content of a site you should simply use Zend_Translate and to
integrate Zend_Translate within your view you should use
the Translate View Helper.
In all following examples we are using the simple Array Translation
Adapter. Of course you can also use any instance of
Zend_Translate and also any subclasses of
Zend_Translate_Adapter. There are several ways to initiate
the Translate View Helper:
-
Registered, through a previously registered instance in
Zend_Registry
-
Afterwards, through the fluent interface
-
Directly, through initiating the class
A registered instance of Zend_Translate is the preferred
usage for this helper. You can also select the locale to be used simply
before you add the adapter to the registry.
Note:
We are speaking of locales instead of languages because a language
also may contain a region. For example English is spoken in
different dialects. There may be a translation for British and one
for American English. Therefore, we say "locale" instead of
"language."
Example #50 Registered instance
To use a registered instance just create an instance of
Zend_Translate or Zend_Translate_Adapter
and register it within Zend_Registry using
Zend_Translate as its key.
// our example adapter
$adapter = new Zend_Translate(
'adapter' => 'array',
'content' => array('simple' => 'einfach'),
'locale' => 'de'
)
);
Zend_Registry::set('Zend_Translate', $adapter);
// within your view
echo $this-> translate('simple');
// this returns 'einfach'
If you are more familiar with the fluent interface, then you can also
create an instance within your view and initiate the helper afterwards.
Example #51 Within the view
To use the fluent interface, create an instance of
Zend_Translate or Zend_Translate_Adapter,
call the helper without a parameter, and call the
setTranslator() method.
// within your view
$adapter = new Zend_Translate(
'adapter' => 'array',
'content' => array('simple' => 'einfach'),
'locale' => 'de'
)
);
$this->translate()->setTranslator($adapter)->translate('simple');
// this returns 'einfach'
If you are using the helper without Zend_View then you can
also use it directly.
// our example adapter
$adapter = new Zend_Translate(
'adapter' => 'array',
'content' => array('simple' => 'einfach'),
'locale' => 'de'
)
);
// initiate the adapter
$translate = new Zend_View_Helper_Translate($adapter);
print $translate-> translate('simple'); // this returns 'einfach'
You would use this way if you are not working with
Zend_View and need to create translated output.
As already seen, the translate() method is used to return
the translation. Just call it with the needed messageid of your
translation adapter. But it can also replace parameters within the
translation string. Therefore, it accepts variable parameters in two ways:
either as a list of parameters, or as an array of parameters. As examples:
Example #53 Single parameter
To use a single parameter just add it to the method.
// within your view
$date = "Monday";
$this->translate("Today is %1\$s", $date);
// could return 'Heute ist Monday'
Note:
Keep in mind that if you are using parameters which are also text,
you may also need to translate these parameters.
Example #54 List of parameters
Or use a list of parameters and add it to the method.
// within your view
$date = "Monday";
$month = "April";
$time = "11:20:55";
$this->translate("Today is %1\$s in %2\$s. Actual time: %3\$s",
$date,
$month,
$time);
// Could return 'Heute ist Monday in April. Aktuelle Zeit: 11:20:55'
Example #55 Array of parameters
Or use an array of parameters and add it to the method.
// within your view
$date = array("Monday", "April", "11:20:55");
$this->translate("Today is %1\$s in %2\$s. Actual time: %3\$s", $date);
// Could return 'Heute ist Monday in April. Aktuelle Zeit: 11:20:55'
Sometimes it is necessary to change the locale of the translation. This
can be done either dynamically per translation or statically for all
following translations. And you can use it with both a parameter list
and an array of parameters. In both cases the locale must be given as
the last single parameter.
Example #56 Change locale dynamically
// within your view
$date = array("Monday", "April", "11:20:55");
$this->translate("Today is %1\$s in %2\$s. Actual time: %3\$s", $date, 'it');
This example returns the Italian translation for the messageid. But it
will only be used once. The next translation will use the locale from
the adapter. Normally you will set the desired locale within the
translation adapter before you add it to the registry. But you can also
set the locale from within the helper:
Example #57 Change locale statically
// within your view
$date = array("Monday", "April", "11:20:55");
$this->translate()->setLocale('it');
$this->translate("Today is %1\$s in %2\$s. Actual time: %3\$s", $date);
The above example sets 'it' as the new default locale which
will be used for all further translations.
Of course there is also a getLocale() method to get the
currently set locale.
Example #58 Get the currently set locale
// within your view
$date = array("Monday", "April", "11:20:55");
// returns 'de' as set default locale from our above examples
$this->translate()->getLocale();
$this->translate()->setLocale('it');
$this->translate("Today is %1\$s in %2\$s. Actual time: %3\$s", $date);
// returns 'it' as new set default locale
$this->translate()->getLocale();
UserAgent View Helper
Overview
This view helper provides the ability to inject and later retrieve a
Zend_Http_UserAgent instance for use in branching display logic
based on device capabilities.
Quick Start
In most cases, you can simply retrieve the User-Agent and related device by calling the
helper. If the UserAgent was configured in the
bootstrap, that instance will be injected already in the helper; otherwise, it
will instantiate one for you.
<?php if ($this->userAgent()->getDevice()->hasFlash()): ?>
<object ...></object>
<?php endif ?>
If you initialize the UserAgent object manually, you can still
inject it into the helper, in one of two ways.
// Pull the helper from the view, and inject:
$helper = $view->getHelper('userAgent');
$helper->setUserAgent($userAgent);
// Pass the UserAgent to the helper:
$view->userAgent($userAgent);
Available Methods
-
-
userAgent
(
Zend_Http_UserAgent $userAgent = null
)
-
Use this method to set or retrieve the UserAgent
instance. Passing an instance will set it; passing no arguments will retrieve
it. If no previous instance has been registered, one will be lazy-loaded using
defaults.
-
-
setUserAgent
(
Zend_Http_UserAgent $userAgent
)
-
If you have an instance of the helper -- for instance, by calling the view
object's getHelper() method -- you may use this method
to set the UserAgent instance.
-
-
getUserAgent
-
Retrieves the UserAgent instance; if none is registered,
it will lazy-load one using default values.
Helper Paths
As with view scripts, your controller can specify a stack of paths
for Zend_View to search for helper classes. By default,
Zend_View looks in "Zend/View/Helper/*" for helper
classes. You can tell Zend_View to look in other
locations using the setHelperPath() and
addHelperPath() methods. Additionally, you can
indicate a class prefix to use for helpers in the path provided, to
allow namespacing your helper classes. By default, if no class
prefix is provided, 'Zend_View_Helper_' is assumed.
$view = new Zend_View();
// Set path to /path/to/more/helpers, with prefix 'My_View_Helper'
$view->setHelperPath('/path/to/more/helpers', 'My_View_Helper');
In fact, you can "stack" paths using the
addHelperPath() method. As you add paths to the stack,
Zend_View will look at the most-recently-added path for
the requested helper class. This allows you to add to (or even
override) the initial distribution of helpers with your own custom
helpers.
$view = new Zend_View();
// Add /path/to/some/helpers with class prefix 'My_View_Helper'
$view->addHelperPath('/path/to/some/helpers', 'My_View_Helper');
// Add /other/path/to/helpers with class prefix 'Your_View_Helper'
$view->addHelperPath('/other/path/to/helpers', 'Your_View_Helper');
// now when you call $this->helperName(), Zend_View will look first for
// "/path/to/some/helpers/HelperName" using class name
// "Your_View_Helper_HelperName", then for
// "/other/path/to/helpers/HelperName.php" using class name
// "My_View_Helper_HelperName", and finally for
// "Zend/View/Helper/HelperName.php" using class name
// "Zend_View_Helper_HelperName".
Writing Custom Helpers
Writing custom helpers is easy; just follow these rules:
-
While not strictly necessary, we recommend either implementing
Zend_View_Helper_Interface or extending
Zend_View_Helper_Abstract when creating your
helpers. Introduced in 1.6.0, these simply define a
setView() method; however, in upcoming releases, we
plan to implement a strategy pattern that will simplify much of
the naming schema detailed below. Building off these now will
help you future-proof your code.
-
The class name must, at the very minimum, end with the helper
name itself, using MixedCaps. E.g., if you were writing a
helper called "specialPurpose", the class name would minimally
need to be "SpecialPurpose". You may, and should, give the class
name a prefix, and it is recommended that you use 'View_Helper'
as part of that prefix: "My_View_Helper_SpecialPurpose". (You
will need to pass in the prefix, with or without the trailing
underscore, to addHelperPath() or
setHelperPath()).
-
The class must have a public method that matches the
helper name; this is the method that will be called when
your template calls "$this->specialPurpose()". In our
"specialPurpose" helper example, the required method
declaration would be "public function specialPurpose()".
-
In general, the class should not echo or print or otherwise
generate output. Instead, it should return values to be
printed or echoed. The returned values should be escaped
appropriately.
-
The class must be in a file named after the helper class. Again
using our "specialPurpose" helper example, the file has to be
named "SpecialPurpose.php".
Place the helper class file somewhere in your helper path stack, and
Zend_View will automatically load, instantiate,
persist, and execute it for you.
Here is an example of our SpecialPurpose helper code:
class My_View_Helper_SpecialPurpose extends Zend_View_Helper_Abstract
{
protected $_count = 0;
public function specialPurpose()
{
$this->_count++;
$output = "I have seen 'The Jerk' {$this->_count} time(s).";
}
}
Then in a view script, you can call the SpecialPurpose
helper as many times as you like; it will be instantiated once, and
then it persists for the life of that Zend_View
instance.
// remember, in a view script, $this refers to the Zend_View instance.
echo $this-> specialPurpose();
echo $this-> specialPurpose();
echo $this-> specialPurpose();
The output would look something like this:
I have seen 'The Jerk' 1 time(s ).
I have seen 'The Jerk' 2 time(s ).
I have seen 'The Jerk' 3 time(s ).
Sometimes you will need access to the calling Zend_View
object -- for instance, if you need to use the registered encoding,
or want to render another view script as part of your helper. To get
access to the view object, your helper class should have a
setView($view) method, like the following:
class My_View_Helper_ScriptPath
{
public $view;
public function setView(Zend_View_Interface $view)
{
$this->view = $view;
}
public function scriptPath($script)
{
return $this->view->getScriptPath($script);
}
}
If your helper class has a setView() method, it will be
called when the helper class is first instantiated, and passed the
current view object. It is up to you to persist the object in your
class, as well as determine how it should be accessed.
If you are extending Zend_View_Helper_Abstract, you do
not need to define this method, as it is defined for you.
Registering Concrete Helpers
Sometimes it is convenient to instantiate a view helper, and then register it with the
view. As of version 1.10.0, this is now possible using the
registerHelper() method, which expects two arguments: the
helper object, and the name by which it will be registered.
$helper = new My_Helper_Foo();
// ...do some configuration or dependency injection...
$view->registerHelper($helper, 'foo');
If the helper has a setView() method, the view object will call
this and inject itself into the helper on registration.
Note: Helper name should match a method
The second argument to registerHelper() is the name of the
helper. A corresponding method name should exist in the helper; otherwise,
Zend_View will call a non-existent method when invoking the
helper, raising a fatal PHP error.
|
|