repo_zf1/documentation/manual/en/module_specs/Zend_Navigation-Pages-Common.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect2 id="zend.navigation.pages.common">
    <title>Common page features</title>

    <para>
        All page classes must extend <classname>Zend_Navigation_Page</classname>,
        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.
    </para>

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

    <para>
        Read more on extending <classname>Zend_Navigation_Page</classname> in
        <link linkend="zend.navigation.pages.custom">Creating custom page types</link>.
    </para>

    <table id="zend.navigation.pages.common.options">
        <title>Common page options</title>

        <tgroup cols="4">
            <thead>
                <row>
                    <entry>Key</entry>
                    <entry>Type</entry>
                    <entry>Default</entry>
                    <entry>Description</entry>
                </row>
            </thead>

            <tbody>
                <row>
                    <entry><code>label</code></entry>
                    <entry><type>String</type></entry>
                    <entry><constant>NULL</constant></entry>
                    <entry>A page label, such as 'Home' or 'Blog'.</entry>
                </row>

                <row>
                    <entry><code>id</code></entry>
                    <entry><type>String</type> | <code>int</code></entry>
                    <entry><constant>NULL</constant></entry>

                    <entry>
                        An id tag/attribute that may be used when rendering
                        the page, typically in an anchor element.
                    </entry>
                </row>

                <row>
                    <entry><code>class</code></entry>
                    <entry><type>String</type></entry>
                    <entry><constant>NULL</constant></entry>

                    <entry>
                        A <acronym>CSS</acronym> class that may be used when rendering the page,
                        typically in an anchor element.
                    </entry>
                </row>

                <row>
                    <entry><code>title</code></entry>
                    <entry><type>String</type></entry>
                    <entry><constant>NULL</constant></entry>

                    <entry>
                        A short page description, typically for using
                        as the <code>title</code> attribute in an anchor.
                    </entry>
                </row>

                <row>
                    <entry><code>target</code></entry>
                    <entry><type>String</type></entry>
                    <entry><constant>NULL</constant></entry>

                    <entry>
                        Specifies a target that may be used for the page,
                        typically in an anchor element.
                    </entry>
                </row>

                <row>
                    <entry><code>accesskey</code></entry>
                    <entry><type>String</type></entry>
                    <entry><constant>NULL</constant></entry>

                    <entry>
                        This attribute assigns an access key to an <code>A</code> element.
                        An access key is a single character from the document character set.
                    </entry>
                </row>

                <row>
                    <entry><code>fragment</code></entry>
                    <entry><type>String</type></entry>
                    <entry><constant>NULL</constant></entry>

                    <entry>
                        The 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)
                    </entry>
                </row>

                <row>
                    <entry><code>rel</code></entry>
                    <entry><type>Array</type></entry>
                    <entry><methodname>array()</methodname></entry>

                    <entry>
                        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 <code>'alternate' => 'format/plain.html'</code>.
                        To allow full flexbility, there are no restrictions on
                        relation values. The value does not have to be a string.
                        Read more about <code>rel</code> and <code>rev</code> in
                        <link linkend="zend.view.helpers.initial.navigation.links">the
                        section on the Links helper.</link>.
                    </entry>
                </row>

                <row>
                    <entry><code>rev</code></entry>
                    <entry><type>Array</type></entry>
                    <entry><methodname>array()</methodname></entry>

                    <entry>
                        Specifies reverse relations for the page. Works exactly
                        like <code>rel</code>.
                    </entry>
                </row>

                <row>
                    <entry><code>order</code></entry>

                    <entry>
                        <type>String</type> | <code>int</code> | <constant>NULL</constant>
                    </entry>

                    <entry><constant>NULL</constant></entry>

                    <entry>
                        Works like order for elements in
                        <link linkend="zend.form.quickstart.render">
                        <classname>Zend_Form</classname></link>. 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 <code>order</code> attribute to a low number,
                        e.g. -100. If a <type>String</type> is given, it must
                        parse to a valid <code>int</code>. If <constant>NULL</constant>
                        is given, it will be reset, meaning the order in which
                        the page was added to the container will be used.
                    </entry>
                </row>

                <row>
                    <entry><code>resource</code></entry>

                    <entry>
                        <type>String</type> | <classname>Zend_Acl_Resource_Interface</classname>
                        | <constant>NULL</constant>
                    </entry>

                    <entry><constant>NULL</constant></entry>

                    <entry>
                        <acronym>ACL</acronym> resource to associate with the page. Read more in
                        <link linkend="zend.view.helpers.initial.navigation.acl">the
                        section on <acronym>ACL</acronym> integration in view helpers.</link>.
                    </entry>
                </row>

                <row>
                    <entry><code>privilege</code></entry>
                    <entry><type>String</type> | <constant>NULL</constant></entry>
                    <entry><constant>NULL</constant></entry>

                    <entry>
                        <acronym>ACL</acronym> privilege to associate with the page. Read more in
                        <link linkend="zend.view.helpers.initial.navigation.acl">the
                        section on <acronym>ACL</acronym> integration in view helpers.</link>.
                    </entry>
                </row>

                <row>
                    <entry><code>active</code></entry>
                    <entry><code>bool</code></entry>
                    <entry><constant>FALSE</constant></entry>

                    <entry>
                        Whether the page should be considered active for the
                        current request. If active is <constant>FALSE</constant> or not
                        given, <acronym>MVC</acronym> pages will check its properties against the
                        request object upon calling <code>$page->isActive()</code>.
                    </entry>
                </row>

                <row>
                    <entry><code>visible</code></entry>
                    <entry><code>bool</code></entry>
                    <entry><constant>TRUE</constant></entry>

                    <entry>
                        Whether page should be visible for the user, or just
                        be a part of the structure. Invisible pages are skipped
                        by view helpers.
                    </entry>
                </row>

                <row>
                    <entry><code>pages</code></entry>

                    <entry>
                        <type>Array</type> | <classname>Zend_Config</classname> |
                        <constant>NULL</constant>
                    </entry>

                    <entry><constant>NULL</constant></entry>

                    <entry>
                        Child pages of the page. This could be an <type>Array</type>
                        or <classname>Zend_Config</classname> object containing either page
                        options that can be passed to the <methodname>factory()</methodname>
                        method, or actual <classname>Zend_Navigation_Page</classname>
                        instances, or a mixture of both.
                    </entry>
                </row>
            </tbody>
        </tgroup>
    </table>

    <note>
        <title>Custom properties</title>

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

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

    <example id="zend.navigation.pages.common.example.customprops">
        <title>Custom page properties</title>

        <para>
            This example shows how custom properties can be used.
        </para>

        <programlisting language="php"><![CDATA[
$page = new Zend_Navigation_Page_Mvc();
$page->foo = 'bar';
$page->meaning = 42;

echo $page->foo;

if ($page->meaning != 42) {
    // action should be taken
}
]]></programlisting>
    </example>
</sect2>