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

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 24249 -->
<!-- Reviewed: no -->
<sect3 id="zend.controller.actionhelpers.viewrenderer">
    <title>ViewRenderer</title>

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

        <para>
            L'aide <emphasis>ViewRenderer</emphasis> apporte les comportements suivants&#160;:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    Élimine le besoin d'instancier un objet de vue dans ses contrôleurs. Ceci
                    devient automatique.
                </para>
            </listitem>
            <listitem>
                <para>
                    Configure automatiquement les chemins vers les scripts de vue, les aides,
                    et les filtres, en se basant sur le module actuel et associe le nom du module
                    comme préfixe de classe pour les aides et les filtres.
                </para>
            </listitem>
            <listitem>
                <para>
                    Créer un objet de vue général accessible pour tous les contrôleurs et
                    donc pour toutes les actions disptachées.
                </para>
            </listitem>
            <listitem>
                <para>
                    Autorise le développeur à personnaliser les options de rendu de la vue.
                </para>
            </listitem>
            <listitem>
                <para>Donne la possibilité de rendre automatiquement un script de vue.</para>
            </listitem>
            <listitem>
                <para>
                    Donne accès aux paramètres configurant le chemin de base (base path) et
                    le chemin des scripts (script path), de la vue.
                </para>
            </listitem>
        </itemizedlist>

        <note>
            <para>
                Su vous utilisez <methodname>_forward()</methodname>,
                <methodname>redirect()</methodname>, ou <methodname>render()</methodname>
                manuellement, le rendu automatique sera annulé car
                <emphasis>ViewRenderer</emphasis> saura que vous prenez la main.
            </para>
        </note>

        <note>
            <para>
                Le <emphasis>ViewRenderer</emphasis> est activé par défaut dans le contrôleur
                frontal. Pour le désactiver, utilisez le paramètre
                <emphasis>noViewRenderer</emphasis>
                (<command>$front-&gt;setParam('noViewRenderer', true);</command>) ou retirez
                l'objet du gestionnaire d'aides
                (<methodname>Zend_Controller_Action_HelperBroker::removeHelper('viewRenderer')</methodname>).
            </para>
            <para>
                Si vous voulez modifier un paramètre du <emphasis>ViewRenderer</emphasis> avant la
                distribution du contrôleur frontal, il existe deux moyens&#160;:
            </para>
            <itemizedlist>
                <listitem>
                    <para>
                        Instanciez et enregistrez votre propre objet
                        <emphasis>ViewRenderer</emphasis> et passez le au gestionnaire
                        d'aides&#160;:
                    </para>
                    <programlisting language="php"><![CDATA[
$viewRenderer = new Zend_Controller_Action_Helper_ViewRenderer();
$viewRenderer->setView($view)
             ->setViewSuffix('php');
Zend_Controller_Action_HelperBroker::addHelper($viewRenderer);
]]></programlisting>
                </listitem>
                <listitem>
                    <para>
                        Initialisez et/ou récupérez l'objet
                        <emphasis>ViewRenderer</emphasis> via le gestionnaire d'aides&#160;:
                    </para>
                    <programlisting language="php"><![CDATA[
$viewRenderer =
    Zend_Controller_Action_HelperBroker::getStaticHelper('viewRenderer');
$viewRenderer->setView($view)
             ->setViewSuffix('php');
]]></programlisting>
                </listitem>
            </itemizedlist>
        </note>
    </sect4>

    <sect4 id="zend.controller.actionhelper.viewrenderer.api">
        <title>API</title>

        <para>
            L'usage le plus banal consiste à instancier et passer l'objet
            <emphasis>ViewRenderer</emphasis> au gestionnaire d'aides. La manière la plus simple
            est d'utiliser la méthode statique <methodname>getStaticHelper()</methodname>
            du gestionnaire, qui s'occupe de tout ceci en une passe&#160;:
        </para>

        <programlisting language="php"><![CDATA[
Zend_Controller_Action_HelperBroker::getStaticHelper('viewRenderer');
]]></programlisting>

        <para>
            La première action demandée déclenche l'instanciation de l'objet de vue par le
            <emphasis>ViewRenderer</emphasis>. A chaque instanciation de contrôleur, la
            méthode <methodname>init()</methodname> de l'objet
            <emphasis>ViewRenderer</emphasis> est appelée. Elle va configurer la vue et appeler
            <methodname>addScriptPath()</methodname> avec un chemin relatif au dossier courant.
            Ceci a pour effet de "namespacer" toutes les aides et les filtres de vue pour le
            module en cours.
        </para>

        <para>
            A chaque <methodname>postDispatch()</methodname> d'action,
            <methodname>render()</methodname> est appelée.
        </para>

        <para>Voici un exemple&#160;:</para>

        <programlisting language="php"><![CDATA[
// Bar controller , module foo :
class Foo_BarController extends Zend_Controller_Action
{
    // Rend bar/index.phtml par défaut; rien à faire c'est automatique
    public function indexAction()
    {
    }

    // Rend bar/populate.phtml avec une variable 'foo' à la valeur 'bar'.
    // l'objet de vue est défini dans le preDispatch(), il est donc
    // accessible.
    public function populateAction()
    {
        $this->view->foo = 'bar';
    }
}

...

// Dans un des scripts de vue :
$this->foo(); // appelle Foo_View_Helper_Foo::foo()
]]></programlisting>

        <para>
            Le <emphasis>ViewRenderer</emphasis> définit de même des accesseurs pour configurer la
            vue qu'il encapsule&#160;:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>setView($view)</methodname> Passage de l'objet de vue au
                    <emphasis>ViewRenderer</emphasis>. Il devient accessible comme une propriété
                    publique de l'objet&#160;: <varname>$view</varname>.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>setNeverRender($flag = true)</methodname> peut être utilisée pour
                    désactiver le rendu automatique de la vue dans tous les contrôleurs.
                    Si réglé à <constant>TRUE</constant>
                    <methodname>postDispatch()</methodname> ne va pa automatiquement appeler
                    <methodname>render()</methodname> dans le contrôleur courant.
                    <methodname>getNeverRender()</methodname> retourne ce paramètre.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>setNoRender($flag = true)</methodname> peut être utilisée pour
                    désactiver le rendu automatique de la vue dans le contrôleur actuel.
                    Si réglé à <constant>TRUE</constant>
                    <methodname>postDispatch()</methodname> ne va pa automatiquement appeler
                    <methodname>render()</methodname> dans le contrôleur courant, mais
                    <methodname>preDispatch()</methodname> réactive le paramètre pour l'action
                    suivante. <methodname>getNoRender()</methodname> retourne cette option.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>setNoController($flag = true)</methodname> est utilisée pour
                    spécifier à <methodname>render()</methodname> de ne pas chercher le script
                    de vue dans le sous répertoire après le contrôleur (correspondant à l'action).
                    Par défaut, cette recherche est effectuée.
                    <methodname>getNoController()</methodname> retourne ce paramètre.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>setNeverController($flag = true)</methodname> fonctionne de manière
                    similaire à <methodname>setNoController()</methodname>, mais pour tous les
                    contrôleurs.<methodname>getNeverController()</methodname> est l'autre
                    accesseur.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>setScriptAction($name)</methodname> peut être utilisée pour
                    spécifier le script de vue d'une action à rendre. <varname>$name</varname>
                    doit être le nom de l'action sans le suffixe (et sans le nom du contrôleur
                    sauf si <emphasis>noController</emphasis> a été activé). Si vous n'utilisez
                    pas cette méthode elle cherchera le script de vue correspondant au nom de
                    l'action en cours (issue de l'objet de requête).
                    <methodname>getScriptAction()</methodname> retourne la valeur actuelle de ce
                    paramètre.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>setResponseSegment($name)</methodname> dit dans quel segment de la
                    réponse rendre le script. Par défaut, la vue est rendue dans le segment par
                    défaut. <methodname>getResponseSegment()</methodname> retourne cette valeur.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>initView($path, $prefix, $options)</methodname> doit être appelée
                    pour configurer la vue : son "base path", le préfixe de classe pour les filtres
                    et aides, et des options du <emphasis>ViewRenderer</emphasis> matérialisées
                    par&#160;: <emphasis>neverRender</emphasis>, <emphasis>noRender</emphasis>,
                    <emphasis>noController</emphasis>, <emphasis>scriptAction</emphasis>, et
                    <emphasis>responseSegment</emphasis>.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>setRender($action = null, $name = null, $noController =
                    false)</methodname> vous permet de spécifier les paramètres
                    <emphasis>scriptAction</emphasis>, <emphasis>responseSegment</emphasis>, et
                    <emphasis>noController</emphasis> en une fois.
                    <methodname>direct()</methodname> est un alias qui permet un appel rapide
                    depuis le contrôleur&#160;:
                </para>
                <programlisting language="php"><![CDATA[
// Rend 'foo' au lieu du script correspondant à l'action courante
$this->_helper->viewRenderer('foo');

// rend form.phtml dans le segment 'html' de la réponse sans utiliser le
// sous repertoire contrôleur pour chercher le script de vue :
$this->_helper->viewRenderer('form', 'html', true);
]]></programlisting>
                <note>
                    <para>
                        <methodname>setRender()</methodname> et <methodname>direct()</methodname>
                        ne rendent pas un script de vue à proprement parler, mais elles notifient
                        au <methodname>postDispatch()</methodname> et
                        <methodname>render()</methodname> sera utilisée pour le faire.
                    </para>
                </note>
            </listitem>
        </itemizedlist>

        <para>
            Le constructeur de <emphasis>ViewRenderer</emphasis> accepte aussi un objet de vue et
            un tableau d'options, de la même manière que <methodname>initView()</methodname>&#160;:
        </para>

        <programlisting language="php"><![CDATA[
$view    = new Zend_View(array('encoding' => 'UTF-8'));
$options = array('noController' => true, 'neverRender' => true);
$viewRenderer =
    new Zend_Controller_Action_Helper_ViewRenderer($view, $options);
]]></programlisting>

        <para>
            Il est aussi possible de personnaliser les chemins utilisés pour déterminer le
            base path (chemin de base) de la vue ainsi que le script path (chemin vers les scripts
            de vue). Des méthodes le permettent, utilisez les options suivantes avec&#160;:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <emphasis>:moduleDir</emphasis> représente le module courant (par convention le
                    dossier parent au dossier contrôleur).
                </para>
            </listitem>
            <listitem>
                <para><emphasis>:module</emphasis> pointe vers le module actuel.</para>
            </listitem>
            <listitem>
                <para><emphasis>:controller</emphasis> pointe vers le contrôleur actuel.</para>
            </listitem>
            <listitem>
                <para><emphasis>:action</emphasis> représente l'action actuellement traitée.</para>
            </listitem>
            <listitem>
                <para>
                    <emphasis>:suffix</emphasis> est utilisée pour le suffixe du script de vue.
                    <methodname>setViewSuffix()</methodname> permet aussi de le modifier.
                </para>
            </listitem>
        </itemizedlist>

        <para>Toutes ces options s'utilisent avec les méthodes ci-après&#160;:</para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>setViewBasePathSpec($spec)</methodname> vous permet de changer le
                    dossier donnant accès aux dossiers de la vue&#160;: le base path. Par défaut
                    il s'agit de <filename>:moduleDir/views</filename>. L'accesseur de récupération
                    est <methodname>getViewBasePathSpec()</methodname>.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>setViewScriptPathSpec($spec)</methodname> : une fois dans le base
                    path, le rendu cherche le script de vue dans le script path, que cette méthode
                    permet de définir. La valeur par défaut est
                    <filename>:controller/:action.:suffix</filename> et
                    l'autre accesseur est <methodname>getViewScriptPathSpec()</methodname>.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>setViewScriptPathNoControllerSpec($spec)</methodname> Une fois
                    dans le base path, si <emphasis>noController</emphasis> est activé, le rendu
                    cherche le script de vue dans le chemin que cette méthode permet de définir.
                    La valeur par défaut est <filename>:action.:suffix</filename> et l'autre
                    accesseur est <methodname>getViewScriptPathNoControllerSpec()</methodname>.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            <emphasis>ViewRenderer</emphasis> utilise un inflecteur&#160;:
            <link linkend="zend.filter.inflector">Zend_Filter_Inflector</link>, pour résoudre les
            options de chemin, en chemins réels. Pour une personnalisation maximale, vous pouvez
            interagir avec cet inflecteur à l'aide des méthodes suivantes&#160;:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>getInflector()</methodname> retourne l'inflecteur. Si aucun
                    n'existe, <emphasis>ViewRenderer</emphasis> en crée un avec des options par
                    défaut.
                </para>
                <para>
                    Par défaut, les règles de l'inflecteur sont statiques autant pour le
                    suffixe et le répertoire module, que pour la cible. Ceci permet au
                    <emphasis>ViewRenderer</emphasis> de modifier ces valeurs dynamiquement.
                </para>
            </listitem>
            <listitem>
                <para>
                    <methodname>setInflector($inflector, $reference)</methodname> peut être
                    utilisée pour passer son propre inflecteur à
                    <emphasis>ViewRenderer</emphasis>. Si <varname>$reference</varname> est à
                    <constant>TRUE</constant>, alors le suffixe, le répertoire du module et
                    la cible seront affectés en fonction des propriétés de
                    <emphasis>ViewRenderer</emphasis>.
                </para>
            </listitem>
        </itemizedlist>

        <note>
            <title>Règles de résolution par défaut</title>
            <para>
                Le <emphasis>ViewRenderer</emphasis> utilise certaines règles par défaut pour
                chercher ses scripts de vue, voyez plutôt&#160;:
            </para>
            <itemizedlist>
                <listitem>
                    <para>
                        <emphasis>:module</emphasis>&#160;: casseMélangée et motsEnNotationCamel
                        qui deviennent des mots séparés par des tirets, et en minuscules.
                        "FooBarBaz" devient "foo-bar-baz".
                    </para>
                    <para>
                        En interne, l'inflecteur utilise les filtres
                        <classname>Zend_Filter_Word_CamelCaseToDash</classname> et
                        <classname>Zend_Filter_StringToLower</classname>.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <emphasis>:controller</emphasis>&#160;: casseMélangée et
                        motsEnNotationCamel qui deviennent des mots séparés par des tirets&#160;;
                        les tirets bas eux, se transforment en séparateur de dossier et tout est
                        passé en minuscules. "<classname>FooBar</classname>" devient
                        "foo-bar"&#160;; "<classname>FooBar_Admin</classname>"
                        devient "<filename>foo-bar/admin</filename>".
                    </para>
                    <para>
                        En interne, l'inflecteur utilise les filtres
                        <classname>Zend_Filter_Word_CamelCaseToDash</classname>,
                        <classname>Zend_Filter_Word_UnderscoreToSeparator</classname>, et
                        <classname>Zend_Filter_StringToLower</classname>.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <emphasis>:action</emphasis>&#160;: casseMélangée et motsEnNotationCamel
                        qui se transforment en mots séparés par des tirets, minuscules. Les
                        caractères non alphanumériques deviennent des tirets. "fooBar" devient
                        "foo-bar"&#160;; "foo-barBaz" devient "foo-bar-baz".
                    </para>
                    <para>
                        Pour ceci, l'inflecteur interne utilise les filtres
                        <classname>Zend_Filter_Word_CamelCaseToDash</classname>,
                        <classname>Zend_Filter_PregReplace</classname>, et
                        <classname>Zend_Filter_StringToLower</classname>.
                    </para>
                </listitem>
            </itemizedlist>
        </note>

        <para>
            Enfin, l'<acronym>API</acronym> de <emphasis>ViewRenderer</emphasis> vous propose
            aussi des méthodes pour déterminer les scripts de vue, et rendre la vue. Celles-ci
            se décomposent en :
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <methodname>renderScript($script, $name)</methodname> va vous permettre de
                    spécifier pleinement le script de vue à rendre, et éventuellement un nom de
                    segment de réponse dans lequel rendre. <emphasis>ViewRenderer</emphasis>
                    s'attend à un paramètre <varname>$script</varname> représentant un chemin
                    complet vers un script de vue, telle que la méthode de la vue
                    <methodname>render()</methodname> l'attend.
                </para>
                <note>
                    <para>
                        Une fois rendue, la vue utilise <emphasis>noRender</emphasis> pour éviter
                        un double rendu automatisé.
                    </para>
                </note>
                <note>
                    <para>
                        Par défaut, <methodname>Zend_Controller_Action::renderScript()</methodname>
                        est un proxy vers la méthode <methodname>renderScript()</methodname> de
                        <emphasis>ViewRenderer</emphasis>.
                    </para>
                </note>
            </listitem>
            <listitem>
                <para>
                    <methodname>getViewScript($action, $vars)</methodname> récupère le chemin du
                    script de vue en se basant sur les paramètres $action et $vars.
                    <varname>$vars</varname> peut contenir "moduleDir", "module", "controller",
                    "action", et "suffix"), sinon les valeurs de la requête actuelle seront
                    utilisées.
                </para>
                <para>
                    <methodname>getViewScript()</methodname> utilisera
                    <emphasis>viewScriptPathSpec</emphasis> ou
                    <emphasis>viewScriptPathNoControllerSpec</emphasis> selon le paramètre
                    <emphasis>noController</emphasis>.
                </para>
                <para>
                    Les délimiteurs apparaissant dans les modules, contrôleurs ou actions seront
                    remplacés par des tirets ("-"). Ainsi pour un contrôleur
                    "<command>foo.bar</command>" et une action "<command>baz:bat</command>", il
                    résultera un chemin de vue "<filename>foo-bar/baz-bat.phtml</filename>".
                </para>
                <note>
                    <para>
                        Par défaut <methodname>Zend_Controller_Action::getViewScript()</methodname>
                        est un proxy vers la méthode <methodname>getViewScript()</methodname> de
                        <emphasis>ViewRenderer</emphasis>.
                    </para>
                </note>
            </listitem>
            <listitem>
                <para>
                    <methodname>render($action, $name, $noController)</methodname> a beaucoup de
                    responsabilités&#160;: d'abord, elle vérifie si <varname>$name</varname> ou
                    <varname>$noController</varname> lui ont été passés, si c'est le cas, elle
                    configure correctement les paramètres <code>responseSegment</code> et
                    <code>noController</code> dans le ViewRenderer. Elle passe ensuite
                    <varname>$action</varname>, si spécifié, à
                    <methodname>getViewScript()</methodname>. Enfin, elle
                    passe le script de vue calculé à <methodname>renderScript()</methodname>.
                </para>
                <note>
                    <para>
                        Attention aux effets secondaires avec
                        <methodname>render()</methodname>&#160;: les valeurs segment de réponse,
                        et <code>noController</code> vont persister dans l'objet ViewRenderer.
                        De plus, <methodname>noRender()</methodname> va être appelée.
                    </para>
                </note>
                <note>
                    <para>
                        Par défaut, <methodname>Zend_Controller_Action::render()</methodname>
                        est un proxy vers <methodname>render()</methodname> de
                        <emphasis>ViewRenderer</emphasis>.
                    </para>
                </note>
            </listitem>
            <listitem>
                <para>
                    <methodname>renderBySpec($action, $vars, $name)</methodname> vous fournit le
                    moyen de passer des paramètres de spécification pour le dossier de script de
                    vue. Cette méthode passe <varname>$action</varname> et <varname>$vars</varname>
                    à <methodname>getScriptPath()</methodname>, pour en déduire un chemin qu'elle
                    envoie alors avec <varname>$name</varname> à
                    <methodname>renderScript()</methodname>.
                </para>
            </listitem>
        </itemizedlist>
    </sect4>

    <sect4 id="zend.controller.actionhelper.viewrenderer.basicusage">
        <title>Exemples</title>

        <example id="zend.controller.actionhelper.viewrenderer.basicusage.example-1">
            <title>Usage de base</title>

            <para>
                L'utilisation la plus basique consiste à initialiser ou et enregistrer un
                objet <emphasis>ViewRenderer</emphasis> dans le gestionnaire d'aides (helper
                broker), et ensuite lui passer des variables dans vos contrôleurs.
            </para>

            <programlisting language="php"><![CDATA[
// Dans le fichier de démarrage :
Zend_Controller_Action_HelperBroker::getStaticHelper('viewRenderer');

...

// 'foo' module, contrôleur 'bar' :
class Foo_BarController extends Zend_Controller_Action
{
    // Rend bar/index.phtml par défaut, rien à faire
    public function indexAction()
    {
    }

    // Rend bar/populate.phtml avec la variable 'foo' à la valeur 'bar'.
    // L'objet de vue est rendu disponible en preDispatch().
    public function populateAction()
    {
        $this->view->foo = 'bar';
    }

    // Ne rend rien, car on demande un nouveau jeton de distribution
    public function bazAction()
    {
        $this->_forward('index');
    }

    // Ne rend rien, une redirection est demandée
    public function batAction()
    {
        $this->_redirect('/index');
    }
}
]]></programlisting>
        </example>

        <note>
            <title>
                Conventions de noms&#160;: délimiteurs de mots dans les noms de contrôleur et
                d'action
            </title>
            <para>
                Si les noms de votre contrôleur ou de votre action sont composés de plusieurs
                mots, le distributeur s'attend à ce qu'ils soient séparés par des caractères bien
                définis, dans l'<acronym>URL</acronym>. Le <emphasis>ViewRenderer</emphasis> les
                transforme alors en '/' pour les chemins, ou tirets '-' pour les mots. Ainsi, un
                appel à <filename>/foo.bar/baz.bat</filename> distribuera
                <methodname>FooBarController::bazBatAction()</methodname> dans
                <filename>FooBarController.php</filename>, et ceci rendra
                <filename>foo-bar/baz-bat.phtml</filename>. Un appel à
                <filename>/bar_baz/baz-bat</filename> distribuera vers
                <methodname>Bar_BazController::bazBatAction()</methodname> dans
                <filename>Bar/BazController.php</filename> (notez la séparation du chemin),
                et rend <filename>bar/baz/baz-bat.phtml</filename>.
            </para>
            <para>
                Notez dans le second exemple, le module est celui par défaut, mais comme un
                séparateur de chemin (tiret bas ou "_") est donné, alors le contrôleur distribué
                devient <classname>Bar_BazController</classname>, dans
                <filename>Bar/BazController.php</filename>.
            </para>
        </note>

        <example id="zend.controller.actionhelper.viewrenderer.basicusage.example-2">
            <title>Désactivation du rendu automatique</title>

            <para>
                Il peut être nécessaire dans certains cas de désactiver manuellement le rendu
                automatique de vue effectué par ViewRenderer. Par exemple, si le contrôleur doit
                retourner une sortie spéciale, comme <acronym>XML</acronym> ou
                <acronym>JSON</acronym>. Deux options s'offrent à vous :
                <methodname>setNeverRender()</methodname>) et
                <methodname>setNoRender()</methodname>.
            </para>

            <programlisting language="php"><![CDATA[
// Baz controller class, bar module :
class Bar_BazController extends Zend_Controller_Action
{
    public function fooAction()
    {
        // Ne rend pas automatiquement cette action
        $this->_helper->viewRenderer->setNoRender();
    }
}

// Bat controller class, bar module :
class Bar_BatController extends Zend_Controller_Action
{
    public function preDispatch()
    {
        // Ne rend plus aucune action de ce contrôleur
        $this->_helper->viewRenderer->setNoRender();
    }
}
]]></programlisting>
        </example>

        <note>
            <para>
                Utiliser <methodname>setNeverRender()</methodname>), pour désactiver totalement
                le rendu automatique de vue vous fera perdre un des avantages majeur de
                <emphasis>ViewRenderer</emphasis>.
            </para>
        </note>

        <example id="zend.controller.actionhelper.viewrenderer.basicusage.example-3">
            <title>Choix d'un script de vue différent</title>

            <para>
                Il peut arriver que vous éprouviez le besoin de rendre un script de vue
                différent de celui correspondant à l'action en cours de distribution. Par exemple,
                un contrôleur qui possède deux actions ajout et édition, qui sont susceptibles
                toutes les deux de rendre le même script de vue. Utilisez alors
                <methodname>setScriptAction()</methodname>, <methodname>setRender()</methodname>,
                ou appelez directement l'aide ViewRenderer qui invoquera
                <methodname>setRender()</methodname>&#160;:
            </para>

            <programlisting language="php"><![CDATA[
// Bar controller class, foo module :
class Foo_BarController extends Zend_Controller_Action
{
    public function addAction()
    {
        // Rend 'bar/form.phtml' plutôt que 'bar/add.phtml'
        $this->_helper->viewRenderer('form');
    }

    public function editAction()
    {
        // Rend 'bar/form.phtml' au lieu de 'bar/edit.phtml'
        $this->_helper->viewRenderer->setScriptAction('form');
    }

    public function processAction()
    {
        // un peu de validation...
        if (!$valid) {
            // Rend 'bar/form.phtml' à la place de 'bar/process.phtml'
            $this->_helper->viewRenderer->setRender('form');
            return;
        }

        // continue le processus...
    }
}
]]></programlisting>
        </example>

        <example id="zend.controller.actionhelper.viewrenderer.basicusage.example-4">
            <title>Modification de l'objet de vue</title>

            <para>
                Si vous désirez modifier l'objet de vue absorbé par
                <code>ViewRenderer</code>, pour par exemple ajouter un chemin vers des aides
                spécifique, ou spécifier l'encodage, vous pourriez par exemple récupérer l'objet de
                vue depuis le <emphasis>ViewRenderer</emphasis>, ou dans un contrôleur.
            </para>

            <programlisting language="php"><![CDATA[
// Bar controller class, foo module :
class Foo_BarController extends Zend_Controller_Action
{
    public function preDispatch()
    {
        // change l'encodage de la vue
        $this->view->setEncoding('UTF-8');
    }

    public function bazAction()
    {
        // Récupère l'objet de vue, et lui passe la fonction
        // d'2chappement 'htmlspecialchars'
        $view = $this->_helper->viewRenderer->view;
        $view->setEscape('htmlspecialchars');
    }
}
]]></programlisting>
        </example>
    </sect4>

    <sect4 id="zend.controller.actionhelper.viewrenderer.advancedusage">
        <title>Utilisation avancée</title>

        <example id="zend.controller.actionhelper.viewrenderer.advancedusage.example-1">
            <title>Changement des spécifications de dossier</title>

            <para>
                Dans certains cas, il peut être nécessaire d'utiliser un chemin absolu, fixe.
                Par exemple si vous ne donnez accès à vos graphistes qu'à un seul dossier, en
                utilisant un moteur de template tel que
                <ulink url="http://smarty.php.net/">Smarty</ulink>.
            </para>

            <para>
                Pour ceci, imaginons que le base path soit fixé à
                "<filename>/opt/vendor/templates</filename>", et
                que vous voulez que vos scripts de vues soit référencés par
                "<filename>:moduleDir/:controller/:action.:suffix</filename>"; si le paramètre
                <emphasis>noController</emphasis> est activé, vous désirez utiliser le dossier
                plus haut "<filename>:action.:suffix</filename>". Enfin,
                vous désirez un suffixe en "tpl"&#160;:
            </para>

            <programlisting language="php"><![CDATA[
/**
 * Dans le fichier de démarrage :
 */

// Une implémentation personnalisée de la vue
$view = new ZF_Smarty();

$viewRenderer = new Zend_Controller_Action_Helper_ViewRenderer($view);
$viewRenderer->setViewBasePathSpec('/opt/vendor/templates')
             ->setViewScriptPathSpec(':module/:controller/:action.:suffix')
             ->setViewScriptPathNoControllerSpec(':action.:suffix')
             ->setViewSuffix('tpl');
Zend_Controller_Action_HelperBroker::addHelper($viewRenderer);
]]></programlisting>
        </example>

        <example id="zend.controller.actionhelper.viewrenderer.advancedusage.example-2">
            <title>Rendu de plusieurs scripts de vue dans une même action</title>

            <para>
                Afin de rendre plusieurs scripts de vue dans une même action, appelez tout
                simplement plusieurs fois <methodname>render()</methodname>&#160;:
            </para>

            <programlisting language="php"><![CDATA[
class SearchController extends Zend_Controller_Action
{
    public function resultsAction()
    {
        // Considérons $this->model comme étant un modèle valide
        $this->view->results = $this->model
                                    ->find($this->_getParam('query', '');

        // render() est proxiée vers ViewRenderer
        // Rend d'abord un formulaire, puis un résultat
        $this->render('form');
        $this->render('results');
    }

    public function formAction()
    {
        // Rien : ViewRenderer rend automatiquement un script de vue
    }
}
]]></programlisting>
        </example>
    </sect4>
</sect3>