Chapter 15. Zym_View

15.1.1. GetRequest Helper

The helper allows access to the request object (Zend_Controller_Response_Abstract) available within Zend_Controller_Front. Retrieving the request object in the view is not recommended; however, this helper is provided as a convince.

getRequest()

15.1.2. GetResponse Helper

Allows access to the response object (Zend_Controller_Response_Abstract) within Zend_Controller_Front.

getResponse()

15.1.3. GetSession Helper

This helper returns a Zend_Session_Namespace. A session should be started if Zend_Session strict is set. See Zend_Session_Namespace documentation for usage. (hint: usage is similar to it)

getSession($namespace = 'Default', $singleInstance = false)

15.1.4. Navigation Helpers

The navigation helpers are used in conjunction with Zym_Navigation, and allows for easy-to-use rendering of menus, breadcrumbs and XML sitemaps.

If a navigation container is not explicitly set in a helper using $helper->setNavigation($nav), the helper will look for it in Zend_Registry with the key Zym_Navigation. This means that as long as you store a navigation container in the registry, you normally don't have to think about setting/getting it in the view helpers.

If a navigation container is not explicitly set in a helper and nothing is found in Zend_Registry, the helper will create an empty Zym_Navigation object before rendering or when using $helper->getNavigation(). Combining this feature with the proxy feature shown below means that navigation view helpers can be used without being aware of the existence of any underlying Zym_Navigation objects.

Example 15.1. 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 means that the following is possible in a view script, for instance:

<?php $this->menu()->addPage(array('label' => 'New page')) ?>

The menu helper is used in this example, but it could just as easily be using the breadcrumbs or sitemap view helper

15.1.4.1. Integration with Zend_Translate

The navigation helpers support translating 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; adding the translator to Zend_Registry using the key Zend_Translate, in which case it will be found by the helpers.

If you want to disable translating, use $helper->setUseTranslator(false).

	Note
	There is no translation in the sitemap helper, since there are no page labels or titles involved in an XML sitemap.

15.1.4.2. Integration with ACL

All navigation view helpers support ACL inherently from the class Zym_View_Helper_NavigationAbstract. A Zend_Acl object can be assigned to a helper instance with $helper->setAcl($acl), where $helper refers to an instance of a helper, and $acl is an ACL instance containing roles and possibly resources. The helpers can be assigned a role to use when iterating pages, by doing $helper->setRole('member') to set a role id, or $helper->setRole(new Zend_Acl_Role('member')) to set an instance. If ACL is used in the helper, the role in the helper must have rights for the page's resource and/or privilege to be included in a menu/breadcrumb/sitemap.

The examples below all show how ACL affects rendering.

15.1.4.3. Navigation structure used in examples

This shows an example setup of a navigation structure, including routes and ACL setup, that is used in the examples below.

<?php
/*
 * An array of example pages
 * 
 * Each element in the array will be passed to
 * Zym_Navigation_Page::factory() when constructing
 * the navigation object below.
 */
