<commit_before>.. _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 | int                                                       |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 flexbility, 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 | int | 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   |bool                                                               |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  |bool                                                               |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:

.. rubric:: 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;
<commit_msg>Updated types nomenclature: short to long<commit_after>.. _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 flexbility, 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:

.. rubric:: 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;

{'fraction_non_alphanumeric': 0.486897147329501, 'fraction_numerical': 0.0002698836801338623, 'mean_word_length': 0.3047642522624036, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 19, 'https://': 0, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 464, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5009492', 'n_tokens_mistral': 2833, 'n_tokens_neox': 2700, 'n_words': 1295}