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

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 24249 -->
<!-- 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&#160;/&#160;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&#160;:
                </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 <emphasis>FlashMessenger</emphasis>,
                    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
            <methodname>addHelper()</methodname>&#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;:
            <emphasis>AutoComplete</emphasis> pour des réponses automatiques à des auto-complétions
            <acronym>AJAX</acronym>&#160;; <emphasis>ContextSwitch</emphasis> et
            <emphasis>AjaxContext</emphasis> pour distribuer des formats de réponse alternatifs
            pour vos actions ; <emphasis>FlashMessenger</emphasis> pour gérer des
            messages entre les sessions ; <emphasis>Json</emphasis> pour encoder et envoyer des
            réponses <acronym>JSON</acronym>&#160;; <emphasis>Redirector</emphasis>, qui fournit
            différentes implémentations pour rediriger vers des pages internes ou externes à votre
            application&#160;; et <emphasis>ViewRenderer</emphasis> 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
                    <emphasis>Redirector</emphasis>&#160;; une classe nommée
                    <emphasis>FooMessage</emphasis> retournera elle-même.
                </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 <emphasis>redirector</emphasis>, 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>