$config = array(
    array(
        'label' => 'Page 1',
        'action' => 'index',
        'controller' => 'index',
        'id' => 'home-link'
    ),
    array(
        'label' => 'Zym',
        'uri' => 'http://www.zym-project.com/',
        'position' => 100
    ),
    array(
        'label' => 'Page 2',
        'action' => 'index',
        'controller' => 'page2',
        'pages' => array(
            array(
                'label' => 'Page 2.1',
                'action' => 'page2_1',
                'controller' => 'page2',
                'class' => 'special-one',
                'title' => 'This element has a special class',
                'active' => true
            ),
            array(
                'label' => 'Page 2.2',
                'action' => 'page2_2',
                'controller' => 'page2',
                'class' => 'special-two',
                'title' => 'This element has a special class too'
            )
        )
    ),
    array(
        'label' => 'Page 2 with params',
        'action' => 'index',
        'controller' => 'page2',
        // specify a param or two
        'params' => array(
            'format' => 'json',
            'foo' => 'bar'
        )
    ),
    array(
        'label' => 'Page 2 with params and a route',
        'action' => 'index',
        'controller' => 'page2',
        // specify a route name and a param for the route
        'route' => 'nav-route-example',
        'params' => array(
            'format' => 'json'
        )
    ),
    array(
        'label' => 'Page 3',
        'action' => 'index',
        'controller' => 'index',
        'module' => 'mymodule',
        'reset_params' => false
    ),
    array(
        'label' => 'Page 4',
        'uri' => '#',
        'pages' => array(
            array(
                'label' => 'Page 4.1',
                'uri' => '/page4',
                'title' => 'Page 4 using uri',
                'pages' => array(
                    array(
                        'label' => 'Page 4.1.1',
                        'title' => 'Page 4 using mvc params',
                        'action' => 'index',
                        'controller' => 'page4',
                        // let's say this page is active
                        'active' => '1'
                    )
                )
            )
        )
    ),
    array(
        'label' => 'Page 0?',
        'uri' => '/setting/the/position/option',
        // setting position to -1 should make it appear first
        'position' => -1
    ),
    array(
        'label' => 'Page 5',
        'uri' => '/',
        // this page should not be visible
        'visible' => false,
        'pages' => array(
            array(
                'label' => 'Page 5.1',
                'uri' => '#',
                'pages' => array(
                    array(
                        'label' => 'Page 5.1.1',
                        'uri' => '#',
                        'pages' => array(
                            array(
                                'label' => 'Page 5.1.2',
                                'uri' => '#',
                                // let's say this page is active
                                'active' => true
                            )
                        )
                    )
                )
            )
        )
    ),
    array(
        'label' => 'ACL page 1 (guest.foo)',
        'uri' => '#acl-guest.foo',
        'resource' => 'guest.foo',
        'pages' => array(
            array(
                'label' => 'ACL page 1.1 (member.foo)',
                'uri' => '#acl-member.foo',
                'resource' => 'member.foo'
            ),
            array(
                'label' => 'ACL page 1.2 (member.bar)',
                'uri' => '#acl-member.bar',
                'resource' => 'member.bar'
            ),
            array(
                'label' => 'ACL page 1.3 (member.baz)',
                'uri' => '#acl-member.baz',
                'resource' => 'member.baz'
            ),
            array(
                'label' => 'ACL page 1.4 (member.baz + read privilege)',
                'uri' => '#acl-member.baz+read',
                'resource' => 'member.baz',
                'privilege' => 'read'
            ),
            array(
                'label' => 'ACL page 1.5 (member.baz + write privilege)',
                'uri' => '#acl-member.baz+write',
                'resource' => 'member.baz',
                'privilege' => 'write'
            )
        )
    ),
    array(
        'label' => 'ACL page 3 (admin.foo)',
        'uri' => '#acl-admin.foo',
        'resource' => 'admin.foo',
        'pages' => array(
            array(
                'label' => 'ACL page 3.1 (nothing)',
                'uri' => '#acl-nada'
            )
        )
    ),
    array(
        'label' => 'No link :o',
        'type' => 'uri',
        'title' => 'This URI page has no URI set, so a span is generated'
    )
);
 
// Create navigation from array
$navigation = new Zym_Navigation($config);
 
// Put navigation in registry so it's found by helpers
Zend_Registry::set('Zym_Navigation', $navigation);
 
// Add a route to show that zym_navigation can be aware of routes and params
$front = Zend_Controller_Front::getInstance();
$router = $front->getRouter();
$router->addRoute(
    'nav-route-example',
    new Zend_Controller_Router_Route('page2/:format', array(
        'controller' => 'page2', 'action' => 'index')
    )
);
 
// Add some ACL stuff to show integration with ACL
$navAcl = new Zend_Acl();
 
