repo_zf1/documentation/manual/en/module_specs/Zend_Controller-ActionHelpers-FlashMessenger.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect3 id="zend.controller.actionhelpers.flashmessenger">
    <title>FlashMessenger</title>

    <sect4 id="zend.controller.actionhelper.flashmessenger.introduction">
        <title>Introduction</title>

        <para>
            The <emphasis>FlashMessenger</emphasis> helper allows you to pass messages
            that the user may need to see on the next request. To accomplish
            this, <emphasis>FlashMessenger</emphasis> uses
            <classname>Zend_Session_Namespace</classname> to store messages for future or
            next request retrieval. It is generally a good idea that if you
            plan on using <classname>Zend_Session</classname> or
            <classname>Zend_Session_Namespace</classname>, that you initialize with
            <methodname>Zend_Session::start()</methodname> in your bootstrap file. (See the
            <link linkend="zend.session.advanced_usage.starting_a_session">Zend_Session</link>
            documentation for more details on its usage.)
        </para>
    </sect4>

    <sect4 id="zend.controller.actionhelper.flashmessenger.api">
        <title>Available Methods</title>

        <para>
            General methods:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>setNamespace($namespace='default')</methodname> is used to set the namespace
                     into which messages are stored by default. 
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>getNamespace()</methodname> is used to retrieve the name of the 
                    default namespace.  The default namespace is 'default'.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>resetNamespace()</methodname> is used to reset the namespace name
                    to the default value, 'default'.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Methods for manipulating messages set in the previous request:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>hasMessages($namespace=NULL)</methodname> is used to determine
                    if messages have been carried from a previous request by the flash messenger.  The
                    optional argument <varname>$namespace</varname> specifies which namespace to look in.
                    If the <varname>$namespace</varname> argument is omitted, the value returned by
                    <methodname>getNamespace()</methodname> will be used.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>getMessages($namespace=NULL)</methodname> is used to retrieve the
                    messages which have been carried from a previous request by the flash messenger.  The
                    optional argument <varname>$namespace</varname> specifies which namespace to pull from.
                    If the <varname>$namespace</varname> argument is omitted, the value returned by
                    <methodname>getNamespace()</methodname> will be used.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>getIterator($namespace=NULL)</methodname> wraps the return value of 
                    <methodname>getMessages()</methodname> in an instance of <classname>ArrayObject</classname>.
                    If the <varname>$namespace</varname> argument is omitted, the value returned by
                    <methodname>getNamespace()</methodname> will be used.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>count($namespace=NULL)</methodname> returns the number of messages contained
                    in the specified namespace.  If the <varname>$namespace</varname> argument is omitted, the 
                    value returned by <methodname>getNamespace()</methodname> will be used.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>clearMessages($namespace=NULL)</methodname> is used to clear all the
                    messages which have been carried from a previous request by the flash messenger.  The
                    optional argument <varname>$namespace</varname> specifies which namespace to clear out.
                    If the <varname>$namespace</varname> argument is omitted, the value returned by
                    <methodname>getNamespace()</methodname> will be used.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Methods for manipulating messages set in the current request:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>addMessage($message, $namespace=NULL)</methodname> is used to add a new 
                    message to the current request.  <varname>$message</varname> contains the message
                    to be added, and the optional argument <varname>$namespace</varname> will specify
                    the namespace.  If the <varname>$namespace</varname> argument is omitted, the value
                    returned by <methodname>getNamespace()</methodname> will be used.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>hasCurrentMessages($namespace=NULL)</methodname> is used to determine
                    if messages have been added to the flash messenger during the current request.  The
                    optional argument <varname>$namespace</varname> specifies which namespace to look in.
                    If the <varname>$namespace</varname> argument is omitted, the value returned by
                    <methodname>getNamespace()</methodname> will be used.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>getCurrentMessages($namespace=NULL)</methodname> is used to retrieve the
                    messages which have been added to the flash messenger during the current request.  The
                    optional argument <varname>$namespace</varname> specifies which namespace to pull from.
                    If the <varname>$namespace</varname> argument is omitted, the value returned by
                    <methodname>getNamespace()</methodname> will be used.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>clearCurrentMessages($namespace=NULL)</methodname> is used to clear all the
                    messages which have been added to the flash messenger during the current request.  The
                    optional argument <varname>$namespace</varname> specifies which namespace to clear out.
                    If the <varname>$namespace</varname> argument is omitted, the value returned by
                    <methodname>getNamespace()</methodname> will be used.
                </para>
            </listitem>
        </itemizedlist>

    </sect4>

    <sect4 id="zend.controller.actionhelper.flashmessenger.basicusage">
        <title>Basic Usage Example</title>

        <para>
            The usage example below shows the use of the flash messenger at its
            most basic. When the action <filename>/some/my</filename> is called, it adds
            the flash message "Record Saved!" A subsequent request to the action
            <filename>/some/my-next-request</filename> will retrieve it (and thus delete
            it as well).
        </para>

        <programlisting language="php"><![CDATA[
class SomeController extends Zend_Controller_Action
{
    /**
     * FlashMessenger
     *
     * @var Zend_Controller_Action_Helper_FlashMessenger
     */
    protected $_flashMessenger = null;

    public function init()
    {
        $this->_flashMessenger =
            $this->_helper->getHelper('FlashMessenger');
        $this->initView();
    }

    public function myAction()
    {
        /**
         * default method of getting
         * Zend_Controller_Action_Helper_FlashMessenger instance
         * on-demand
         */
        $this->_flashMessenger->addMessage('Record Saved!');
    }

    public function myNextRequestAction()
    {
        $this->view->messages = $this->_flashMessenger->getMessages();
        $this->render();
    }
}
]]></programlisting>
    </sect4>
</sect3>