Home Info Files

Zend Framework 2 Documentation (Manual)

File: /_sources/modules/zend.navigation.pages.common.txt

:orphan:

.. _zend.navigation.pages.common:

Common page features
--------------------

All page classes must extend ``Zend\Navigation\Page\AbstractPage``, and will thus share a common set of features
and properties. Most notably they share the options in the table below and the same initialization process.

Option keys are mapped to *set* methods. This means that the option *order* maps to the method ``setOrder()``, and
*reset_params* maps to the method ``setResetParams()``. If there is no setter method for the option, it will be set
as a custom property of the page.

Read more on extending ``Zend\Navigation\Page\AbstractPage`` in :ref:`Creating custom page types
<zend.navigation.pages.custom>`.

.. _zend.navigation.pages.common.options:

.. table:: Common page options

   +---------+-------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   |Key      |Type                                                               | Default     |Description                                                                                                                                                                                                                                                                                                                                                                                                                                                |
   +=========+===================================================================+=============+===========================================================================================================================================================================================================================================================================================================================================================================================================================================================+
   |label    |String                                                             |NULL         |A page label, such as 'Home' or 'Blog'.                                                                                                                                                                                                                                                                                                                                                                                                                    |
   +---------+-------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   |fragment |String | NULL                                                      |NULL         |A fragment identifier (anchor identifier) pointing to an anchor within a resource that is subordinate to another, primary resource. The fragment identifier introduced by a hash mark "#". Example: ``http://www.example.org/foo.html#bar`` (*bar* is the fragment identifier)                                                                                                                                                                             |
   +---------+-------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   |id       |String | Integer                                                   |NULL         |An *id* tag/attribute that may be used when rendering the page, typically in an anchor element.                                                                                                                                                                                                                                                                                                                                                            |
   +---------+-------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   |class    |String                                                             |NULL         |A *CSS* class that may be used when rendering the page, typically in an anchor element.                                                                                                                                                                                                                                                                                                                                                                    |
   +---------+-------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   |title    |String                                                             |NULL         |A short page description, typically for using as the title attribute in an anchor.                                                                                                                                                                                                                                                                                                                                                                         |
   +---------+-------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   |target   |String                                                             |NULL         |Specifies a target that may be used for the page, typically in an anchor element.                                                                                                                                                                                                                                                                                                                                                                          |
   +---------+-------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   |rel      |Array                                                              |array()      |Specifies forward relations for the page. Each element in the array is a key-value pair, where the key designates the relation/link type, and the value is a pointer to the linked page. An example of a key-value pair is ``'alternate' => 'format/plain.html'``. To allow full flexibility, there are no restrictions on relation values. The value does not have to be a string. Read more about ``rel`` and ``rev`` in the section on the Links helper.|
   +---------+-------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   |rev      |Array                                                              |array()      |Specifies reverse relations for the page. Works exactly like rel.                                                                                                                                                                                                                                                                                                                                                                                          |
   +---------+-------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   |order    |String | Integer | NULL                                            |NULL         |Works like order for elements in ``Zend\Form``. If specified, the page will be iterated in a specific order, meaning you can force a page to be iterated before others by setting the order attribute to a low number, e.g. -100. If a String is given, it must parse to a valid int. If ``NULL`` is given, it will be reset, meaning the order in which the page was added to the container will be used.                                                 |
   +---------+-------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   |resource |String | ``Zend\Permissions\Acl\Resource\ResourceInterface`` | NULL|NULL         |ACL resource to associate with the page. Read more in the section on ACL integration in view helpers.                                                                                                                                                                                                                                                                                                                                                      |
   +---------+-------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   |privilege|String | NULL                                                      |NULL         |ACL privilege to associate with the page. Read more in the section on ACL integration in view helpers.                                                                                                                                                                                                                                                                                                                                                     |
   +---------+-------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   |active   |Boolean                                                            |FALSE        |Whether the page should be considered active for the current request. If active is FALSE or not given, MVC pages will check its properties against the request object upon calling ``$page->isActive()``.                                                                                                                                                                                                                                                  |
   +---------+-------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   |visible  |Boolean                                                            |TRUE         |Whether page should be visible for the user, or just be a part of the structure. Invisible pages are skipped by view helpers.                                                                                                                                                                                                                                                                                                                              |
   +---------+-------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
   |pages    |Array | ``Zend\Config`` | NULL                                     |NULL         |Child pages of the page. This could be an Array or ``Zend\Config`` object containing either page options that can be passed to the ``factory()`` method, or actual ``Zend\Navigation\Page\AbstractPage`` instances, or a mixture of both.                                                                                                                                                                                                                  |
   +---------+-------------------------------------------------------------------+-------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

.. note::

   **Custom properties**

   All pages support setting and getting of custom properties by use of the magic methods ``__set($name, $value)``,
   ``__get($name)``, ``__isset($name)`` and ``__unset($name)``. Custom properties may have any value, and will be
   included in the array that is returned from ``$page->toArray()``, which means that pages can be
   serialized/deserialized successfully even if the pages contains properties that are not native in the page
   class.

   Both native and custom properties can be set using ``$page->set($name, $value)`` and retrieved using
   ``$page->get($name)``, or by using magic methods.

.. _zend.navigation.pages.common.example.customprops:

Custom page properties
^^^^^^^^^^^^^^^^^^^^^^

This example shows how custom properties can be used.

.. code-block:: php
   :linenos:

   $page = new Zend\Navigation\Page\Mvc();
   $page->foo     = 'bar';
   $page->meaning = 42;

   echo $page->foo;

   if ($page->meaning != 42) {
       // action should be taken
   }