$navAcl->addRole(new Zend_Acl_Role('guest'));
$navAcl->addRole(new Zend_Acl_Role('member'), 'guest');
$navAcl->addRole(new Zend_Acl_Role('admin'), 'member');
$navAcl->addRole(new Zend_Acl_Role('special'), 'member');
 
$navAcl->add(new Zend_Acl_Resource('guest.foo'));
$navAcl->add(new Zend_Acl_Resource('member.foo'));
$navAcl->add(new Zend_Acl_Resource('member.bar'), 'member.foo');
$navAcl->add(new Zend_Acl_Resource('member.baz'));
$navAcl->add(new Zend_Acl_Resource('admin.foo'));
 
$navAcl->allow('guest', 'guest.foo');
$navAcl->allow('member', 'member.foo');
$navAcl->allow('special', 'member.baz', 'read');
$navAcl->allow('admin', null);
 
Zend_Registry::set('Zym_Navigation_Acl', $navAcl);
 
// Do the following in the view (for this demo we keep it simple,
// but this is probably better to do in a plugin or when you set up
// ACL or navigation):
/*
$navAcl = Zend_Registry::get('Zym_Navigation_Acl');
 
$this->breadcrumbs()->setAcl($navAcl);
$this->breadcrumbs()->setRole('special');
$this->menu()->setAcl($navAcl);
$this->menu()->setRole('special');
$this->sitemap()->setAcl($navAcl);
$this->sitemap()->setRole('special');
*/

15.1.4.4. Breadcrumbs Helper

Breadcrumbs are used to indicate where in a site structure a user is currently browsing, and typically is something along the lines of "You are here: Home > Products > FantasticProduct 1.0". The breadcrumbs helper follows the guidelines from Breadcrumbs Pattern - Yahoo! Design Pattern Library, and allows customization or overriding of the suggested features.

The way the breadcrumbs helper works; it finds the deepest active page in a navigation structure, 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 Zym_Navigation_Page_Mvc.

Example 15.2. Rendering breadcrumbs

This example shows how to render breadcrumbs with default settings. The reason it doesn't output Page 5 > Page 5.1 > Page 5.1.1 > Page 5.12 is because Page 5 is not visible, and thus is left out of the breadcrumbs iteration.

In a view script or layout:
<?php echo $this->breadcrumbs() ?>
 
or if short tags are enabled:
<?= $this->breadcrumbs() ?>
 
Output:
<a href="index.php?option=com_siteembed&page=#">Page 4</a> &amp;gt; <a title="Page 4 using uri" href="index.php?option=com_siteembed&page=/page4">Page 4.1</a> &amp;gt; Page 4.1.1
 
Rendering with 8 spaces indentation:
<?= $this->breadcrumbs()->toString(8) ?>
        <a href="index.php?option=com_siteembed&page=#">Page 4</a> &amp;gt; <a title="Page 4 using uri" href="index.php?option=com_siteembed&page=/page4">Page 4.1</a> &amp;gt; Page 4.1.1

Example 15.3. Rendering customized breadcrumbs

This example shows how to render breadcrumbs with customized settings.

In a view script or layout:
<?php
$this->breadcrumbs()->setLinkLast(true);
$this->breadcrumbs()->setSeparator('<span class="separator"> &amp;#9654; </span>');
echo $this->breadcrumbs();
?>
Output:
<a href="index.php?option=com_siteembed&page=#">Page 4</a><span class="separator"> &amp;#9654; </span><a title="Page 4 using uri" href="index.php?option=com_siteembed&page=/page4">Page 4.1</a><span class="separator"> &amp;#9654; </span><a title="Page 4 using mvc params" href="index.php?option=com_siteembed&page=/page4">Page 4.1.1</a>
 
Setting minimum depth required to render breadcrumbs:
<?php
$this->breadcrumbs()->setMinDepth(10);
// this outputs an empty string, since the deepest
// active page is not level 10 or deeper
echo $this->breadcrumbs();
?>

