repo_zf1/documentation/manual/en/module_specs/Zend_Controller-Plugins-ActionStack.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect3 id="zend.controller.plugins.standard.actionstack">
    <title>ActionStack</title>

    <para>
        The <emphasis>ActionStack</emphasis> plugin allows you to manage a stack of
        requests, and operates as a <emphasis>postDispatch</emphasis> plugin. If a
        forward (i.e., a call to another action) is already detected in the
        current request object, it does nothing. However, if not, it checks its
        stack and pulls the topmost item off it and forwards to the action
        specified in that request. The stack is processed in <acronym>LIFO</acronym> order.
    </para>

    <para>
        You can retrieve the plugin from the front controller at any time using
        <methodname>Zend_Controller_Front::getPlugin('Zend_Controller_Plugin_ActionStack')</methodname>.
        Once you have the plugin object, there are a variety of mechanisms you
        can use to manipulate it.
    </para>

    <itemizedlist>
        <listitem>
            <para>
                <methodname>getRegistry()</methodname> and <methodname>setRegistry()</methodname>.
                Internally, <emphasis>ActionStack</emphasis> uses a
                <classname>Zend_Registry</classname> instance to store the stack. You can
                substitute a different registry instance or retrieve it with
                these accessors.
            </para>
        </listitem>

        <listitem>
            <para>
                <methodname>getRegistryKey()</methodname> and
                <methodname>setRegistryKey()</methodname>.
                These can be used to indicate which registry key to use when
                pulling the stack. Default value is
                '<classname>Zend_Controller_Plugin_ActionStack</classname>'.
            </para>
        </listitem>

        <listitem>
            <para>
                <methodname>getStack()</methodname> allows you to retrieve the stack of
                actions in its entirety.
            </para>
        </listitem>

        <listitem>
            <para>
                <methodname>pushStack()</methodname> and <methodname>popStack()</methodname> allow
                you to add to and pull from the stack, respectively.
                <methodname>pushStack()</methodname> accepts a request object.
            </para>
        </listitem>
    </itemizedlist>

    <para>
        An additional method, <methodname>forward()</methodname>, expects a request object,
        and sets the state of the current request object in the front controller
        to the state of the provided request object, and markes it as
        undispatched (forcing another iteration of the dispatch loop).
    </para>
</sect3>
<!--
vim:se ts=4 sw=4 et:
-->