repo_zf1/documentation/manual/fr/module_specs/Zend_Controller-ActionHelpers.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 20765 -->
<!-- Reviewed: no -->
<sect1 id="zend.controller.actionhelpers" xmlns:xi="http://www.w3.org/2001/XInclude">
    <title>Aides d'action (Helper)</title>

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

        <para>
            Les aides d'action permettent aux développeurs d'injecter, en cours d'exécution
            et/ou à la demande, des fonctionnalités dans tout contrôleur d'action qui étend
            <classname>Zend_Controller_Action</classname>. Le but des aides d'action est de
            minimiser la nécessité d'étendre le contrôleur d'action abstrait en y injectant des
            fonctionnalités communes de contrôleur d'action.
        </para>

        <para>
            Il y a de nombreuses manières d'utiliser les aides d'action. Les aides d'action
            utilisent le système de gestionnaire ("Broker"), similaire aux gestionnaires vus pour
            les
            <link linkend="zend.view.helpers">Zend_View_Helper</link>, et les
            <link linkend="zend.controller.plugins">Zend_Controller_Plugin</link>. Les aides
            d'action (comme les aides de vue <classname>Zend_View_Helper</classname>) peuvent être
            chargées et appelées à la demande, ou elles peuvent être instanciées au début de la
            requête ("bootstrap") ou au moment de la création des contrôleurs d'action
            (<methodname>init()</methodname>). Pour mieux comprendre ceci, reportez vous à la section
            d'utilisation ci-dessous.
        </para>
    </sect2>

    <sect2 id="zend.controller.actionhelper.initialization">
        <title>Initialisation des aides</title>

        <para>
            Une aide peut être initialisée de plusieurs manières différentes, basées sur vos
            besoins aussi bien que la fonctionnalité de l'aide.
        </para>

        <para>
            Le gestionnaire d'aide est stocké en tant que membre <varname>$_helper</varname> du
            <classname>Zend_Controller_Action</classname> ; utilisez le gestionnaire pour récupérer
            ou appeler les aides. Les méthodes pour faire ceci incluent&#160;:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    L'utilisation explicite de <methodname>getHelper()</methodname>. Passez lui
                    simplement un nom, et l'objet d'aide est retourné&#160;:
                </para>
                <programlisting language="php"><![CDATA[
$flashMessenger = $this->_helper->getHelper('FlashMessenger');
$message = 'Nous avons fait quelquechose lors de la dernière requête';
$flashMessenger->addMessage($message);
]]></programlisting>
            </listitem>
            <listitem>
                <para>
                    L'utilisation de la fonctionnalité <methodname>__get()</methodname> du gestionnaire
                    d'aide et récupérez l'aide comme si elle était une propriété membre du
                    gestionnaire :
                </para>
                <programlisting language="php"><![CDATA[
$flashMessenger = $this->_helper->FlashMessenger;
$message = 'Nous avons fait quelquechose lors de la dernière requête';
$flashMessenger->addMessage($message);
]]></programlisting>
            </listitem>
            <listitem>
                <para>
                    Enfin, la plupart des aides d'action implémente la méthode
                    <methodname>direct()</methodname> qui va appeler une méthode spécifique par défaut dans
                    l'aide. Dans l'exemple de <code>FlashMessenger</code>, ceci appelle
                    <methodname>addMessage()</methodname>&#160;:
                </para>
                <programlisting language="php"><![CDATA[
$message = 'Nous avons fait quelquechose lors de la dernière requête';
$this->_helper->FlashMessenger($message);
]]></programlisting>
            </listitem>
        </itemizedlist>

        <note>
            <para>Tous les exemples ci-dessus sont équivalents.</para>
        </note>

        <para>
            Vous pouvez vouloir aussi instancier les aides explicitement. Vous pourriez avoir
            besoin de ceci si vous utilisez l'aide hors du contexte du contrôleur d'action, ou si
            vous souhaitez fournir une aide au gestionnaire d'aides à utiliser pour une action
            quelconque. L'instanciation se fait comme toute autre classe <acronym>PHP</acronym>.
        </para>
    </sect2>

    <sect2 id="zend.controller.actionhelper.broker">
        <title>Le gestionnaire d'aide (Broker)</title>

        <para>
            <classname>Zend_Controller_Action_HelperBroker</classname> gère les détails de
            l'enregistrement des objets d'aide et les chemins de ces aides, ainsi que la
            récupération des aides à la demande.
        </para>

        <para>
            Pour enregistrer une aide dans le gestionnaire, utilisez
            <code>addHelper</code>&#160;:
        </para>

        <programlisting language="php"><![CDATA[
Zend_Controller_Action_HelperBroker::addHelper($helper);
]]></programlisting>

        <para>
            Bien sûr, instancier et fournir des aides au gestionnaire est coûteux en temps et
            en ressource donc deux méthodes existent pour automatiser les choses légèrement&#160;:
            <methodname>addPrefix()</methodname> et <methodname>addPath()</methodname>.
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>addPrefix()</methodname> prend un préfixe de classe et l'utilise pour
                    déterminer le chemin des dossiers dans lesquels les classes d'aides ont été
                    définies. Ceci suppose que le préfixe de la classe respecte la convention de
                    nommage de Zend Framework.
                </para>
                <programlisting language="php"><![CDATA[
// Ajoute les aides préfixées Mes_Action_Helpers dans Mes/Action/Helpers/
Zend_Controller_Action_HelperBroker::addPrefix('Mes_Action_Helpers');
]]></programlisting>
            </listitem>
            <listitem>
                <para>
                    <methodname>addPath()</methodname> prend un répertoire en premier argument et un
                    préfixe de classe en second (par défaut réglé à
                    "<classname>Zend_Controller_Action_Helper</classname>"). Ceci vous permet de
                    faire correspondre vos propres préfixes de classe à vos dossiers
                    spécifiques.
                </para>
                <programlisting language="php"><![CDATA[
// Ajoute les aides préfixées avec Aide dans Plugins/Aides/
Zend_Controller_Action_HelperBroker::addPath('./Plugins/Aides', 'Aide');
]]></programlisting>
            </listitem>
        </itemizedlist>

        <para>
            Puisque ces méthodes sont statiques, elles peuvent être appelées en tout point du
            déroulement du contrôleur pour ajouter dynamiquement les aides nécessaires.
        </para>

        <para>
            En interne, le gestionnaire d'aide utilise
            <link linkend="zend.loader.pluginloader">une instance de PluginLoader</link>pour
            conserver les chemins. Vous pouvez récupérer le PluginLoader en utilisant la méthode
            statique <methodname>getPluginLoader()</methodname>, ou alternativement, injecter une instance
            personnalisée de PluginLoader en utilisant <methodname>setPluginLoader()</methodname>.
        </para>

        <para>
            Pour déterminer si une aide existe dans le gestionnaire d'aide, utilisez
            <methodname>hasHelper($name)</methodname>, où <varname>$name</varname> est le nom raccourci de l'aide
            (sans le préfixe)&#160;:
        </para>

        <programlisting language="php"><![CDATA[
// Vérifie si l'aide 'redirector' est enregistrée dans le gestionnaire :
if (Zend_Controller_Action_HelperBroker::hasHelper('redirector')) {
    echo 'L\'aide Redirector est enregistrée';
}
]]></programlisting>

        <para>
            Il existe aussi deux méthodes statiques pour récupérer les aides issues du
            gestionnaire d'aide : <methodname>getExistingHelper()</methodname> et
            <methodname>getStaticHelper()</methodname>. <methodname>getExistingHelper()</methodname> récupérera une aide
            seulement si elle a précédemment été invoquée par ou explicitement enregistrée dans le
            gestionnaire d'aides; la méthode lèvera une exception sinon.
            <methodname>getStaticHelper()</methodname> réalise la même chose que
            <methodname>getExistingHelper()</methodname>, mais tentera d'instancier l'aide si elle n'a pas déjà
            été enregistrée dans la pile des aides. <methodname>getStaticHelper()</methodname> est un bon choix
            pour récupérer les aides que vous voulez configurer.
        </para>

        <para>
            Les deux méthodes prennent un unique paramètre, <varname>$name</varname>, qui est le
            nom court de l'aide (c'est-à-dire sans le préfixe).
        </para>

        <programlisting language="php"><![CDATA[
// Vérifie si l'aide 'redirector' est enregistrée dans le gestionnaire,
// et l'extrait :
if (Zend_Controller_Action_HelperBroker::hasHelper('redirector')) {
    $redirector =
        Zend_Controller_Action_HelperBroker::getExistingHelper('redirector');
}

// Ou, simplement le récupère, sans se soucier s'il a ou non été
// enregistré précédemment :
$redirector =
    Zend_Controller_Action_HelperBroker::getStaticHelper('redirector');
}
]]></programlisting>

        <para>
            Enfin, pour effacer une aide enregistrée du gestionnaire, utilisez
            <methodname>removeHelper($name)</methodname>, où <varname>$name</varname> est le nom raccourci de l'aide
            (sans le préfixe)&#160;:
        </para>

        <programlisting language="php"><![CDATA[
// Effacement conditionnel de l'aide 'redirector' du gestionnaire :
if (Zend_Controller_Action_HelperBroker::hasHelper('redirector')) {
    Zend_Controller_Action_HelperBroker::removeHelper('redirector')
}
]]></programlisting>
    </sect2>

    <sect2 id="zend.controller.actionhelper.stockhelpers">
        <title>Aides d'action intégrées</title>

        <para>
            Zend Framework inclue plusieurs aides d'action par défaut&#160;:
            <code>AutoComplete</code> pour des réponses automatiques à des auto-complétions <acronym>AJAX</acronym> ;
            <code>ContextSwitch</code> et <code>AjaxContext</code> pour distribuer des formats de
            réponse alternatifs pour vos actions ; <code>FlashMessenger</code> pour gérer des
            messages entre les sessions ; <code>Redirector</code>, qui fournit différentes
            implémentations pour rediriger vers des pages internes ou externes à votre application
            ; et <code>ViewRenderer</code> pour automatiser le processus de paramétrage de vos
            objets de vues dans votre contrôleur et du rendu de ces vues.
        </para>

        <xi:include href="Zend_Controller-ActionHelpers-ActionStack.xml" />
        <xi:include href="Zend_Controller-ActionHelpers-AutoComplete.xml" />
        <xi:include href="Zend_Controller-ActionHelpers-ContextSwitch.xml" />
        <xi:include href="Zend_Controller-ActionHelpers-FlashMessenger.xml" />
        <xi:include href="Zend_Controller-ActionHelpers-Json.xml" />
        <xi:include href="Zend_Controller-ActionHelpers-Redirector.xml" />
        <xi:include href="Zend_Controller-ActionHelpers-ViewRenderer.xml" />
    </sect2>

    <sect2 id="zend.controller.actionhelper.writingyourown">
        <title>Écrire vos propres aides</title>

        <para>
            Les aides d'action étendent
            <classname>Zend_Controller_Action_Helper_Abstract</classname>, une classe abstraite qui
            fournit l'interface basique et les fonctionnalités requises par le gestionnaire
            d'aides. Ceci inclue les méthodes suivantes&#160;:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>setActionController()</methodname> est utilisée pour paramétrer le
                    contrôleur d'action courant.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>init()</methodname>, déclenchée par le gestionnaire d'aides à
                    l'instanciation, peut être utilisée pour déclencher l'initialisation dans
                    l'aide&#160;; ceci peut être pratique pour remettre dans l'état initial quand de
                    multiples contrôleurs utilisent la même aide dans des actions
                    enchaînées.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>preDispatch()</methodname> est déclenchée avant la distribution d'une
                    action.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>postDispatch()</methodname> est déclenchée quand une action a été
                    distribuée - même si un plugin <methodname>preDispatch()</methodname> a évité l'action.
                    Principalement utile pour le nettoyage.
                </para>
            </listitem>
            <listitem>
                <para><methodname>getRequest()</methodname> récupère l'objet de requête courant.</para>
            </listitem>
            <listitem>
                <para><methodname>getResponse()</methodname> récupère l'objet de réponse courant.</para>
            </listitem>
            <listitem>
                <para>
                    <methodname>getName()</methodname> récupère le nom de l'aide. Elle récupère la
                    portion du nom de la classe qui suit le dernier tiret bas ("_"), ou le nom de
                    la classe entier sinon. Pour exemple, si la classe est nommée
                    <classname>Zend_Controller_Action_Helper_Redirector</classname>, elle retourne
                    <code>Redirector</code>&#160;; une classe nommée <code>FooMessage</code>
                    retournera <code>FooMessage</code>.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Vous pouvez optionnellement inclure une méthode <methodname>direct()</methodname> dans votre
            classe d'aide. Si définie, ceci vous permet de traiter l'aide comme une méthode du
            gestionnaire, dans le but de faciliter un usage unique de l'aide. Pour exemple, l'aide
            <link linkend="zend.controller.actionhelpers.redirector">Redirector</link>définit
            <methodname>direct()</methodname> comme un alias de <methodname>goto()</methodname>, vous permettant d'utiliser
            l'aide comme ceci&#160;:
        </para>

        <programlisting language="php"><![CDATA[
// Redirige vers /blog/view/item/id/42
$this->_helper->redirector('item', 'view', 'blog', array('id' => 42));
]]></programlisting>

        <para>
            En interne, la méthode <methodname>__call()</methodname> du gestionnaire d'aides cherche une
            aide nommée <code>redirector</code>, puis vérifie si cette aide possède une méthode
            <methodname>direct()</methodname>, et enfin appelle cette méthode avec les arguments
            fournis.
        </para>

        <para>
            Une fois que vous avez créé vos propres classes d'aide, vous pouvez en fournir
            l'accès comme décrit dans les sections ci-dessus.
        </para>
    </sect2>
</sect1>