15.1.4.5. Menu Helper

The menu helper is used for rendering navigation containers as an HTML menu, by using ul and li elements. How the HTML should be presented is easily configurable by using CSS.

Example 15.4. Rendering a menu

This example shows how to render a menu that is registered in the view helper, either by $helper->setNavigation($nav) or retrieving the object from Zend_Registry.

Notice how pages that are invisible or pages with ACL roles incompatible with the view helper are filtered out.

In a view script or layout:
<?php echo $this->menu() ?>
 
or if short tags are enabled:
<?= $this->menu() ?>
 
Output:
<ul class="navigation">
    <li>
        <a href="index.php?option=com_siteembed&page=/setting/the/position/option">Page 0?</a>
 
    </li>
    <li>
        <a id="home-link" href="index.php?option=com_siteembed&page=/">Page 1</a>
    </li>
    <li class="active">
        <a href="index.php?option=com_siteembed&page=/page2">Page 2</a>
        <ul>
            <li class="active">
 
                <a title="This element has a special class" class="special-one" href="index.php?option=com_siteembed&page=/page2/page2_1">Page 2.1</a>
            </li>
            <li>
                <a title="This element has a special class too" class="special-two" href="index.php?option=com_siteembed&page=/page2/page2_2">Page 2.2</a>
            </li>
        </ul>
    </li>
    <li>
 
        <a href="index.php?option=com_siteembed&page=/page2/index/format/json/foo/bar">Page 2 with params</a>
    </li>
    <li>
        <a href="index.php?option=com_siteembed&page=/page2/json">Page 2 with params and a route</a>
    </li>
    <li>
        <a href="index.php?option=com_siteembed&page=/mymodule">Page 3</a>
 
    </li>
    <li class="active">
        <a href="index.php?option=com_siteembed&page=#">Page 4</a>
        <ul>
            <li class="active">
                <a title="Page 4 using uri" href="index.php?option=com_siteembed&page=/page4">Page 4.1</a>
                <ul>
                    <li class="active">
 
                        <a title="Page 4 using mvc params" href="index.php?option=com_siteembed&page=/page4">Page 4.1.1</a>
                    </li>
                </ul>
            </li>
        </ul>
    </li>
    <li>
        <a href="index.php?option=com_siteembed&page=#acl-guest.foo">ACL page 1 (guest.foo)</a>
 
        <ul>
            <li>
                <a href="index.php?option=com_siteembed&page=#acl-member.foo">ACL page 1.1 (member.foo)</a>
            </li>
            <li>
                <a href="index.php?option=com_siteembed&page=#acl-member.bar">ACL page 1.2 (member.bar)</a>
            </li>
            <li>
 
                <a href="index.php?option=com_siteembed&page=#acl-member.baz+read">ACL page 1.4 (member.baz + read privilege)</a>
            </li>
        </ul>
    </li>
    <li>
        <span title="This URI page has no URI set, so a span is generated">No link :o</span>
    </li>
    <li>
 
        <a href="http://www.zym-project.com/">Zym</a>
    </li>
</ul>

Example 15.5. Rendering a custom menu

This example shows how to render a menu that is not registered in the view helper.

<?php
$nav = new Zym_Navigation(array(
    array(
        'label'      => 'Site 1',
        'uri'        => 'site1',
        'changefreq' => 'daily',
        'priority'   => '0.9'
    ),
    array(
        'label'      => 'Site 2',
        'uri'        => 'site2',
        'active'     => true,
        'lastmod'    => 'earlier'
    ),
    array(
        'label'      => 'Site 3',
        'uri'        => 'site3',
        'changefrew' => 'often'
    )
));
 
$this->menu()->setUlClass('my-nav');
$this->menu()->setIndent(4);
echo $this->menu()->renderMenu($nav);
?>
    <ul class="my-nav">
        <li>
            <a href="index.php?option=com_siteembed&page=site1">Site 1</a>
        </li>
        <li class="active">
            <a href="index.php?option=com_siteembed&page=site2">Site 2</a>
        </li>
        <li>
            <a href="index.php?option=com_siteembed&page=site3">Site 3</a>
        </li>
    </ul>

15.1.4.6. Sitemap Helper

The sitemap helper is used for generating XML sitemaps, as defined by the Sitemaps XML format. XML sitemaps can be used to have detailed control of how a search engine should index your site.

By default, the sitemap helper uses Zym's sitemap validators to validate each element that is used. 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).

Table 15.1. 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.

Example 15.6. Rendering an XML sitemap

This example shows how to render an XML sitemap based on the setup we did further up.

<?php
// In a view script or layout:
 
// format output
$this->sitemap()->setFormatOutput(true); // default is false
 
// other possible methods:
//$this->sitemap()->setUseXmlDeclaration(false); // default is true
//$this->sitemap()->setUseMaxDepth(1); // default is null, no max depth
//$this->sitemap()->setServerUrl('http://my.otherhost.com'); // default is to detect automatically
 
// print sitemap
echo $this->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/setting/the/position/option</loc>
  </url>
  <url>
    <loc>http://www.example.com/</loc>
  </url>
  <url>
    <loc>http://www.example.com/page2</loc>
  </url>
  <url>
    <loc>http://www.example.com/page2/page2_1</loc>
  </url>
  <url>
    <loc>http://www.example.com/page2/page2_2</loc>
  </url>
  <url>
    <loc>http://www.example.com/page2/index/format/json/foo/bar</loc>
  </url>
  <url>
    <loc>http://www.example.com/page2/json</loc>
  </url>
  <url>
    <loc>http://www.example.com/mymodule</loc>
  </url>
  <url>
    <loc>http://www.example.com/demo/navigation/#</loc>
  </url>
  <url>
    <loc>http://www.example.com/page4</loc>
  </url>
  <url>
    <loc>http://www.example.com/page4</loc>
  </url>
  <url>
    <loc>http://www.example.com/demo/navigation/#acl-guest.foo</loc>
  </url>
  <url>
    <loc>http://www.example.com/demo/navigation/#acl-member.foo</loc>
  </url>
  <url>
    <loc>http://www.example.com/demo/navigation/#acl-member.bar</loc>
  </url>
  <url>
    <loc>http://www.example.com/demo/navigation/#acl-member.baz+read</loc>
  </url>
  <url>
    <loc>http://www.zym-project.com/</loc>
  </url>
</urlset>

15.1.5. TimeSince Helper

This helper calculates the time passed from timestamps to generate a formatted string like "5 days and 4 hours". Applications of this helper are generally seen in "Created 2 weeks ago" or "Last modified 5 minutes ago" type lines.

Units supported are years, months, weeks, days, minutes, seconds. String format is the largest possible unit and if possible the unit below it. If a 1 year and 2 weeks have passed then "1 year" is the output; however, if 1 year, 2 months and 5 days have passed then "1 year and 2 months" is returned. If less than a second have passed then "less than a second" is returned.

Output is automatically translated if possible using Zend_View_Helper_Translate. The translation format is '%d months'. An already completed gettext pot file is located on Zym's demo in the data locale folder.

timeSince($timestamp, $time = null)

Example 15.7. Using Zym_View_Helper_TimeSince

<!-- Simple -->
Last updated <?= $this->timeSince($timestamp); ?> ago
 
<!-- Time since a specified timestamp -->
<?= $this->timeSince($timestamp, strtotime('+1 day')); ?>

15.1.6. TimeUntil Helper

This helper calculates the time to an event from timestamps to generate a formatted string like "5 days and 4 hours". It is similar to the TimeSince helper except applications of this helper are generally seen in "This event will start in 5 days and 4 hours" or "3 weeks before expiration" type lines.