Introduction au Zend Framework

 Apprendre Zend Framework

appendix

 Guide de référence Zend Framework


  •  Zend_Gdata
  •  Zend_Http
  •  Zend_InfoCard
  •  Zend_Json
  •  Zend_Layout
  •  Zend_Ldap
  •  Zend_Loader
  •  Zend_Locale
  •  Zend_Log
  •  Zend_Mail
  •  Zend_Markup
  •  Zend_Measure
  •  Zend_Memory
  •  Zend_Mime
  •  Zend_Navigation
  •  Zend_Oauth
  •  Zend_OpenId
  •  Zend_Paginator
  •  Zend_Pdf
  •  Zend_ProgressBar
  •  Zend_Queue
  •  Zend_Reflection
  •  Zend_Registry
  •  Zend_Rest

  •  Zend_Search_Lucene
  •  Zend_Serializer
  •  Zend_Server
  •  Zend_Service
  •  Zend_Session
  •  Zend_Soap
  •  Zend_Tag
  •  Zend_Test
  •  Zend_Text
  •  Zend_TimeSync
  •  Zend_Tool
  •  Zend_Tool_Framework
  •  Zend_Tool_Project
  •  Zend_Translate
  •  Zend_Uri
  •  Zend_Validate
  •  Zend_Version
  •  Zend_View
  •  Zend_Wildfire
  •  Zend_XmlRpc
  • ZendX_Console_Process_Unix
  • ZendX_JQuery
  • Translation 61.2% Update 2010-11-28 - Revision 23149 - Version ZF 1.11.x

    77.4. Aides de vue

    Dans vos scripts de vue, il est souvent nécessaire d'effectuer certaines actions complexes encore et encore : par exemple, formater une date, générer des éléments de formulaire, afficher des liens d'action. Vous pouvez utiliser des classes d'aide pour effectuer ce genre de tâches.

    Une aide est simplement une classe. Par exemple, nous voulons une aide nommée "foobar". Par défaut, la classe est préfixée avec "Zend_View_Helper_" (vous pouvez spécifier un préfixe personnalisé en paramétrant votre chemin d'aide), et le dernier segment du nom de classe est le nom de l'aide ; ce segment peut être avec des CaracteresMajuscules ; le nom complet de la classe est alors : Zend_View_Helper_FooBar. Cette classe doit contenir au moins une méthode, nommée comme l'aide avec la notationCamel : fooBar().

    [Note] Surveillez la casse

    Les noms des aides sont toujours en notationCamel, c'est-à-dire qu'ils ne commencent pas avec un caractère majuscule. Le nom de classe elle-même peut être en casseMélangée, mais la méthode qui est exécutée est en notationCamel.

    Pour utiliser une aide dans votre script de vue, appelez la en utilisant $this->nomAide(). Dans les coulisses, Zend_View va charger la classe Zend_View_Helper_NomAide, créer une instance de cet objet, et appeler sa méthode nomAide(). L'instance de l'objet est persistante dans l'instance de Zend_View, et est réutilisée pour tous les appels futurs à $this->nomAide().

    77.4.1. Aides initiales

    Zend_View fournit avec un jeu initial de classes d'aides, la plupart est liée à la génération d'éléments de formulaire. Chacune affiche et échappe l'élément automatiquement. De plus, il existe des aides pour créer des URLs sur la base de routes et des listes HTML, de la même manière que l'on déclarerait des variables. Les aides actuellement incluses sont :

    • declareVars() : initialement prévu pour être utilisé avec strictVars(), cette aide peut être utilisée pour déclarer les variables de modèle ("template") qui sont (ou pas) déjà déclarées dans l'objet de vue, ou pour gérer des valeurs par défaut. Les tableaux passés comme arguments à la méthode seront utilisés pour paramétrer des valeurs par défaut ; sinon, si la variable n'existe pas, on lui affecte une chaîne vide.

    • fieldset($name, $content, $attribs) : crée un ensemble de champs XHTML. Si $attribs contient une clé "legend", cette valeur sera utilisée comme légende du fieldset. Le fieldset entourera le contenu $content tel qu'il aura été fourni à l'aide.

    • form($name, $attribs, $content) : génère un formulaire XHTML. Tous les éléments $attribs sont échappés et rendus sous la forme d'attributs de la balise "form". Si $content est présent et n'est pas un booléen valant FALSE, alors ce contenu est rendu à l'intérieur des balises "form" ; si $content est un booléen valant FALSE (par défaut), seul la balise ouvrante "form" est générée.

    • formButton($name, $value, $attribs) : crée un élément <button />.

    • formCheckbox($name, $value, $attribs, $options): crée un élément <input type="checkbox" />.

      Par défaut, quand aucune $value n'est fournie et qu'aucune $options n'est présente, alors "0" est considéré comme la valeur non cochée et "1" comme la valeur cochée. Si une $value est fournie, mais qu'aucune $options n'est présente, l'état coché est considéré égal à la $value fournie.

      $options devrait être un tableau. Si ce tableau est indexé, la première valeur est la valeur cochée, la seconde est la valeur non cochée ; et tout autre valeur est ignorée. Vous pouvez aussi passer un tableau associatif avec les clés "checked" et "unChecked".

      Si $options est fourni, et que $value correspond à la valeur cochée, alors l'élément sera marqué comme coché. Vous pouvez aussi marquer l'élément comme coché ou décoché en passant une valeur booléenne à l'attribut "checked".

      Ceci pourra sûrement être plus explicite avec quelques exemples :

      // "1" et "0" en tant qu'options cochée/décochée ; cochée
      echo $this->formCheckbox('foo');

      // "1" et "0" en tant qu'options cochée/décochée ; cochée
      echo $this->formCheckbox('foo'null, array('checked' => true));

      // "bar" et "0" en tant qu'options cochée/décochée ; décochée
      echo $this->formCheckbox('foo''bar');

      // "bar" et "0" en tant qu'options cochée/décochée ; cochée
      echo $this->formCheckbox('foo''bar', array('checked' => true));

      // "bar" et "baz" en tant qu'options cochée/décochée ; décochée
      echo $this->formCheckbox('foo'nullnull, array('bar''baz'));

      // "bar" et "baz" en tant qu'options cochée/décochée ; décochée
      echo $this->formCheckbox('foo'nullnull, array(
          
      'checked' => 'bar',
          
      'unChecked' => 'baz'
      ));

      // "bar" et "baz" en tant qu'options cochée/décochée ; cochée
      echo $this->formCheckbox('foo''bar'null, array('bar''baz'));
      echo 
      $this->formCheckbox('foo',
                               
      null,
                               array(
      'checked' => true),
                               array(
      'bar''baz'));

      // "bar" et "baz" en tant qu'options cochée/décochée ; décochée
      echo $this->formCheckbox('foo''baz'null, array('bar''baz'));
      echo 
      $this->formCheckbox('foo',
                               
      null,
                               array(
      'checked' => false),
                               array(
      'bar''baz'));

      Dans tous les cas, la balise est précédée d'un élément masqué ("hidden") avec la valeur de l'état décoché ; ainsi, si la valeur est décochée, vous aurez toujours une valeur valide retournée par votre formulaire.

    • formErrors($errors, $options) : génère une liste non ordonnée XHTML pour montrer des erreurs. $errors peut être une chaîne de caractères ou un tableau de chaînes ; $options peut être tout attribut que vous pourriez vouloir placer dans la balise ouvrante de la liste.

      Vous pouvez spécifier des éléments ouvrants, fermants et des séparateurs de contenu alternatifs lors du rendu des erreurs en appelant les différentes méthodes suivantes de l'aide :

      • setElementStart($string) ; par défaut vaut "<ul class="errors"%s"><li>", où %s est remplacé avec les attributs spécifiés dans $options.

      • setElementSeparator($string) ; par défaut vaut "</li><li>".

      • setElementEnd($string) ; par défaut vaut "</li></ul>".

    • formFile($name, $attribs): crée un élément <input type="file" />.

    • formHidden($name, $value, $attribs) : crée un élément <input type="hidden" />.

    • formLabel($name, $value, $attribs) : crée un élément <label>, en réglant l'attribut for avec $name, et le texte du label avec $value. Si disable est fourni via attribs, rien n'est retourné.

    • formMultiCheckbox($name, $value, $attribs, $options, $listsep) : crée une liste de cases à cocher. $options devrait être un tableau associatif, avec une profondeur arbitraire. $value peut être une valeur unique ou un tableau de valeurs sélectionnées qui correspondent aux clés du tableau $options. $listsep est un séparateur HTML ("<br />") par défaut. Par défaut, cet élément est traité comme un tableau ; toutes les cases à cocher partagent le même nom, et sont soumises sous la forme d'un tableau.

    • formPassword($name, $value, $attribs) : crée un élément <input type="password" />.

    • formRadio($name, $value, $attribs, $options) : crée une série d'éléments <input type="button" />, un pour chaque élément $options. Dans le tableau $options, la clé de l'élément est la valeur du radio, et la valeur de l'élément est l'étiquette du radio. La radio $value sera précochée pour vous.

    • formReset($name, $value, $attribs) : crée un élément <input type="reset" />.

    • formSelect($name, $value, $attribs, $options) : crée un bloc <select>...</select>, avec une <option> pour chaque élément $options. Dans le tableau $options, la clé de l'élément est la valeur de l'option, et la valeur de l'élément est son étiquette optionnelle. L'option (ou les options) $value sera (ou seront) présélectionnée(s) pour vous.

    • formSubmit($name, $value, $attribs) : crée un élément <input type="submit" />.

    • formText($name, $value, $attribs) : crée un élément <input type="text" />.

    • formTextarea($name, $value, $attribs) : crée un bloc <textarea>...</textarea>.

    • url($urlOptions, $name, $reset) : crée un URL basé sur une route nommée. $urlOptions doit être un tableau associatif avec des paires de clés/valeurs utilisées par une route particulière.

    • htmlList($items, $ordered, $attribs, $escape) : génère des listes ordonnées ou non basées sur les $items qui lui sont fournis. Si $items est un tableau multidimensionnel, une liste imbriquée sera construite. Si le paramètre $escape vaut TRUE (valeur par défaut), chaque élément sera échappé en utilisant le mécanisme d'échappement enregistré dans les objets de vue ; fournissez une valeur FALSE si vous voulez autoriser du balisage dans vos listes.

    Les utiliser dans vos script de vue est très simple, voici un exemple. Notez que tout ce dont vous avez besoin, c'est de les appeler; elles vont se charger et s'instancier elle-même si besoin est.

    <!--
    Dans votre script de vue$this se réfère à l'instance de Zend_View.
    Partons du principe que vous avez déjà assigné une série d'
    options
    de sélection dans un tableau $pays 
    =
    array(
    'us' => 'Etats-Unis''fr' => 'France''de' => 'Allemagne').
    -->
    <
    form action="action.php" method="post">
        <
    p><label>Votre email :
            <?
    php echo $this->formText('email',
                                       
    'vous@exemple.fr',
                                       array(
    'size' => 32)) ?>
        </label></p>
        <p><label>Votre pays :
            <?php echo $this->formSelect('country',
                                         
    'us',
                                         
    null,
                                         
    $this->pays?>
        </label></p>
        <p><label>??? Would you like to opt in ???
            <?php echo $this->formCheckbox('opt_in',
                                           
    'oui',
                                           
    null,
                                           array(
    'oui''non')) ?>
        </label></p>
    </form>

    La sortie résultante du script de vue ressemblera à ceci :

    <form action="action.php" method="post">
        <
    p><label>Votre email :
            <
    input type="text" name="email"
                   
    value="vous@exemple.fr" size="32" />
        </
    label></p>
        <
    p><label>Votre pays :
            <
    select name="country">
                <
    option value="us" selected="selected">Etats-Unis</option>
                <
    option value="fr">France</option>
                <
    option value="de">Allemagne</option>
            </
    select>
        </
    label></p>
        <
    p><label>??? Would you like to opt in ???
            <
    input type="hidden" name="opt_in" value="non" />
            <
    input type="checkbox" name="opt_in"
                   
    value="oui" checked="checked" />
        </
    label></p>
    </
    form>

    77.4.1.1. L'aide de vue Action

    L'aide de vue Action permet à des scripts de vue de distribuer une action donnée d'un contrôleur ; le résultat de l'objet de réponse suivant la distribution est alors retourné. Ceux-ci peuvent être employés quand une action particulière peut produire du contenu réutilisable ou du contenu de type "gadget".

    Les actions qui ont comme conséquence un _forward() ou une redirection sont considérées invalide, et retourneront une chaîne vide.

    L'API pour l'aide de vue Action respecte le même schéma que la plupart les composants MVC qui appellent des actions de contrôleur : action($action, $controller, $module = null, array $params = array()). $action et $controller sont exigés ; si aucun module n'est spécifié, le module par défaut est implicite.

    Exemple 77.1. Utilisation de base de l'aide de vue Action

    Par exemple, vous pouvez avoir un CommentController avec une méthode listAction() que vous souhaitez appeler afin de récupérer une liste de commentaires pour la requête courante :

    <div id="sidebar right">
        <
    div class="item">
            <?
    php echo $this->action('list''comment'null, array('count' => 10)); ?>
        </div>
    </div>

    77.4.1.2. Aide BaseUrl

    La plupart des URLs générées par le framework possèdent l' URL de base préfixée automatiquement. Les développeurs ont besoin de la rajouter à la main à leurs propres URLs afin de garder une correspondance chemins - ressources correcte.

    L'utilisation de l'aide de vue BaseUrl est très simple:

    /*
     * Imaginons une URL de base dans page/application de "/mypage".
     */

    /*
     * affiche:
     * <base href="/mypage/" />
     */
    <base href="<?php echo $this->baseUrl(); ?>" />

    /*
     * affiche:
     * <link rel="stylesheet" type="text/css" href="/mypage/css/base.css" />
     */
    <link rel="stylesheet" type="text/css"
         
    href="<?php echo $this->baseUrl('css/base.css'); ?>" />
    [Note] Note

    Pour plus de simplicité, le fichier PHP (par exemple "index.php") est enelevé de l'URL de base gérée par Zend_Controller. Cependant, si ceci vous gène, utilisez $this->getHelper('BaseUrl')->setBaseUrl() pour affecter votre propre BaseUrl.

    77.4.1.3. Aide Currency

    Afficher des informations de monnaie localisées est très courant; l'aide de vue de Zend_Currency est dédiée à cela. Voyez le chapitre sur Zend Currency pour les détails sur la localisation. Dans cette section, nous apprendrons à manipuler l'aide de vue uniquement.

    Il existe plusieurs manières d'initialiser l'aide de vue Currency:

    • Enrigistrée dans une instance de Zend_Registry.

    • Grâce à une interface fluide.

    • En instanciant directement la classe.

    L'enregistrement en registre de Zend_Currency est la manière recommandée. Grâce à cela vous pouvez selectionner la monnaie à utiliser puis ajouter son adaptateur au registre.

    Pour séléctionner la valeur de la monnaie à utiliser, passez une chaine ou encore une locale ce qui est recommandé car les informations provenant du client HTTP seront alors utilisées par défaut.

    [Note] Note

    Nous parlons bien de "locales" et non de "langues" car la langue peut varier en fonction de la position géorgraphique au sein d'un même pays.Par exemple, l'anglais est parlé dans différents dialectes : Anglais ou Américain. Une monnaie est liée directement à une région, vous devrez donc utiliser une locale complète c'est à dire représentant le pays et la région. Nous parlons donc de "locale" plutôt que de "langue."

    Exemple 77.2. Instance en registre

    Pour utiliser une instance en registre, créez une instance de Zend_Currency et enregistrez la dans Zend_Registry en utilisant la clé Zend_Currency.

    // notre monnaie d'exemple
    $currency = new Zend_Currency('de_AT');
    Zend_Registry::set('Zend_Currency'$currency);

    // Dans votre vue
    echo $this->currency(1234.56);
    // Ceci affiche '€ 1.234,56'

    Si vous préférez utiliser l'interface fluide, vous pouvez alors créer une instance dans votre vue et la configurer après cela.

    Exemple 77.3. Instance dans la vue

    Pour utiliser l'interface fluide, créez une instance de Zend_Currency, appelez l'aide de vue sans paramètre et appelez ensuite la méthode setCurrency().

    // Dans votre vue
    $currency = new Zend_Currency('de_AT');
    $this->currency()->setCurrency($currency)->currency(1234.56);
    // Ceci affiche '€ 1.234,56'

    Si vous utilisez l'aide sans Zend_View alors vous pouvez aussi l'utiliser de manière directe, via instanciation manuelle.

    Exemple 77.4. Utilisation directe via instanciation

    // Notre monnaie d'exemple
    $currency = new Zend_Currency('de_AT');

    // Initialisation de l'aide de vue
    $helper = new Zend_View_Helper_Currency($currency);
    echo 
    $helper->currency(1234.56); // Ceci affiche '€ 1.234,56'

    Comme déja vu, la méthode currency() est utilisée pour retourner la chaine représentant la monnaie. Appelez la simplement avec la valeur que vous voulez voir affichée. Des options sont aussi disponibles, elles servent à changer le comportement interne de l'aide.

    Exemple 77.5. Utilisation directe

    // Notre monnaie d'exemple
    $currency = new Zend_Currency('de_AT');

    // Initialisation de l'aide de vue
    $helper = new Zend_View_Helper_Currency($currency);
    echo 
    $helper->currency(1234.56); // Ceci affiche '€ 1.234,56'
    echo $helper->currency(1234.56, array('precision' => 1));
    // Ceci affiche '€ 1.234,6'

    Concernant les options disponibles, voyez la méthode toCurrency() de Zend_Currency.

    77.4.1.4. Aide Cycle

    L'aide Cycle est utilisée pour alterner des valeurs.

    Exemple 77.6. Aide Cycle : utilisation de base

    Pour ajouter des éléments dans le cycle, spécifiez le simplement dans le constructeur ou utilisez assign(array $data)

    <?php foreach ($this->books as $book):?>
      <tr style="background-color:<?php echo $this->cycle(array("#F0F0F0",
                                                                
    "#FFFFFF"))
                                                  ->
    next()?>">
      <td><?php echo $this->escape($book['author']) ?></td>
    </tr>
    <?php endforeach;?>

    // Mouvement dans le sens inverse
    $this->cycle()->assign(array("#F0F0F0","#FFFFFF"));
    $this->cycle()->prev();
    ?>

    La sortie:

    <tr style="background-color:'#F0F0F0'">
       <
    td>First</td>
    </
    tr>
    <
    tr style="background-color:'#FFFFFF'">
       <
    td>Second</td>
    </
    tr>

    Exemple 77.7. Travailler avec 2 cycles ou plus

    Pour utiliser 2 cycles, il faut renseigner leurs noms. Ca se passe au niveau du second paramètre de la méthode cycle. $this->cycle(array("#F0F0F0","#FFFFFF"),'cycle2'). setName($name) peut aussi être utilisée.


    <?php foreach ($this->books as $book):?>
      <tr style="background-color:<?php echo $this->cycle(array("#F0F0F0",
                                                                
    "#FFFFFF"))
                                                  ->
    next()?>">
      <td><?php echo $this->cycle(array(1,2,3),'number')->next()?></td>
      <td><?php echo $this->escape($book['author'])?></td>
    </tr>
    <?php endforeach;?>

    77.4.1.5. L'aide de vue Partial

    L'aide de vue Partial est utilisée pour effectuer le rendu d'un modèle ("template") spécifique dans sa propre portée de variable. L'utilisation principale est pour les fragments réutilisables de modèle avec lesquels vous n'avez pas besoin de vous inquiéter des conflits de noms de variable. De plus, ils vous permettent de spécifier les scripts de vue partiels dans des modules spécifiques.

    Une soeur de l'aide Partial, l'aide de vue de PartialLoop vous permet de passer des données itératives, et effectue un rendu partiel pour chaque élément.

    [Note] Compteur de PartialLoop

    L'aide de vue PartialLoop assigne une variable à la vue nommée partialCounter qui fournit la position courante du tableau au script de vue. Ce qui permet simplement d'avoir des couleurs alternatives dans les lignes d'un tableau par exemple.

    Exemple 77.8. Utilisation de base des Partials

    L'utilisation de base des Partials est d'effectuer le rendu d'un fragment de modèle dans sa propre portée de vue. Examinez le script partiel suivant :

    <!--partiel.phtml-->
    <
    ul>
        <
    li>De : <?php echo $this->escape($this->de?></li>
        <li>Sujet : <?php echo $this->escape($this->sujet?></li>
    </ul>

    Vous l'appelleriez alors dans votre script de vue en utilisant ce qui suit :

    <?php echo $this->partial('partiel.phtml', array(
        
    'de' => 'Equipe Framework',
        
    'sujet' => 'vues partielles')); ?>

    Qui vous retournerait :

    <ul>
        <
    li>De Equipe Framework</li>
        <
    li>Sujet vues partielles</li>
    </
    ul>

    [Note] Qu'est qu'un modèle ?

    Un modèle utilisé avec l'aide de vue Partial peut être un des suivants :

    • Tableaux ("array") : si un tableau est fourni, il devrait être associatif, car ses paires de clé/valeur sont assignées à la vue avec les clés comme variables de vue.

    • Objet implémentant la méthode toArray() : si un objet est fourni et qu'il possède une méthode toArray(), le résultat de toArray() sera assigné à la vue comme variable de vue.

    • Objet standard : tout autre objet assignera le résultat de object_get_vars() (essentiellement toutes les propriétés publiques de l'objet) à l'objet de vue.

    Si votre modèle est un objet, vous pouvez vouloir le fournir en tant qu'objet au script partiel, plutôt que de le sérialiser en un tableau de variables. Vous pouvez faire ceci en paramétrant la propriété "objectKey" de l'aide de vue approprié :

    // Tell partial to pass objects as 'model' variable
    $view->partial()->setObjectKey('model');

    // Tell partial to pass objects from partialLoop as 'model' variable in final
    // partial view script:
    $view->partialLoop()->setObjectKey('model');

    Cette technique est particulièrement utile quand vous fournissez un Zend_Db_Table_Rowsets à partialLoop(), ainsi vous avez un accès complet à vos objets Row à l'intérieur de vos scripts de vue, permettant d'appeler des méthodes sur ceux-ci (comme récupérer des valeurs d'un Row parent ou dépendant).

    Exemple 77.9. Utiliser PartialLoop pour effectuer le rendu d'éléments itératifs

    Typiquement, vous voudrez employer des Partials dans une boucle, pour rendre le même fragment de contenu plusieurs fois ; de cette façon vous pouvez mettre de grands blocs de contenu répété ou de logique complexe d'affichage dans un endroit unique. Toutefois ceci a un impact d'exécution, car l'aide Partial doit être appelée une fois par itération.

    L'aide de vue PartialLoop résout ce problème. Elle vous permet de fournir un élément itérable (tableau ou objet implémentant Iterator) comme modèle. Elle réitère alors au-dessus de celui-ci en fournissant les éléments au script partiel. Les éléments dans l'itérateur peuvent être n'importe quel modèle que l'aide de vue Partial permet (cf. ci-dessus).

    Considérons le script partiel suivant :

    <!--partialLoop.phtml-->
        <
    dt><?php echo $this->key ?></dt>
        <dd><?php echo $this->value ?></dd>

    Et le "modèle" suivant :

    $model = array(
        array(
    'key' => 'Mammifère''value' => 'Chameau'),
        array(
    'key' => 'Oiseau',    'value' => 'Pingouin'),
        array(
    'key' => 'Reptile',   'value' => 'Asp'),
        array(
    'key' => 'Poisson',   'value' => 'Flounder')
    );

    Dans votre script de vue, vous pouvez maintenant appeler l'aide PartialLoop :

    <dl>
    <?
    php echo $this->partialLoop('partialLoop.phtml'$model?>
    </dl>
    <dl>
        <
    dt>Mammifère</dt>
        <
    dd>Chameau</dd>

        <
    dt>Oiseau</dt>
        <
    dd>Pingouin</dd>

        <
    dt>Reptile</dt>
        <
    dd>Asp</dd>

        <
    dt>Poisson</dt>
        <
    dd>Flounder</dd>

    </
    dl>

    Exemple 77.10. Effectuer le rendu partiel dans des modules différents

    Parfois un partiel existera dans un module différent. Si vous connaissez le nom du module, vous pouvez le fournir comme deuxième argument à partial() ou à partialLoop(), en déplaçant l'argument $model à la troisième position.

    Par exemple, s'il y a un gestionnaire de page partiel que vous souhaitez utiliser et qui est dans le module "liste", vous pourriez le saisir comme suit :

    <?php echo $this->partial('pager.phtml''liste'$pagerData?>

    De cette façon, vous pouvez réutiliser des partiels créés spécifiquement pour d'autre modules. Ceci dit, il est probablement une meilleure pratique de mettre des partiels réutilisables dans des dossiers partagés de script de vue.


    77.4.1.6. L'aide de vue Placeholder

    [Note] Note

    NDT. : Le terme "placeholder est conservé car sa signification varie en fonction du contexte : conteneur générique ou emplacement réservé.

    L'aide de vue Placeholder est utilisé pour faire persister le contenu entre les scripts de vues et les instances de vues. Il offre aussi des fonctionnalités utiles comme l'agrégation de contenu, la capture de contenu de scripts de vues pour une utilisation ultérieure, et l'ajout de texte pré ou post contenu (et la personnalisation des séparateurs de contenu).

    Exemple 77.11. Utilisation basique des Placeholders

    L'utilisation basique des placeholders est la persistance des données de vue. Chaque appel de l'aide Placeholder attend un nom de placeholder ; l'aide retourne un objet conteneur que vous pouvez soit manipuler ou simplement envoyé à l'affichage.

    <?php $this->placeholder('foo')->set("Du texte pour plus tard"?>

    <?php
        
    echo $this->placeholder('foo');
        
    // outputs "Du texte pour plus tard"
    ?>

    Exemple 77.12. Utilisation des Placeholders pour agréger du contenu

    L'agrégation du contenu via les placeholders peut être aussi utile parfois. Par exemple, votre script de vue peut avoir une variable sous forme de tableau à partir de laquelle vous souhaitez récupérer des messages à afficher plus tard ; un autre script de vue peut ensuite déterminer de la manière suivant laquelle ils seront affichés.

    L'aide de vue Placeholder utilise des conteneurs qui étendent ArrayObject, fournissant de riches fonctionnalités de manipulations des tableaux. De plus, il offre une variété de méthodes pour le formatage du contenu stockée dans le conteneur :

    • setPrefix($prefix) paramètre le texte qui sera placé préalablement à tout le contenu. Utilisez getPrefix() à tout moment pour déterminer le réglage courant.

    • setPostfix($prefix) paramètre le texte qui sera placé après tout le contenu. Utilisez getPostfix() à tout moment pour déterminer le réglage courant.

    • setSeparator($prefix) paramètre le texte qui sera placé entre chaque élément de contenu. Utilisez getSeparator() à tout moment pour déterminer le réglage courant.

    • setIndent($prefix) peut être utilisé pour paramétrer une indentation pour chaque élément du contenu. Si un entier est fourni, il s'agira du nombre d'espaces à utiliser ; si une chaîne est fournie, elle sera utilisée. Utilisez getIndent() à tout moment pour déterminer le réglage courant.

    <!-- premier script de vue -->
    <?
    php $this->placeholder('foo')->exchangeArray($this->data?>
    <!-- autre script (plus tard) -->
    <?
    php
    $this
    ->placeholder('foo')->setPrefix("<ul>\n    <li>")
                             ->
    setSeparator("</li><li>\n")
                             ->
    setIndent(4)
                             ->
    setPostfix("</li></ul>\n");
    ?>

    <?php
        
    echo $this->placeholder('foo');
        
    // affiche une liste non-ordonnée avec une belle indentation
    ?>

    Puisque l'objet conteneur Placeholder étend ArrayObject, vous pouvez ainsi facilement assigner du contenu à une clé du conteneur en particulier, plutôt que de simplement de les envoyer les unes après les autres ("push"). Les clés peuvent être accédées soit en utilisant les propriétés d'objet ou comme les clés d'un tableau.

    <?php $this->placeholder('foo')->bar $this->data ?>
    <?php 
    echo $this->placeholder('foo')->bar ?>

    <?php
    $foo 
    $this->placeholder('foo');
    echo 
    $foo['bar'];
    ?>

    Exemple 77.13. Utilisation des Placeholders pour capturer le contenu

    Occasionnellement vous pouvez avoir du contenu pour un placeholder dans un script de vue qui est simple à mettre sous forme de modèle ("template") ; l'aide de vue Placeholder vous permet de capturer tout contenu arbitraire pour un rendu ultérieur en utilisant l'API suivante.

    • captureStart($type, $key) commence la capture de contenu.

      $type doit être une des constantes de Placeholder : APPEND ou SET. Si c'est APPEND, le contenu capturé est ajouté à la liste de contenu courant dans le placeholder ; si c'est SET, le contenu capturé remplace toute valeur existante dans le placeholder (potentiellement permet de remplacer tout contenu préalable). Par défaut, $type vaut APPEND.

      $key peut être utilisé pour spécifier une clé en particulier dans le conteneur placeholder dans laquelle vous souhaitez capturer le contenu.

      captureStart() verrouille la capture jusqu'à l'appel de captureEnd() ; vous ne pouvez pas imbriquer des captures avec le même conteneur placeholder. Le faire entraînera la levée d'une exception.

    • captureEnd() stoppe la capture de contenu, et le place dans l'objet conteneur suivant la manière utilisée pour appeler captureStart().

    <!-- Default captureappend -->
    <?
    php $this->placeholder('foo')->captureStart();
    foreach (
    $this->data as $datum): ?>
    <div class="foo">
        <h2><?php echo $datum->title ?></h2>
        <p><?php echo $datum->content ?></p>
    </div>
    <?php endforeach; ?>
    <?php $this
    ->placeholder('foo')->captureEnd() ?>

    <?php echo $this->placeholder('foo'?>
    <!-- Capture to key -->
    <?
    php $this->placeholder('foo')->captureStart('SET''data');
    foreach (
    $this->data as $datum): ?>
    <div class="foo">
        <h2><?php echo $datum->title ?></h2>
        <p><?php echo $datum->content ?></p>
    </div>
     <?php endforeach; ?>
    <?php $this
    ->placeholder('foo')->captureEnd() ?>

    <?php echo $this->placeholder('foo')->data ?>

    77.4.1.6.1. Implémentation concrète des Placeholder

    Zend Framework embarque certaines implémentations concrètes de placeholders. Celles-ci sont destinées à des placeholders communément utilisés : doctype, titre de page, et les différents éléments <head>. Dans tous les cas, appeler le placeholder sans arguments retournera l'élément lui-même.

    La documentation pour chacun des éléments existe séparément, suivez les liens ci-dessous :

    77.4.1.7. L'aide de vue Doctype

    Les documents HTML et XHTML valides doivent inclure une déclaration DOCTYPE. Sans compter qu'ils sont difficiles à garder en mémoire, ceux-ci peuvent aussi affecter la façon dont certains éléments du document peuvent être rendus (par exemple, les échappements CDATA dans <script> et les éléments <style>.

    L'aide Doctype vous permet de spécifier un des types suivants :

    • XHTML11

    • XHTML1_STRICT

    • XHTML1_TRANSITIONAL

    • XHTML1_FRAMESET

    • XHTML_BASIC1

    • HTML4_STRICT

    • HTML4_LOOSE

    • HTML4_FRAMESET

    • HTML5

    Vous pouvez aussi spécifier un doctype personnalisé du moment que celui-ci soit correctement formé.

    L'aide Doctype est une implémentation concrète de l'aide Conteneur.

    Exemple 77.14. Utilisation basique de l'aide Doctype

    Vous pouvez spécifier le doctype à n'importe quel moment. Cependant, les aides de vues qui utilisent pour leur affichage ne le reconnaissent qu'une fois qu'il a été paramètré, donc la manière la plus simple est de le spécifier dans votre fichier d'amorçage :

    $doctypeHelper = new Zend_View_Helper_Doctype();
    $doctypeHelper->doctype('XHTML1_STRICT');

    Ensuite vous l'affichez en début de votre layout :

    <?php echo $this->doctype() ?>

    Exemple 77.15. Récupérer le Doctype

    Si vous avez besoin du doctype, vous pouvez le récupérer par l'appel de getDoctype() sur l'objet.

    $doctype $view->doctype()->getDoctype();

    Typiquement, vous pouvez simplement vouloir savoir si le doctype est XHTML ou non ; pour ceci, la méthode isXhtml() vous suffira :

    if ($view->doctype()->isXhtml()) {
        
    // faire qqch de différent
    }

    Vous pouvez aussi vérifier si le doctype représente un document HTML5 :

    if ($view->doctype()->isHtml5()) {
        
    // faire qqch de différent
    }

    77.4.1.8. L'aide de vue HeadLink

    L'élément HTML <link> est de plus en plus employé pour lier différents types de ressources à votre site : feuilles de styles, syndication, icônes, trackbacks et d'autres. L'aide HeadLink fournit une interface simple pour créer et agréger ces éléments pour la récupération postérieure et le rendement dans votre script d'affichage.

    L'aide HeadLink possède des méthodes pour ajouter des liens de feuilles de style dans sa pile :

    • appendStylesheet($href, $media, $conditionalStylesheet, $extras)

    • offsetSetStylesheet($index, $href, $media, $conditionalStylesheet, $extras)

    • prependStylesheet($href, $media, $conditionalStylesheet, $extras)

    • setStylesheet($href, $media, $conditionalStylesheet, $extras)

    La valeur par défaut de $media vaut screen, mais peut être n'importe quelle valeur de média valide. $conditionalStylesheet est une chaîne ou le booléen FALSE, et sera utilisé au moment du rendu pour déterminer si des commentaires spéciaux doivent être inclus pour empêcher le chargement de la feuille de style sur certaines plate-formes. $extras est un tableau de valeurs supplémentaires que vous voulez ajouter à la balise.

    De plus, l'aide HeadLink possède des méthodes pour ajouter des liens alternatifs dans sa pile :

    • appendAlternate($href, $type, $title, $extras)

    • offsetSetAlternate($index, $href, $type, $title, $extras)

    • prependAlternate($href, $type, $title, $extras)

    • setAlternate($href, $type, $title, $extras)

    La méthode headLink() de l'aide permet de spécifier tous les attributs nécessaires à un élément <link>, et vous permet aussi de préciser l'emplacement - le nouvel élément peut remplacer tous les autres, s'ajouter au début ou à la fin de la liste.

    L'aide HeadLink est une implémentation concrète de l'aide Placeholder.

    Exemple 77.16. Utilisation basique de l'aide HeadLink

    Vous pouvez spécifier un headLink à n'importe quel moment. Typiquement, vous pouvez spécifier des liens globaux dans votre script de disposition, et des liens spécifiques à l'application dans vos scripts de vue. Dans votre script de disposition, dans la section <head>, vous pourrez ensuite afficher le résultat de l'aide.

    <?php // régler les liens dans votre script de vue :
    $this->headLink()->appendStylesheet('/styles/basic.css')
                     ->
    headLink(array('rel' => 'favicon',
                                      
    'href' => '/img/favicon.ico'),
                                
    'PREPEND')
                     ->
    prependStylesheet('/styles/moz.css',
                                         
    'screen',
                                         
    true,
                                         array(
    'id' => 'my_stylesheet'));
    ?>

    <!-- effectuer le rendu -->
    <?php echo $this->headLink() ?>

    77.4.1.9. L'aide de vue HeadMeta

    L'élément HTML <meta> est utilisé pour fournir des métadonnées concernant votre document HTML - typiquement, les mots-clés, l'encodage du document, les directives de mise en cache, etc. Les balises de métadonnées peuvent être soit de type "http-equiv" ou "name", doivent contenir un attribut "content" et peuvent avoir aussi un attribut modificateur "lang" ou "scheme".

    L'aide de vue HeadMeta supporte les méthodes suivantes pour le paramétrage et l'ajout de métadonnées :

    • appendName($keyValue, $content, $conditionalName)

    • offsetSetName($index, $keyValue, $content, $conditionalName)

    • prependName($keyValue, $content, $conditionalName)

    • setName($keyValue, $content, $modifiers)

    • appendHttpEquiv($keyValue, $content, $conditionalHttpEquiv)

    • offsetSetHttpEquiv($index, $keyValue, $content, $conditionalHttpEquiv)

    • prependHttpEquiv($keyValue, $content, $conditionalHttpEquiv)

    • setHttpEquiv($keyValue, $content, $modifiers)

    Le paramètre $keyValue est utilisé pour définir une valeur pour la clé "name" ou "http-equiv" ; $content est la valeur pour la clé "content", et $modifiers est un tableau associatif optionel qui peut contenir les clés "lang" et/ou "scheme".

    Vous pouvez aussi spécifier les métadonnées en utilisant la méthode headMeta() qui a la signature suivante : headMeta($content, $keyValue, $keyType = 'name', $modifiers = array(), $placement = 'APPEND'). $keyValue est le contenu de la clé spécifiée dans $keyType, qui peut être "name" ou "http-equiv". $placement peut être soit "SET" (efface toutes les valeurs sauvegardées précédentes), soit "APPEND" (ajout en fin de pile), soit "PREPEND" (ajout en début de pile).

    HeadMeta surcharge chacune des méthodes append(), offsetSet(), prepend(), et set(), pour imposer l'utilisation des méthodes spéciales énumérées ci-dessus. En interne, il stocke chaque élément sous la forme d'un stdClass, qui peut ensuite être sérialiser grâce à la méthode itemToString(). Ceci vous permet de réaliser des contrôles sur les éléments de la pile, et optionnellement de modifier ces éléments simplement en modifiant l'objet retourné.

    L'aide de vue HeadMeta est une implémentation concrète de l'aide Placeholder.

    Exemple 77.17. Utilisation basique de l'aide HeadMeta

    Vous pouvez spécifier une nouvelle métadonnée à n'importe quel moment. Typiquement, vous pouvez spécifier les règles de mise en cache côté client ou les mots clés SEO (Search Engine Optimization : pour l'optimisation des moteurs de recherche).

    Par exemple, si vous souhaitez spécifier des mots clés SEO, vous devez créer une métadonnée de type "name" ayant pour nom "keywords" et pour contenu les mots clés que vous souhaitez associer à votre page :

    // paramètrage des mots clés
    $this->headMeta()->appendName('keywords''framework, PHP, productivité');

    Si vous souhaitez paramètrer des règles de mise en cache côté client, vous devez créer une métadonnée de type "http-equiv" avec les règles que vous souhaitez imposer :

    // désactiver la mise en cache côté client
    $this->headMeta()->appendHttpEquiv('expires',
                                       
    'Wed, 26 Feb 1997 08:21:57 GMT')
                     ->
    appendHttpEquiv('pragma''no-cache')
                     ->
    appendHttpEquiv('Cache-Control''no-cache');

    Une autre utilisation habituelle des métadonnées est le réglage du type de contenu ("content type"), de l'encodage, et le langage :

    // régler le type de contenu et l'encodage
    $this->headMeta()->appendHttpEquiv('Content-Type''text/html; charset=UTF-8')
                     ->
    appendHttpEquiv('Content-Language''fr-FR');

    Si vous proposez un document HTML5, vous pouvez fournir l'encodage de cette manière :

    // régler l'encodage en HTML5
    $this->headMeta()->setCharset('UTF-8');
    // donnera <meta charset="UTF-8">

    Et comme exemple final, une manière simple d'afficher un message de transition avant une redirection est d'utiliser une métadonnée "refresh" :

    // paramètrer une métadonnée refresh pour 3 secondes
    // avant une nouvel URL :
    $this->headMeta()->appendHttpEquiv('Refresh',
                                       
    '3;URL=http://www.some.org/some.html');

    Quand vous êtes prêts à placer vos métadonnées dans votre script de disposition, réalisez un "echo" de l'aide :

    <?php echo $this->headMeta() ?>

    77.4.1.10. L'aide de vue HeadScript

    L'élément HTML <script> est utilisé pour à la fois pour fournir des éléments de scripts côté-client dans le code HTML et aussi pour lier une ressource distante contenant du script côté-client. L'aide de vue HeadScript vous permet de gérer ces deux cas.

    L'aide de vue HeadScript supportent les méthodes suivantes pour paramétrer ou ajouter des scripts :

    • appendFile($src, $type = 'text/javascript', $attrs = array())

    • offsetSetFile($index, $src, $type = 'text/javascript', $attrs = array())

    • prependFile($src, $type = 'text/javascript', $attrs = array())

    • setFile($src, $type = 'text/javascript', $attrs = array())

    • appendScript($script, $type = 'text/javascript', $attrs = array())

    • offsetSetScript($index, $script, $type = 'text/javascript', $attrs = array())

    • prependScript($script, $type = 'text/javascript', $attrs = array())

    • setScript($script, $type = 'text/javascript', $attrs = array())

    Dans le cas des méthodes de type *File(), $src est l'emplacement distant du script à charger ; c'est généralement sous la forme d'une URL ou d'un chemin de fichier. Pour les méthode de type *Script(), $script sont les directives de script côté-client que vous souhaitez utiliser dans l'élément.

    [Note] Paramétrez des commentaires conditionnels

    HeadScript vous permet d'englober vos balises de script avec des commentaires conditionnels, ce qui permet de les masquer pour des navigateurs spécifiques. Pour ajouter les balises conditionnelles, fournissez le paramètre conditional en tant que partie du paramètre $attrs lors de l'appel de la méthode.

    Exemple 77.18. Headscript avec des commentaires conditionnels

    // adding scripts
    $this->headScript()->appendFile('/js/prototype.js',
                                    
    'text/javascript',
                                    array(
    'conditional' => 'lt IE 7');

    HeadScript vous permet aussi de capturer des scripts ; ceci peut être utile si vous voulez créer du script côté-client par programmation, et ensuite le placer n'importe où. Une utilisation de ceci est montré dans un exemple ci-dessous.

    Enfin, vous pouvez aussi utiliser la méthode headScript() pour rapidement ajouter des éléments de script ; le prototype dans ce cas est headScript($mode = 'FILE', $spec, $placement = 'APPEND'). Le $mode est soit "FILE", soit "SCRIPT", suivant si vous liez un script ou que vous en définissiez un. $spec est soit le script à lier ou la source du script elle-même. $placement est "APPEND", "PREPEND", ou "SET".

    HeadScript surcharge chacun des append(), offsetSet(), prepend(), et set() pour imposer l'utilisation des méthodes spéciales énumérées ci-dessus. En interne, il stocke chaque élément sous la forme d'un stdClass, qui peut être ensuite sérialisé grâce à la méthode itemToString(). Ceci vous permet de réaliser des vérifications sur les éléments dans la pile, et optionnellement de les modifier en modifiant simplement l'objet retourné.

    L'aide HeadScript est une implémentation concrète de l'aide Conteneur.

    [Note] Utilisez InlineScript pour les scripts dans le corps ("body") du HTML

    L'aide de vue, InlineScript, similaire à HeadScript devrait être utilisée quand vous souhaitez inclure des scripts dans le corps ("body") du HTML. Placer ces scripts en fin du document est une bonne pratique pour accélérer l'envoi de votre page, particulièrement pour les scripts tiers d'analyse.

    [Note] Les attributs arbitraires sont désactivées par défaut

    Par défaut, HeadScript affichera seulement les attributs de <script> approuvés par le W3C. Ceux-ci inclus "type", "charset", "defer", "language", et "src". Cependant, certaines bibliothèques javascript, notamment Dojo, utilise des attributs personnalisés dans le but de modifier le comportement. Pour autoriser ce type d'attribut, vous pouvez les activer grâce à la méthode setAllowArbitraryAttributes() :

    $this->headScript()->setAllowArbitraryAttributes(true);

    Exemple 77.19. Utilisation basique de l'aide HeadScript

    Vous devriez ajouter une nouvelle balise de script à chaque fois. Comme noté ci-dessus, ceux-ci peuvent être des liens vers des ressources externes ou vers les scripts eux-mêmes.

    // ajout de scripts
    $this->headScript()->appendFile('/js/prototype.js')
                       ->
    appendScript($onloadScript);

    L'ordre est souvent important avec les scripts côté-client ; vous devez vous assurer de charger les librairies dans un ordre spécifique en fonction de leurs dépendances ; utilisez à la fois les directives append, prepend, et offsetSet pour vous aider dans cette tâche :

    // mettre les scripts dans l'ordre

    // placer celui-ci à un offset particulier pour s'assurer
    // de le charger en dernier
    $this->headScript()->offsetSetFile(100'/js/myfuncs.js');

    // utiliser les effets de scriptaculous (append utilise
    // l'index suivant, c-à-d. 101)
    $this->headScript()->appendFile('/js/scriptaculous.js');

    // mais dans tous les cas, le script de base prototype
    // doit être chargé en premier :
    $this->headScript()->prependFile('/js/prototype.js');

    Quand vous êtes finalement prêt à afficher tous les scripts dans votre layout, faîtes simplement un echo de l'aide :

    <?php echo $this->headScript() ?>

    Exemple 77.20. Capturer les scripts en utilisant l'aide HeadScript

    Parfois vous devez générer des scripts côté-client par programme. Même si vous pouvez employer la concaténation de chaînes, les "heredocs", ou tout autre équivalent, il est souvent plus facile de faire juste la création des scripts et de les entourer par des balises PHP. HeadScript vous permet de le faire, et capture ainsi l'élément dans la pile :

    <?php $this->headScript()->captureStart() ?>
    var action = '<?php echo $this->baseUrl ?>';
    $('foo_form').action = action;
    <?php $this->headScript()->captureEnd() ?>

    Les suppositions suivantes sont considérées :

    • Les déclarations de scripts sont ajoutées à la pile. Si vous souhaitez qu'elles remplacent la pile ou qu'elles soient ajoutées en début de pile, vous devez fournir "SET" ou "PREPEND", en tant que premier argument de captureStart().

    • Le type MIME est considéré comme étant "text/javascript" ; si vous souhaitez spécifier un type différent, vous devez le fournir en tant que deuxième argument de captureStart().

    • Si vous souhaitez spécifier un quelconque attribut additionnel pour la balise <script>, fournissez-le sous la forme d'un tableau en troisième argument de captureStart().


    77.4.1.11. L'aide de vue HeadStyle

    L'élément HTML <style> est utilisé pour inclure des feuilles de styles CSS à l'intérieur de l'élément HTML <head>.

    [Note] Utilisez HeadLink pour lier des fichiers CSS externes

    HeadLink devrait être utilisé pour inclure des feuilles de styles externes. HeadStyle ne devrait être utilisé que si vous souhaitez définir des feuilles de styles internes.

    L'aide de vue HeadStyle supporte les méthodes suivantes pour l'ajout et le paramétrage des déclarations de feuilles de styles :

    • appendStyle($content, $attributes = array())

    • offsetSetStyle($index, $content, $attributes = array())

    • prependStyle($content, $attributes = array())

    • setStyle($content, $attributes = array())

    Dans tous les cas, $content est le contenu des déclarations CSS. $attributes sont les attributs additionnels que vous pouvez fournir à la balise style : "lang", "title", "media", ou "dir" sont autorisés.

    [Note] Paramétrez des commentaires conditionnels

    HeadStyle vous permet d'englober vos balises de style avec des commentaires conditionnels, ce qui permet de les masquer pour des navigateurs spécifiques. Pour ajouter les balises conditionnelles, fournissez le paramètre conditional en tant que partie du paramètre $attrs lors de l'appel de la méthode.

    Exemple 77.21. HeadStyle avec des commentaires conditionnels

    // adding scripts
    $this->headStyle()->appendStyle($styles, array('conditional' => 'lt IE 7'));

    HeadStyle permet aussi la capture des déclarations de style ; ceci peut être utile si vous voulez créer des déclarations par programme, et ensuite les placer à un autre endroit. L'utilisation de cette fonctionnalité est montrée dans un exemple ci-dessous.

    Enfin, vous pouvez utiliser la méthode headStyle() pour ajouter rapidement des éléments de déclarations ; la signature de la méthode est headStyle($content$placement = 'APPEND', $attributes = array()). $placement peut être "APPEND", "PREPEND", ou "SET".

    HeadStyle surcharge chacune des méthodes append(), offsetSet(), prepend(), et set() pour imposer l'utilisation des méthodes spéciales listées ci-dessus. En interne, il stocke chaque élément sous la forme d'un stdClass, qui est ensuite sérialisé en utilisant la méthode itemToString(). Ceci vous permet de réaliser des vérifications sur les éléments de la pile, et optionnellement modifier ces éléments en modifiant simplement l'objet retourné.

    L'aide HeadStyle est une implémentation concrète de l'aide Placeholder.

    [Note] UTF-8 encoding used by default

    By default, Zend Framework uses UTF-8 as its default encoding, and, specific to this case, Zend_View does as well. Character encoding can be set differently on the view object itself using the setEncoding() method (or the the encoding instantiation parameter). However, since Zend_View_Interface does not define accessors for encoding, it's possible that if you are using a custom view implementation with this view helper, you will not have a getEncoding() method, which is what the view helper uses internally for determining the character set in which to encode.

    If you do not want to utilize UTF-8 in such a situation, you will need to implement a getEncoding() method in your custom view implementation.

    Exemple 77.22. Utilisation basique de l'aide HeadStyle

    Vous pouvez spécifier une nouvelle balise de style à n'importe quel moment :

    // ajout de styles
    $this->headStyle()->appendStyle($styles);

    L'ordre est très important avec les CSS ; vous pouvez devoir assurer que les déclarations soient chargées dans un ordre spécifique dû à l'ordre de la cascade ; employez les diverses directives "append", "prepend", et "offsetSet" pour faciliter cette tâche :

    // Mettre les styles dans le bon ordre

    // - placer à un offset particulier
    $this->headStyle()->offsetSetStyle(100$stylesPerso);

    // - placer à la fin
    $this->headStyle()->appendStyle($stylesFinaux);

    // - placer au début
    $this->headStyle()->prependStyle($stylesInitiaux);

    Quand vous êtes finalement prêt à afficher toutes les déclarations de styles dans votre script de layout, faîtes un simple echo de l'aide :

    <?php echo $this->headStyle() ?>

    Exemple 77.23. Capturer les déclarations de style en utilisant l'aide HeadStyle

    Parfois vous devez produire des déclarations de styles CSS par programme. Même si vous pouvez employer la concaténation de chaînes, les "heredocs", ou tout autre équivalent, il est souvent plus facile de faire juste la création des styles et de les entourer par des balises PHP. HeadStyle vous permet de le faire, et capture ainsi l'élément dans la pile :

    <?php $this->headStyle()->captureStart() ?>
    body {
        background-color: <?php echo $this->bgColor ?>;
    }
    <?php $this->headStyle()->captureEnd() ?>

    Les suppositions suivantes sont considérées :

    • Les déclarations de styles sont ajoutées à la pile. Si vous souhaitez qu'elles remplacent la pile ou qu'elles soient ajoutées en début de pile, vous devez fournir "SET" ou "PREPEND", en tant que premier argument de captureStart().

    • Si vous souhaitez spécifier un quelconque attribut additionnel pour la balise <style>, fournissez-le sous la forme d'un tableau en deuxième argument de captureStart().


    77.4.1.12. L'aide de vue HeadTitle

    L'élément HTML <title> est utilisé pour fournir un titre à un document HTML. L'aide HeadTitle vous permet par programme de créer et de stocker le titre afin de le récupérer plus tard et de l'afficher.

    L'aide HeadTitle est une implémentation concrète de l'aide Placeholder. Elle surcharge la méthode toString() pour forcer la génération d'un élément <title>, et ajoute une méthode headTitle() pour des réglages faciles et rapides et pour l'aggrégation des éléments du titre. La signature de la méthode est headTitle($title, $setType = null) ; par défaut, la valeur est ajoutée en fin de pile (pour aggréger les segments du titre) si laissé à null, mais vous pouvez aussi spécifier "PREPEND" (pour l'ajouter en début de pile) ou "SET" (pour remplacer la pile existante).

    Since setting the aggregating (attach) order on each call to headTitle can be cumbersome, you can set a default attach order by calling setDefaultAttachOrder() which is applied to all headTitle() calls unless you explicitly pass a different attach order as the second parameter.

    Exemple 77.24. Utilisation basique de l'aide HeadTitle

    Vous pouvez spécifier la balise de titre à n'importe quel moment. Un usage typique serait de paramètrer les différents segments du titre à chaque niveau de profondeur de votre application : site, module, contrôleur, action et ressources potentielles.

    // Paramétrage des noms de contrôleurs et d'action
    // en tant que segment de titre :
    $request Zend_Controller_Front::getInstance()->getRequest();
    $this->headTitle($request->getActionName())
         ->
    headTitle($request->getControllerName());

    // Réglage du nom de site, par exemple dans votre script
    // de disposition :
    $this->headTitle('Zend Framework');

    // Réglage de la haîne de séparation des segments :
    $this->headTitle()->setSeparator(' / ');

    Quand vous êtes finalement prêt à afficher le titre dans votre script de disposition, faîtes simplement un echo de l'aide :

    <!-- Affiche <action> / <controller> / Zend Framework -->
    <?
    php echo $this->headTitle() ?>

    77.4.1.13. L'aide de vue HTML Object

    L'élément HTML <object> est utilisé pour inclure un média comme Flash ou QuickTime dans les pages Web. L'aide de vue Object vous aide à réaliser ceci avec un minimum d'effort.

    Il existe quatre aides de vue Object initiaux :

    • htmlFlash : génère le balisage pour l'inclusion de fichiers Flash.

    • htmlObject : génère le balisage pour l'inclusion d'objets personnalisés.

    • htmlPage : génère le balisage pour l'inclusion d'autres pages (X)HTML.

    • htmlQuicktime : génère le balisage pour l'inclusion de fichiers QuickTime.

    Toutes ces aides partagent une interface similaire. Pour cette raison, cette documentation ne présentera des exemples que pour deux de ces aides.

    Exemple 77.25. Aide de vue Flash

    Inclure du Flash dans votre page est assez simple. Le seul argument requis est l'URI de la ressource.

    <?php echo $this->htmlFlash('/path/to/flash.swf'); ?>

    Ceci affichera le code HTML suivant :

    <object data="/path/to/flash.swf" type="application/x-shockwave-flash"
        
    classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
        
    codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab">
    </
    object>

    Cependant vous pouvez aussi spécifier des attributs, des paramètres et du contenu qui peuvent être affichés avec la balise <object>. Ceci peut être montré avec l'aide de vue htmlObject.

    Exemple 77.26. Personnalisation d'un objet en fournissant des arguments additionnels

    Le premier argument de l'aide Object est toujours requis. Il s'agit de l'URI de la ressource à inclure. Le second argument est seulement requis par l'aide htmlObject. Les autres aides contiennent déjà la bonne valeur pour cet argument. Le troisième argument est utilisé pour fournir des attributs à l'élément object. Seul un tableau de paires clé/valeur est accepté. classid ou codebase sont des exemples de tels attributs. Le quatrième paramètre ne prend aussi qu'un tableau de paires clé/valeur est les utilise pour créer des éléments <param>. Enfin, vous avez la possibilité de fournir un contenu additionnel à l'objet en cinquième paramètre. Voici donc un exemple qui utilise tous le paramètres :

    <?php echo $this->htmlObject(
        
    '/path/to/file.ext',
        
    'mime/type',
        array(
            
    'attr1' => 'aval1',
            
    'attr2' => 'aval2'
        
    ),
        array(
            
    'param1' => 'pval1',
            
    'param2' => 'pval2'
        
    ),
        
    'some content'
    ); ?>

    Ceci affichera le code HTML suivant :

    <object data="/path/to/file.ext" type="mime/type"
            
    attr1="aval1" attr2="aval2">
        <
    param name="param1" value="pval1" />
        <
    param name="param2" value="pval2" />
        
    some content
    </object>

    77.4.1.14. L'aide de vue InlineScript

    L'élément HTML <script> est utilisé pour fournir des éléments de script côté client ou pour lier des ressources distantes contenant des scripts s'exécutant côté client. L'aide de vue InlineScript vous permet de gérer ces deux cas. Elle est dérivée de l'aide HeadScript, et chaque méthode de cette aide est donc disponible ; cependant, vous devez utiliser la méthode inlineScript() au lieu de headScript().

    [Note] Utiliser InlineScript pour des scripts dans le corps ("body") HTML

    InlineScript, peut être utilisé quand vous souhaitez inclure des scripts dans votre body HTML. Placer ces scripts en fin de votre document est une bonne pratique pour améliorer la vitesse de distribution de votre page, particulièrement quand vous utilisez des scripts d'analyses fournis par des tiers.

    Certaines librairies JS doivent être incluses dans la partie head du HTML ; utilisez l'aide vue HeadScript pour ces scripts.

    77.4.1.15. L'aide de vue JSON

    Quand vous créez des vues qui retournent du JSON, il est important de paramétrer aussi les en-têtes de réponse appropriés. L'aide vue JSON réalise exactement cela. De plus, par défaut, elle désactive l'éventuel layout (s'il est activé), puisque les layouts sont rarement utilisés dans les réponses JSON.

    L'aide de vue JSON ajoute l'en-tête suivant :

    Content-Typeapplication/json

    Beaucoup de librairies AJAX recherche cet en-tête quand elles analysent les réponses pour déterminer comment le contenu doit être géré.

    L'utilisation de l'aide de vue JSON est très simple :

    <?php echo $this->json($this->data?>
    [Note] Keeping layouts and enabling encoding using Zend_Json_Expr

    Each method in the JSON helper accepts a second, optional argument. This second argument can be a boolean flag to enable or disable layouts, or an array of options that will be passed to Zend_Json::encode() and used internally to encode data.

    To keep layouts, the second parameter needs to be boolean TRUE. When the second parameter is an array, keeping layouts can be achieved by including a keepLayouts key with a value of a boolean TRUE.

    // Boolean true as second argument enables layouts:
    echo $this->json($this->datatrue);

    // Or boolean true as "keepLayouts" key:
    echo $this->json($this->data, array('keepLayouts' => true));

    Zend_Json::encode allows the encoding of native JSON expressions using Zend_Json_Expr objects. This option is disabled by default. To enable this option, pass a boolean TRUE to the enableJsonExprFinder key of the options array:

    <?php echo $this->json($this->data, array(
        
    'enableJsonExprFinder' => true,
        
    'keepLayouts'          => true,
    )) 
    ?>

    77.4.1.16. Navigation Helpers

    The navigation helpers are used for rendering navigational elements from Zend_Navigation_Container instances.

    There are 5 built-in helpers:

    • Breadcrumbs, used for rendering the path to the currently active page.

    • Links, used for rendering navigational head links (e.g. <link rel="next" href="..." />)

    • Menu, used for rendering menus.

    • Sitemap, used for rendering sitemaps conforming to the Sitemaps XML format.

    • Navigation, used for proxying calls to other navigational helpers.

    All built-in helpers extend Zend_View_Helper_Navigation_HelperAbstract, which adds integration with ACL and translation. The abstract class implements the interface Zend_View_Helper_Navigation_Helper, which defines the following methods:

    • getContainer() and setContainer() gets and sets the navigation container the helper should operate on by default, and hasContainer() checks if the helper has container registered.

    • getTranslator() and setTranslator() gets and sets the translator used for translating labels and titles. getUseTranslator() and setUseTranslator() controls whether the translator should be enabled. The method hasTranslator() checks if the helper has a translator registered.

    • getAcl(), setAcl(), getRole() and setRole(), gets and sets ACL (Zend_Acl) instance and role (String or Zend_Acl_Role_Interface) used for filtering out pages when rendering. getUseAcl() and setUseAcl() controls whether ACL should be enabled. The methods hasAcl() and hasRole() checks if the helper has an ACL instance or a role registered.

    • __toString(), magic method to ensure that helpers can be rendered by echoing the helper instance directly.

    • render(), must be implemented by concrete helpers to do the actual rendering.

    In addition to the method stubs from the interface, the abstract class also implements the following methods:

    • getIndent() and setIndent() gets and sets indentation. The setter accepts a String or an Integer. In the case of an Integer, the helper will use the given number of spaces for indentation. I.e., setIndent(4) means 4 initial spaces of indentation. Indentation can be specified for all helpers except the Sitemap helper.

    • getMinDepth() and setMinDepth() gets and sets the minimum depth a page must have to be included by the helper. Setting NULL means no minimum depth.

    • getMaxDepth() and setMaxDepth() gets and sets the maximum depth a page can have to be included by the helper. Setting NULL means no maximum depth.

    • getRenderInvisible() and setRenderInvisible() gets and sets whether to render items that have been marked as invisible or not.

    • __call() is used for proxying calls to the container registered in the helper, which means you can call methods on a helper as if it was a container. See example below.

    • findActive($container, $minDepth, $maxDepth) is used for finding the deepest active page in the given container. If depths are not given, the method will use the values retrieved from getMinDepth() and getMaxDepth(). The deepest active page must be between $minDepth and $maxDepth inclusively. Returns an array containing a reference to the found page instance and the depth at which the page was found.

    • htmlify() renders an 'a' HTML element from a Zend_Navigation_Page instance.

    • accept() is used for determining if a page should be accepted when iterating containers. This method checks for page visibility and verifies that the helper's role is allowed access to the page's resource and privilege.

    • The static method setDefaultAcl() is used for setting a default ACL object that will be used by helpers.

    • The static method setDefaultRole() is used for setting a default ACL that will be used by helpers

    If a navigation container is not explicitly set in a helper using $helper->setContainer($nav), the helper will look for a container instance with the key Zend_Navigation in the registry. If a container is not explicitly set or found in the registry, the helper will create an empty Zend_Navigation container when calling $helper->getContainer().

    Exemple 77.27. Proxying calls to the navigation container

    Navigation view helpers use the magic method __call() to proxy method calls to the navigation container that is registered in the view helper.

    $this->navigation()->addPage(array(
        
    'type' => 'uri',
        
    'label' => 'New page'));

    The call above will add a page to the container in the Navigation helper.


    77.4.1.16.1. Translation of labels and titles

    The navigation helpers support translation of page labels and titles. You can set a translator of type Zend_Translate or Zend_Translate_Adapter in the helper using $helper->setTranslator($translator), or like with other I18n-enabled components; by adding the translator to the registry by using the key Zend_Translate.

    If you want to disable translation, use $helper->setUseTranslator(false).

    The proxy helper will inject its own translator to the helper it proxies to if the proxied helper doesn't already have a translator.

    [Note] Note

    There is no translation in the sitemap helper, since there are no page labels or titles involved in an XML sitemap.

    77.4.1.16.2. Integration with ACL

    All navigational view helpers support ACL inherently from the class Zend_View_Helper_Navigation_HelperAbstract. A Zend_Acl object can be assigned to a helper instance with $helper->setAcl($acl), and role with $helper->setRole('member') or $helper->setRole(new Zend_Acl_Role('member')) . If ACL is used in the helper, the role in the helper must be allowed by the ACL to access a page's resource and/or have the page's privilege for the page to be included when rendering.

    If a page is not accepted by ACL, any descendant page will also be excluded from rendering.

    The proxy helper will inject its own ACL and role to the helper it proxies to if the proxied helper doesn't already have any.

    The examples below all show how ACL affects rendering.

    77.4.1.16.3. Navigation setup used in examples

    This example shows the setup of a navigation container for a fictional software company.

    Notes on the setup:

    • The domain for the site is www.example.com.

    • Interesting page properties are marked with a comment.

    • Unless otherwise is stated in other examples, the user is requesting the URL http://www.example.com/products/server/faq/, which translates to the page labeled FAQ under Foo Server.

    • The assumed ACL and router setup is shown below the container setup.

    /*
     * Navigation container (config/array)

     * Each element in the array will be passed to
     * Zend_Navigation_Page::factory() when constructing
     * the navigation container below.
     */
    $pages = array(
        array(
            
    'label'      => 'Home',
            
    'title'      => 'Go Home',
            
    'module'     => 'default',
            
    'controller' => 'index',
            
    'action'     => 'index',
            
    'order'      => -100 // make sure home is the first page
        
    ),
        array(
            
    'label'      => 'Special offer this week only!',
            
    'module'     => 'store',
            
    'controller' => 'offer',
            
    'action'     => 'amazing',
            
    'visible'    => false // not visible
        
    ),
        array(
            
    'label'      => 'Products',
            
    'module'     => 'products',
            
    'controller' => 'index',
            
    'action'     => 'index',
            
    'pages'      => array(
                array(
                    
    'label'      => 'Foo Server',
                    
    'module'     => 'products',
                    
    'controller' => 'server',
                    
    'action'     => 'index',
                    
    'pages'      => array(
                        array(
                            
    'label'      => 'FAQ',
                            
    'module'     => 'products',
                            
    'controller' => 'server',
                            
    'action'     => 'faq',
                            
    'rel'        => array(
                                
    'canonical' => 'http://www.example.com/?page=faq',
                                
    'alternate' => array(
                                    
    'module'     => 'products',
                                    
    'controller' => 'server',
                                    
    'action'     => 'faq',
                                    
    'params'     => array('format' => 'xml')
                                )
                            )
                        ),
                        array(
                            
    'label'      => 'Editions',
                            
    'module'     => 'products',
                            
    'controller' => 'server',
                            
    'action'     => 'editions'
                        
    ),
                        array(
                            
    'label'      => 'System Requirements',
                            
    'module'     => 'products',
                            
    'controller' => 'server',
                            
    'action'     => 'requirements'
                        
    )
                    )
                ),
                array(
                    
    'label'      => 'Foo Studio',
                    
    'module'     => 'products',
                    
    'controller' => 'studio',
                    
    'action'     => 'index',
                    
    'pages'      => array(
                        array(
                            
    'label'      => 'Customer Stories',
                            
    'module'     => 'products',
                            
    'controller' => 'studio',
                            
    'action'     => 'customers'
                        
    ),
                        array(
                            
    'label'      => 'Support',
                            
    'module'     => 'prodcts',
                            
    'controller' => 'studio',
                            
    'action'     => 'support'
                        
    )
                    )
                )
            )
        ),
        array(
            
    'label'      => 'Company',
            
    'title'      => 'About us',
            
    'module'     => 'company',
            
    'controller' => 'about',
            
    'action'     => 'index',
            
    'pages'      => array(
                array(
                    
    'label'      => 'Investor Relations',
                    
    'module'     => 'company',
                    
    'controller' => 'about',
                    
    'action'     => 'investors'
                
    ),
                array(
                    
    'label'      => 'News',
                    
    'class'      => 'rss'// class
                    
    'module'     => 'company',
                    
    'controller' => 'news',
                    
    'action'     => 'index',
                    
    'pages'      => array(
                        array(
                            
    'label'      => 'Press Releases',
                            
    'module'     => 'company',
                            
    'controller' => 'news',
                            
    'action'     => 'press'
                        
    ),
                        array(
                            
    'label'      => 'Archive',
                            
    'route'      => 'archive'// route
                            
    'module'     => 'company',
                            
    'controller' => 'news',
                            
    'action'     => 'archive'
                        
    )
                    )
                )
            )
        ),
        array(
            
    'label'      => 'Community',
            
    'module'     => 'community',
            
    'controller' => 'index',
            
    'action'     => 'index',
            
    'pages'      => array(
                array(
                    
    'label'      => 'My Account',
                    
    'module'     => 'community',
                    
    'controller' => 'account',
                    
    'action'     => 'index',
                    
    'resource'   => 'mvc:community.account' // resource
                
    ),
                array(
                    
    'label' => 'Forums',
                    
    'uri'   => 'http://forums.example.com/',
                    
    'class' => 'external' // class
                
    )
            )
        ),
        array(
            
    'label'      => 'Administration',
            
    'module'     => 'admin',
            
    'controller' => 'index',
            
    'action'     => 'index',
            
    'resource'   => 'mvc:admin'// resource
            
    'pages'      => array(
                array(
                    
    'label'      => 'Write new article',
                    
    'module'     => 'admin',
                    
    'controller' => 'post',
                    
    'aciton'     => 'write'
                
    )
            )
        )
    );

    // Create container from array
    $container = new Zend_Navigation($pages);

    // Store the container in the proxy helper:
    $view->getHelper('navigation')->setContainer($container);

    // ...or simply:
    $view->navigation($container);

    // ...or store it in the reigstry:
    Zend_Registry::set('Zend_Navigation'$container);

    In addition to the container above, the following setup is assumed:

    // Setup router (default routes and 'archive' route):
    $front Zend_Controller_Front::getInstance();
    $router $front->getRouter();
    $router->addDefaultRoutes();
    $router->addRoute(
        
    'archive',
        new 
    Zend_Controller_Router_Route(
            
    '/archive/:year',
            array(
                
    'module'     => 'company',
                
    'controller' => 'news',
                
    'action'     => 'archive',
                
    'year'       => (int) date('Y') - 1
            
    ),
            array(
    'year' => '\d+')
        )
    );

    // Setup ACL:
    $acl = new Zend_Acl();
    $acl->addRole(new Zend_Acl_Role('member'));
    $acl->addRole(new Zend_Acl_Role('admin'));
    $acl->add(new Zend_Acl_Resource('mvc:admin'));
    $acl->add(new Zend_Acl_Resource('mvc:community.account'));
    $acl->allow('member''mvc:community.account');
    $acl->allow('admin'null);

    // Store ACL and role in the proxy helper:
    $view->navigation()->setAcl($acl)->setRole('member');

    // ...or set default ACL and role statically:
    Zend_View_Helper_Navigation_HelperAbstract::setDefaultAcl($acl);
    Zend_View_Helper_Navigation_HelperAbstract::setDefaultRole('member');
    77.4.1.16.4. Breadcrumbs Helper

    Breadcrumbs are used for indicating where in a sitemap a user is currently browsing, and are typically rendered like this: "You are here: Home > Products > FantasticProduct 1.0". The breadcrumbs helper follows the guidelines from Breadcrumbs Pattern - Yahoo! Design Pattern Library, and allows simple customization (minimum/maximum depth, indentation, separator, and whether the last element should be linked), or rendering using a partial view script.

    The Breadcrumbs helper works like this; it finds the deepest active page in a navigation container, and renders an upwards path to the root. For MVC pages, the "activeness" of a page is determined by inspecting the request object, as stated in the section on Zend_Navigation_Page_Mvc.

    The helper sets the minDepth property to 1 by default, meaning breadcrumbs will not be rendered if the deepest active page is a root page. If maxDepth is specified, the helper will stop rendering when at the specified depth (e.g. stop at level 2 even if the deepest active page is on level 3).

    Methods in the breadcrumbs helper:

    • {get|set}Separator() gets/sets separator string that is used between breadcrumbs. Defualt is ' &gt; '.

    • {get|set}LinkLast() gets/sets whether the last breadcrumb should be rendered as an anchor or not. Default is FALSE.

    • {get|set}Partial() gets/sets a partial view script that should be used for rendering breadcrumbs. If a partial view script is set, the helper's render() method will use the renderPartial() method. If no partial is set, the renderStraight() method is used. The helper expects the partial to be a String or an Array with two elements. If the partial is a String, it denotes the name of the partial script to use. If it is an Array, the first element will be used as the name of the partial view script, and the second element is the module where the script is found.

    • renderStraight() is the default render method.

    • renderPartial() is used for rendering using a partial view script.

    Exemple 77.28. Rendering breadcrumbs

    This example shows how to render breadcrumbs with default settings.

    In a view script or layout:
    <?
    php echo $this->navigation()->breadcrumbs(); ?>

    The two calls above take advantage of the magic __toString() method,
    and are equivalent to:
    <?php echo $this->navigation()->breadcrumbs()->render(); ?>

    Output:
    <a href="/products">Products</a> &amp;gt; <a href="/products/server">Foo Server</a> &amp;gt; FAQ

    Exemple 77.29. Specifying indentation

    This example shows how to render breadcrumbs with initial indentation.

    Rendering with 8 spaces indentation:
    <?
    php echo $this->navigation()->breadcrumbs()->setIndent(8);?>

    Output:
            <a href="/products">Products</a> &amp;gt; <a href="/products/server">Foo Server</a> &amp;gt; FAQ

    Exemple 77.30. Customize breadcrumbs output

    This example shows how to customze breadcrumbs output by specifying various options.

    In a view script or layout:

    <?
    php
    echo $this->navigation()
              ->
    breadcrumbs()
              ->
    setLinkLast(true)                   // link last page
              
    ->setMaxDepth(1)                      // stop at level 1
              
    ->setSeparator(' &amp;#9654;' PHP_EOL); // cool separator with newline
    ?>

    Output:
    <a href="/products">Products</a> &amp;#9654;
    <a href="/products/server">Foo Server</a>

    /////////////////////////////////////////////////////

    Setting minimum depth required to render breadcrumbs:

    <?php
    $this
    ->navigation()->breadcrumbs()->setMinDepth(10);
    echo 
    $this->navigation()->breadcrumbs();
    ?>

    Output:
    Nothing, because the deepest active page is not at level 10 or deeper.

    Exemple 77.31. Rendering breadcrumbs using a partial view script

    This example shows how to render customized breadcrumbs using a partial vew script. By calling setPartial(), you can specify a partial view script that will be used when calling render(). When a partial is specified, the renderPartial() method will be called. This method will find the deepest active page and pass an array of pages that leads to the active page to the partial view script.

    In a layout:

    $partial = ;
    echo 
    $this->navigation()->breadcrumbs()
                            ->
    setPartial(array('breadcrumbs.phtml''default'));

    Contents of application/modules/default/views/breadcrumbs.phtml:

    echo implode(', 'array_map(
            
    create_function('$a''return $a->getLabel();'),
            
    $this->pages));

    Output:

    ProductsFoo ServerFAQ

    77.4.1.16.5. Links Helper

    The links helper is used for rendering HTML LINK elements. Links are used for describing document relationships of the currently active page. Read more about links and link types at Document relationships: the LINK element (HTML4 W3C Rec.) and Link types (HTML4 W3C Rec.) in the HTML4 W3C Recommendation.

    There are two types of relations; forward and reverse, indicated by the keyords 'rel' and 'rev'. Most methods in the helper will take a $rel param, which must be either 'rel' or 'rev'. Most methods also take a $type param, which is used for specifying the link type (e.g. alternate, start, next, prev, chapter, etc).

    Relationships can be added to page objects manually, or found by traversing the container registered in the helper. The method findRelation($page, $rel, $type) will first try to find the given $rel of $type from the $page by calling $page->findRel($type) or $page->findRel($type). If the $page has a relation that can be converted to a page instance, that relation will be used. If the $page instance doesn't have the specified $type, the helper will look for a method in the helper named search$rel$type (e.g. searchRelNext() or searchRevAlternate()). If such a method exists, it will be used for determining the $page's relation by traversing the container.

    Not all relations can be determined by traversing the container. These are the relations that will be found by searching:

    • searchRelStart(), forward 'start' relation: the first page in the container.

    • searchRelNext(), forward 'next' relation; finds the next page in the container, i.e. the page after the active page.

    • searchRelPrev(), forward 'prev' relation; finds the previous page, i.e. the page before the active page.

    • searchRelChapter(), forward 'chapter' relations; finds all pages on level 0 except the 'start' relation or the active page if it's on level 0.

    • searchRelSection(), forward 'section' relations; finds all child pages of the active page if the active page is on level 0 (a 'chapter').

    • searchRelSubsection(), forward 'subsection' relations; finds all child pages of the active page if the active pages is on level 1 (a 'section').

    • searchRevSection(), reverse 'section' relation; finds the parent of the active page if the active page is on level 1 (a 'section').

    • searchRevSubsection(), reverse 'subsection' relation; finds the parent of the active page if the active page is on level 2 (a 'subsection').

    [Note] Note

    When looking for relations in the page instance ($page->getRel($type) or $page->getRev($type)), the helper accepts the values of type String, Array, Zend_Config, or Zend_Navigation_Page. If a string is found, it will be converted to a Zend_Navigation_Page_Uri. If an array or a config is found, it will be converted to one or several page instances. If the first key of the array/config is numeric, it will be considered to contain several pages, and each element will be passed to the page factory. If the first key is not numeric, the array/config will be passed to the page factory directly, and a single page will be returned.

    The helper also supports magic methods for finding relations. E.g. to find forward alternate relations, call $helper->findRelAlternate($page), and to find reverse section relations, call $helper->findRevSection($page). Those calls correspond to $helper->findRelation($page, 'rel', 'alternate'); and $helper->findRelation($page, 'rev', 'section'); respectively.

    To customize which relations should be rendered, the helper uses a render flag. The render flag is an integer value, and will be used in a bitwse and (&) operation against the helper's render constants to determine if the relation that belongs to the render constant should be rendered.

    See the example below for more information.

    • Zend_View_Helper_Navigation_Link::RENDER_ALTERNATE

    • Zend_View_Helper_Navigation_Link::RENDER_STYLESHEET

    • Zend_View_Helper_Navigation_Link::RENDER_START

    • Zend_View_Helper_Navigation_Link::RENDER_NEXT

    • Zend_View_Helper_Navigation_Link::RENDER_PREV

    • Zend_View_Helper_Navigation_Link::RENDER_CONTENTS

    • Zend_View_Helper_Navigation_Link::RENDER_INDEX

    • Zend_View_Helper_Navigation_Link::RENDER_GLOSSARY

    • Zend_View_Helper_Navigation_Link::RENDER_COPYRIGHT

    • Zend_View_Helper_Navigation_Link::RENDER_CHAPTER

    • Zend_View_Helper_Navigation_Link::RENDER_SECTION

    • Zend_View_Helper_Navigation_Link::RENDER_SUBSECTION

    • Zend_View_Helper_Navigation_Link::RENDER_APPENDIX

    • Zend_View_Helper_Navigation_Link::RENDER_HELP

    • Zend_View_Helper_Navigation_Link::RENDER_BOOKMARK

    • Zend_View_Helper_Navigation_Link::RENDER_CUSTOM

    • Zend_View_Helper_Navigation_Link::RENDER_ALL

    The constants from RENDER_ALTERNATE to RENDER_BOOKMARK denote standard HTML link types. RENDER_CUSTOM denotes non-standard relations that specified in pages. RENDER_ALL denotes standard and non-standard relations.

    Methods in the links helper:

    • {get|set}RenderFlag() gets/sets the render flag. Default is RENDER_ALL. See examples below on how to set the render flag.

    • findAllRelations() finds all relations of all types for a given page.

    • findRelation() finds all relations of a given type from a given page.

    • searchRel{Start|Next|Prev|Chapter|Section|Subsection}() traverses a container to find forward relations to the start page, the next page, the previous page, chapters, sections, and subsections.

    • searchRev{Section|Subsection}() traverses a container to find reverse relations to sections or subsections.

    • renderLink() renders a single link element.

    Exemple 77.32. Specify relations in pages

    This example shows how to specify relations in pages.

    $container = new Zend_Navigation(array(
        array(
            
    'label' => 'Relations using strings',
            
    'rel'   => array(
                
    'alternate' => 'http://www.example.org/'
            
    ),
            
    'rev'   => array(
                
    'alternate' => 'http://www.example.net/'
            
    )
        ),
        array(
            
    'label' => 'Relations using arrays',
            
    'rel'   => array(
                
    'alternate' => array(
                    
    'label' => 'Example.org',
                    
    'uri'   => 'http://www.example.org/'
                
    )
            )
        ),
        array(
            
    'label' => 'Relations using configs',
            
    'rel'   => array(
                
    'alternate' => new Zend_Config(array(
                    
    'label' => 'Example.org',
                    
    'uri'   => 'http://www.example.org/'
                
    ))
            )
        ),
        array(
            
    'label' => 'Relations using pages instance',
            
    'rel'   => array(
                
    'alternate' => Zend_Navigation_Page::factory(array(
                    
    'label' => 'Example.org',
                    
    'uri'   => 'http://www.example.org/'
                
    ))
            )
        )
    ));

    Exemple 77.33. Default rendering of links

    This example shows how to render a menu from a container registered/found in the view helper.

    In a view script or layout:
    <?
    php echo $this->view->navigation()->links(); ?>

    Output:
    <link rel="alternate" href="/products/server/faq/format/xml">
    <link rel="start" href="/" title="Home">
    <link rel="next" href="/products/server/editions" title="Editions">
    <link rel="prev" href="/products/server" title="Foo Server">
    <link rel="chapter" href="/products" title="Products">
    <link rel="chapter" href="/company/about" title="Company">
    <link rel="chapter" href="/community" title="Community">
    <link rel="canonical" href="http://www.example.com/?page=server-faq">
    <link rev="subsection" href="/products/server" title="Foo Server">

    Exemple 77.34. Specify which relations to render

    This example shows how to specify which relations to find and render.

    Render only startnext, and prev:
    $helper->setRenderFlag(Zend_View_Helper_Navigation_Links::RENDER_START |
                           
    Zend_View_Helper_Navigation_Links::RENDER_NEXT |
                           
    Zend_View_Helper_Navigation_Links::RENDER_PREV);

    Output:
    <
    link rel="start" href="/" title="Home">
    <
    link rel="next" href="/products/server/editions" title="Editions">
    <
    link rel="prev" href="/products/server" title="Foo Server">
    Render only native link types:
    $helper->setRenderFlag(Zend_View_Helper_Navigation_Links::RENDER_ALL ^
                           
    Zend_View_Helper_Navigation_Links::RENDER_CUSTOM);

    Output:
    <
    link rel="alternate" href="/products/server/faq/format/xml">
    <
    link rel="start" href="/" title="Home">
    <
    link rel="next" href="/products/server/editions" title="Editions">
    <
    link rel="prev" href="/products/server" title="Foo Server">
    <
    link rel="chapter" href="/products" title="Products">
    <
    link rel="chapter" href="/company/about" title="Company">
    <
    link rel="chapter" href="/community" title="Community">
    <
    link rev="subsection" href="/products/server" title="Foo Server">
    Render all but chapter:
    $helper->setRenderFlag(Zend_View_Helper_Navigation_Links::RENDER_ALL ^
                           
    Zend_View_Helper_Navigation_Links::RENDER_CHAPTER);

    Output:
    <
    link rel="alternate" href="/products/server/faq/format/xml">
    <
    link rel="start" href="/" title="Home">
    <
    link rel="next" href="/products/server/editions" title="Editions">
    <
    link rel="prev" href="/products/server" title="Foo Server">
    <
    link rel="canonical" href="http://www.example.com/?page=server-faq">
    <
    link rev="subsection" href="/products/server" title="Foo Server">

    77.4.1.16.6. Menu Helper

    The Menu helper is used for rendering menus from navigation containers. By default, the menu will be rendered using HTML UL and LI tags, but the helper also allows using a partial view script.

    Methods in the Menu helper:

    • {get|set}UlClass() gets/sets the CSS class used in renderMenu().

    • {get|set}OnlyActiveBranch() gets/sets a flag specifying whether only the active branch of a container should be rendered.

    • {get|set}RenderParents() gets/sets a flag specifying whether parents should be rendered when only rendering active branch of a container. If set to FALSE, only the deepest active menu will be rendered.

    • {get|set}Partial() gets/sets a partial view script that should be used for rendering menu. If a partial view script is set, the helper's render() method will use the renderPartial() method. If no partial is set, the renderMenu() method is used. The helper expects the partial to be a String or an Array with two elements. If the partial is a String, it denotes the name of the partial script to use. If it is an Array, the first element will be used as the name of the partial view script, and the second element is the module where the script is found.

    • htmlify() overrides the method from the abstract class to return span elements if the page has no href.

    • renderMenu($container = null, $options = array()) is the default render method, and will render a container as a HTML UL list.

      If $container is not given, the container registered in the helper will be rendered.

      $options is used for overriding options specified temporarily without rsetting the values in the helper instance. It is an associative array where each key corresponds to an option in the helper.

      Recognized options:

      • indent; indentation. Expects a String or an int value.

      • minDepth; minimum depth. Expcects an int or NULL (no minimum depth).

      • maxDepth; maximum depth. Expcects an int or NULL (no maximum depth).

      • ulClass; CSS class for ul element. Expects a String.

      • onlyActiveBranch; whether only active branch should be rendered. Expects a Boolean value.

      • renderParents; whether parents should be rendered if only rendering active branch. Expects a Boolean value.

      If an option is not given, the value set in the helper will be used.

    • renderPartial() is used for rendering the menu using a partial view script.

    • renderSubMenu() renders the deepest menu level of a container's active branch.

    Exemple 77.35. Rendering a menu

    This example shows how to render a menu from a container registered/found in the view helper. Notice how pages are filtered out based on visibility and ACL.

    In a view script or layout:
    <?
    php echo $this->navigation()->menu()->render() ?>

    Or simply:
    <?php echo $this->navigation()->menu() ?>

    Output:
    <ul class="navigation">
        <li>
            <a title="Go Home" href="/">Home</a>
        </li>
        <li class="active">
            <a href="/products">Products</a>
            <ul>
                <li class="active">
                    <a href="/products/server">Foo Server</a>
                    <ul>
                        <li class="active">
                            <a href="/products/server/faq">FAQ</a>
                        </li>
                        <li>
                            <a href="/products/server/editions">Editions</a>
                        </li>
                        <li>
                            <a href="/products/server/requirements">System Requirements</a>
                        </li>
                    </ul>
                </li>
                <li>
                    <a href="/products/studio">Foo Studio</a>
                    <ul>
                        <li>
                            <a href="/products/studio/customers">Customer Stories</a>
                        </li>
                        <li>
                            <a href="/prodcts/studio/support">Support</a>
                        </li>
                    </ul>
                </li>
            </ul>
        </li>
        <li>
            <a title="About us" href="/company/about">Company</a>
            <ul>
                <li>
                    <a href="/company/about/investors">Investor Relations</a>
                </li>
                <li>
                    <a class="rss" href="/company/news">News</a>
                    <ul>
                        <li>
                            <a href="/company/news/press">Press Releases</a>
                        </li>
                        <li>
                            <a href="/archive">Archive</a>
                        </li>
                    </ul>
                </li>
            </ul>
        </li>
        <li>
            <a href="/community">Community</a>
            <ul>
                <li>
                    <a href="/community/account">My Account</a>
                </li>
                <li>
                    <a class="external" href="http://forums.example.com/">Forums</a>
                </li>
            </ul>
        </li>
    </ul>

    Exemple 77.36. Calling renderMenu() directly

    This example shows how to render a menu that is not registered in the view helper by calling the renderMenu() directly and specifying a few options.

    <?php
    // render only the 'Community' menu
    $community $this->navigation()->findOneByLabel('Community');
    $options = array(
        
    'indent'  => 16,
        
    'ulClass' => 'community'
    );
    echo 
    $this->navigation()
              ->
    menu()
              ->
    renderMenu($community$options);
    ?>
    Output:
                    <ul class="community">
                        <li>
                            <a href="/community/account">My Account</a>
                        </li>
                        <li>
                            <a class="external" href="http://forums.example.com/">Forums</a>
                        </li>
                    </ul>

    Exemple 77.37. Rendering the deepest active menu

    This example shows how the renderSubMenu() will render the deepest sub menu of the active branch.

    Calling renderSubMenu($container, $ulClass, $indent) is equivalent to calling renderMenu($container, $options) with the following options:

    array(
        
    'ulClass'          => $ulClass,
        
    'indent'           => $indent,
        
    'minDepth'         => null,
        
    'maxDepth'         => null,
        
    'onlyActiveBranch' => true,
        
    'renderParents'    => false
    );
    <?php
    echo $this->navigation()
              ->
    menu()
              ->
    renderSubMenu(null'sidebar'4);
    ?>

    The output will be the same if 'FAQ' or 'Foo Server' is active:
        <ul class="sidebar">
            <li class="active">
                <a href="/products/server/faq">FAQ</a>
            </li>
            <li>
                <a href="/products/server/editions">Editions</a>
            </li>
            <li>
                <a href="/products/server/requirements">System Requirements</a>
            </li>
        </ul>

    Exemple 77.38. Rendering a menu with maximum depth

    <?php
    echo $this->navigation()
              ->
    menu()
              ->
    setMaxDepth(1);
    ?>

    Output:
    <ul class="navigation">
        <li>
            <a title="Go Home" href="/">Home</a>
        </li>
        <li class="active">
            <a href="/products">Products</a>
            <ul>
                <li class="active">
                    <a href="/products/server">Foo Server</a>
                </li>
                <li>
                    <a href="/products/studio">Foo Studio</a>
                </li>
            </ul>
        </li>
        <li>
            <a title="About us" href="/company/about">Company</a>
            <ul>
                <li>
                    <a href="/company/about/investors">Investor Relations</a>
                </li>
                <li>
                    <a class="rss" href="/company/news">News</a>
                </li>
            </ul>
        </li>
        <li>
            <a href="/community">Community</a>
            <ul>
                <li>
                    <a href="/community/account">My Account</a>
                </li>
                <li>
                    <a class="external" href="http://forums.example.com/">Forums</a>
                </li>
            </ul>
        </li>
    </ul>

    Exemple 77.39. Rendering a menu with minimum depth

    <?php
    echo $this->navigation()
              ->
    menu()
              ->
    setMinDepth(1);
    ?>

    Output:
    <ul class="navigation">
        <li class="active">
            <a href="/products/server">Foo Server</a>
            <ul>
                <li class="active">
                    <a href="/products/server/faq">FAQ</a>
                </li>
                <li>
                    <a href="/products/server/editions">Editions</a>
                </li>
                <li>
                    <a href="/products/server/requirements">System Requirements</a>
                </li>
            </ul>
        </li>
        <li>
            <a href="/products/studio">Foo Studio</a>
            <ul>
                <li>
                    <a href="/products/studio/customers">Customer Stories</a>
                </li>
                <li>
                    <a href="/prodcts/studio/support">Support</a>
                </li>
            </ul>
        </li>
        <li>
            <a href="/company/about/investors">Investor Relations</a>
        </li>
        <li>
            <a class="rss" href="/company/news">News</a>
            <ul>
                <li>
                    <a href="/company/news/press">Press Releases</a>
                </li>
                <li>
                    <a href="/archive">Archive</a>
                </li>
            </ul>
        </li>
        <li>
            <a href="/community/account">My Account</a>
        </li>
        <li>
            <a class="external" href="http://forums.example.com/">Forums</a>
        </li>
    </ul>

    Exemple 77.40. Rendering only the active branch of a menu

    <?php
    echo $this->navigation()
              ->
    menu()
              ->
    setOnlyActiveBranch(true);
    ?>

    Output:
    <ul class="navigation">
        <li class="active">
            <a href="/products">Products</a>
            <ul>
                <li class="active">
                    <a href="/products/server">Foo Server</a>
                    <ul>
                        <li class="active">
                            <a href="/products/server/faq">FAQ</a>
                        </li>
                        <li>
                            <a href="/products/server/editions">Editions</a>
                        </li>
                        <li>
                            <a href="/products/server/requirements">System Requirements</a>
                        </li>
                    </ul>
                </li>
            </ul>
        </li>
    </ul>

    Exemple 77.41.  Rendering only the active branch of a menu with minimum depth

    <?php
    echo $this->navigation()
              ->
    menu()
              ->
    setOnlyActiveBranch(true)
              ->
    setMinDepth(1);
    ?>

    Output:
    <ul class="navigation">
        <li class="active">
            <a href="/products/server">Foo Server</a>
            <ul>
                <li class="active">
                    <a href="/products/server/faq">FAQ</a>
                </li>
                <li>
                    <a href="/products/server/editions">Editions</a>
                </li>
                <li>
                    <a href="/products/server/requirements">System Requirements</a>
                </li>
            </ul>
        </li>
    </ul>

    Exemple 77.42.  Rendering only the active branch of a menu with maximum depth

    <?php
    echo $this->navigation()
              ->
    menu()
              ->
    setOnlyActiveBranch(true)
              ->
    setMaxDepth(1);
    ?>

    Output:
    <ul class="navigation">
        <li class="active">
            <a href="/products">Products</a>
            <ul>
                <li class="active">
                    <a href="/products/server">Foo Server</a>
                </li>
                <li>
                    <a href="/products/studio">Foo Studio</a>
                </li>
            </ul>
        </li>
    </ul>

    Exemple 77.43.  Rendering only the active branch of a menu with maximum depth and no parents

    <?php
    echo $this->navigation()
              ->
    menu()
              ->
    setOnlyActiveBranch(true)
              ->
    setRenderParents(false)
              ->
    setMaxDepth(1);
    ?>

    Output:
    <ul class="navigation">
        <li class="active">
            <a href="/products/server">Foo Server</a>
        </li>
        <li>
            <a href="/products/studio">Foo Studio</a>
        </li>
    </ul>

    Exemple 77.44. Rendering a custom menu using a partial view script

    This example shows how to render a custom menu using a partial vew script. By calling setPartial(), you can specify a partial view script that will be used when calling render(). When a partial is specified, the renderPartial() method will be called. This method will assign the container to the view with the key container.

    In a layout:

    $partial = array('menu.phtml''default');
    $this->navigation()->menu()->setPartial($partial);
    echo 
    $this->navigation()->menu()->render();

    In application/modules/default/views/menu.phtml:

    foreach ($this->container as $page) {
        echo 
    $this->navigation()->menu()->htmlify($page), PHP_EOL;
    }

    Output:

    <a title="Go Home" href="/">Home</a>
    <
    a href="/products">Products</a>
    <
    a title="About us" href="/company/about">Company</a>
    <
    a href="/community">Community</a>

    77.4.1.16.7. Sitemap Helper

    The Sitemap helper is used for generating XML sitemaps, as defined by the Sitemaps XML format. Read more about Sitemaps on Wikpedia.

    By default, the sitemap helper uses sitemap validators to validate each element that is rendered. This can be disabled by calling $helper->setUseSitemapValidators(false).

    [Note] Note

    If you disable sitemap validators, the custom properties (see table) are not validated at all.

    The sitemap helper also supports Sitemap XSD Schema validation of the generated sitemap. This is disabled by default, since it will require a request to the Schema file. It can be enabled with $helper->setUseSchemaValidation(true).

    Tableau 77.1. Sitemap XML elements

    Element Description
    loc Absolute URL to page. An absolute URL will be generated by the helper.
    lastmod

    The date of last modification of the file, in W3C Datetime format. This time portion can be omitted if desired, and only use YYYY-MM-DD.

    The helper will try to retrieve the lastmod value from the page's custom property lastmod if it is set in the page. If the value is not a valid date, it is ignored.

    changefreq

    How frequently the page is likely to change. This value provides general information to search engines and may not correlate exactly to how often they crawl the page. Valid values are:

    • always

    • hourly

    • daily

    • weekly

    • monthly

    • yearly

    • never

    The helper will try to retrieve the changefreq value from the page's custom property changefreq if it is set in the page. If the value is not valid, it is ignored.

    priority

    The priority of this URL relative to other URLs on your site. Valid values range from 0.0 to 1.0.

    The helper will try to retrieve the priority value from the page's custom property priority if it is set in the page. If the value is not valid, it is ignored.


    Methods in the sitemap helper:

    • {get|set}FormatOutput() gets/sets a flag indicating whether XML output should be formatted. This corresponds to the formatOutput property of the native DOMDocument class. Read more at PHP: DOMDocument - Manual. Default is FALSE.

    • {get|set}UseXmlDeclaration() gets/sets a flag indicating whether the XML declaration should be included when rendering. Default is TRUE.

    • {get|set}UseSitemapValidators() gets/sets a flag indicating whether sitemap validators should be used when generating the DOM sitemap. Default is TRUE.

    • {get|set}UseSchemaValidation() gets/sets a flag indicating whether the helper should use XML Schema validation when generating the DOM sitemap. Default is FALSE. If TRUE.

    • {get|set}ServerUrl() gets/sets server URL that will be prepended to non-absolute URLs in the url() method. If no server URL is specified, it will be determined by the helper.

    • url() is used to generate absolute URLs to pages.

    • getDomSitemap() generates a DOMDocument from a given container.

    Exemple 77.45. Rendering an XML sitemap

    This example shows how to render an XML sitemap based on the setup we did further up.

    // In a view script or layout:

    // format output
    $this->navigation()
          ->
    sitemap()
          ->
    setFormatOutput(true); // default is false

    // other possible methods:
    // ->setUseXmlDeclaration(false); // default is true
    // ->setServerUrl('http://my.otherhost.com');
    // default is to detect automatically

    // print sitemap
    echo $this->navigation()->sitemap();

    Notice how pages that are invisible or pages with ACL roles incompatible with the view helper are filtered out:

    <?xml version="1.0" encoding="UTF-8"?>
    <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
      <url>
        <loc>http://www.example.com/</loc>
      </url>
      <url>
        <loc>http://www.example.com/products</loc>
      </url>
      <url>
        <loc>http://www.example.com/products/server</loc>
      </url>
      <url>
        <loc>http://www.example.com/products/server/faq</loc>
      </url>
      <url>
        <loc>http://www.example.com/products/server/editions</loc>
      </url>
      <url>
        <loc>http://www.example.com/products/server/requirements</loc>
      </url>
      <url>
        <loc>http://www.example.com/products/studio</loc>
      </url>
      <url>
        <loc>http://www.example.com/products/studio/customers</loc>
      </url>
      <url>
        <loc>http://www.example.com/prodcts/studio/support</loc>
      </url>
      <url>
        <loc>http://www.example.com/company/about</loc>
      </url>
      <url>
        <loc>http://www.example.com/company/about/investors</loc>
      </url>
      <url>
        <loc>http://www.example.com/company/news</loc>
      </url>
      <url>
        <loc>http://www.example.com/company/news/press</loc>
      </url>
      <url>
        <loc>http://www.example.com/archive</loc>
      </url>
      <url>
        <loc>http://www.example.com/community</loc>
      </url>
      <url>
        <loc>http://www.example.com/community/account</loc>
      </url>
      <url>
        <loc>http://forums.example.com/</loc>
      </url>
    </urlset>

    Render the sitemap using no ACL role (should filter out /community/account):

    echo $this->navigation()
              ->
    sitemap()
              ->
    setFormatOutput(true)
              ->
    setRole();
    <?xml version="1.0" encoding="UTF-8"?>
    <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
      <url>
        <loc>http://www.example.com/</loc>
      </url>
      <url>
        <loc>http://www.example.com/products</loc>
      </url>
      <url>
        <loc>http://www.example.com/products/server</loc>
      </url>
      <url>
        <loc>http://www.example.com/products/server/faq</loc>
      </url>
      <url>
        <loc>http://www.example.com/products/server/editions</loc>
      </url>
      <url>
        <loc>http://www.example.com/products/server/requirements</loc>
      </url>
      <url>
        <loc>http://www.example.com/products/studio</loc>
      </url>
      <url>
        <loc>http://www.example.com/products/studio/customers</loc>
      </url>
      <url>
        <loc>http://www.example.com/prodcts/studio/support</loc>
      </url>
      <url>
        <loc>http://www.example.com/company/about</loc>
      </url>
      <url>
        <loc>http://www.example.com/company/about/investors</loc>
      </url>
      <url>
        <loc>http://www.example.com/company/news</loc>
      </url>
      <url>
        <loc>http://www.example.com/company/news/press</loc>
      </url>
      <url>
        <loc>http://www.example.com/archive</loc>
      </url>
      <url>
        <loc>http://www.example.com/community</loc>
      </url>
      <url>
        <loc>http://forums.example.com/</loc>
      </url>
    </urlset>

    Render the sitemap using a maximum depth of 1.

    echo $this->navigation()
              ->
    sitemap()
              ->
    setFormatOutput(true)
              ->
    setMaxDepth(1);
    <?xml version="1.0" encoding="UTF-8"?>
    <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
      <url>
        <loc>http://www.example.com/</loc>
      </url>
      <url>
        <loc>http://www.example.com/products</loc>
      </url>
      <url>
        <loc>http://www.example.com/products/server</loc>
      </url>
      <url>
        <loc>http://www.example.com/products/studio</loc>
      </url>
      <url>
        <loc>http://www.example.com/company/about</loc>
      </url>
      <url>
        <loc>http://www.example.com/company/about/investors</loc>
      </url>
      <url>
        <loc>http://www.example.com/company/news</loc>
      </url>
      <url>
        <loc>http://www.example.com/community</loc>
      </url>
      <url>
        <loc>http://www.example.com/community/account</loc>
      </url>
      <url>
        <loc>http://forums.example.com/</loc>
      </url>
    </urlset>

    [Note] UTF-8 encoding used by default

    By default, Zend Framework uses UTF-8 as its default encoding, and, specific to this case, Zend_View does as well. Character encoding can be set differently on the view object itself using the setEncoding() method (or the the encoding instantiation parameter). However, since Zend_View_Interface does not define accessors for encoding, it's possible that if you are using a custom view implementation with the Dojo view helper, you will not have a getEncoding() method, which is what the view helper uses internally for determining the character set in which to encode.

    If you do not want to utilize UTF-8 in such a situation, you will need to implement a getEncoding() method in your custom view implementation.

    77.4.1.16.8. Navigation Helper

    The Navigation helper is a proxy helper that relays calls to other navigational helpers. It can be considered an entry point to all navigation-related view tasks. The aforementioned navigational helpers are in the namespace Zend_View_Helper_Navigation, and would thus require the path Zend/View/Helper/Navigation to be added as a helper path to the view. With the proxy helper residing in the Zend_View_Helper namespace, it will always be available, without the need to add any helper paths to the view.

    The Navigation helper finds other helpers that implement the Zend_View_Helper_Navigation_Helper interface, which means custom view helpers can also be proxied. This would, however, require that the custom helper path is added to the view.

    When proxying to other helpers, the Navigation helper can inject its container, ACL/role, and translator. This means that you won't have to explicitly set all three in all navigational helpers, nor resort to injecting by means of Zend_Registry or static methods.

    • findHelper() finds the given helper, verifies that it is a navigational helper, and injects container, ACL/role and translator.

    • {get|set}InjectContainer() gets/sets a flag indicating whether the container should be injected to proxied helpers. Default is TRUE.

    • {get|set}InjectAcl() gets/sets a flag indicating whether the ACL/role should be injected to proxied helpers. Default is TRUE.

    • {get|set}InjectTranslator() gets/sets a flag indicating whether the translator should be injected to proxied helpers. Default is TRUE.

    • {get|set}DefaultProxy() gets/sets the default proxy. Default is 'menu'.

    • render() proxies to the render method of the default proxy.

    77.4.1.17. L'aide de vue Translate

    Souvent le sites Web sont disponibles en plusieurs langues. Pour traduire le contenu d'un site, vous pouvez simplement utiliser Zend Translate et pour intégrer Zend Translate à l'intérieur de vos vues, vous devriez utiliser l'aide de vue Translate.

    Dans tous les exemples suivants nous allons utiliser l'adaptateur de traduction Array. Bien sûr vous pouvez aussi utiliser toute instance de Zend_Translate ainsi que toutes sous-classes de Zend_Translate_Adapter. Il y a plusieurs manières d'initialiser l'aide de vue Translate :

    • enregistré préalablement dans Zend_Registry

    • après, par l'interface fluide

    • directement en initialisant la classe

    Une instance préalablement enregistré de Zend_Translate est l'utilisation préférée pour cette aide. Vous pouvez ainsi sélectionner la locale à utiliser avant d'ajouter l'adaptateur dans le registre.

    [Note] Note

    Nous parlons de locales et non de langues car une langue peut aussi contenir une région. Par exemple l'anglais est parlé en différents dialectes. Il peut y avoir une traduction pour l'anglais et une pour l'américain. Ainsi, nous disons "locale" plutôt que "langues".

    Exemple 77.46. Instance enregistrée

    Pour utiliser une instance enregistrée, créez une instance de Zend_Translate ou Zend_Translate_Adapter et enregistrez la dans Zend_Registry en utilisant la clé Zend_Translate.

    // notre adaptateur d'exemple
    $adapter = new Zend_Translate(
        array(
            
    'adapter' => 'array',
            
    'content' => array('simple' => 'einfach'),
            
    'locale'  => 'de'
        
    )
    );
    Zend_Registry::set('Zend_Translate'$adapter);

    // à l'intérieur de votre vue
    echo $this->translate('simple');
    // ceci retourne 'einfach'

    Si vous êtes plus familier avec l'interface fluide, alors vous pouvez aussi créer une instance à l'intérieur de votre vue et initialiser l'aide ensuite.

    Exemple 77.47. A l'intérieur de la vue

    Pour utiliser l'interface fluide, créez une instance de Zend_Translate ou Zend_Translate_Adapter, appelez l'aide sans paramètres, et appelez la méthode setTranslator().

    // à l'intérieur de votre vue
    $adapter = new Zend_Translate(
        array(
            
    'adapter' => 'array',
            
    'content' => array('simple' => 'einfach'),
            
    'locale'  => 'de'
        
    )
    );
    $this->translate()->setTranslator($adapter)->translate('simple');
    // ceci retourne 'einfach'

    Si vous utilisez votre aide sans Zend_View, alors vous pouvez aussi l'utiliser directement.

    Exemple 77.48. Utilisation directe

    // notre adaptateur d'exemple
    $adapter = new Zend_Translate(
        array(
            
    'adapter' => 'array',
            
    'content' => array('simple' => 'einfach'),
            
    'locale'  => 'de'
        
    )
    );

    // initialiser l'adaptateur
    $translate = new Zend_View_Helper_Translate($adapter);
    print 
    $translate->translate('simple');
    // ceci retourne 'einfach'

    Vous devriez utiliser cette façon de faire si vous ne travaillez pas avec Zend_View et que vous avez besoin de créer des affichages traduits.


    Comme vu auparavant, la méthode translate() est utilisé pour retourner la traduction. Appelez la simplement avec l'identifiant de message de votre adaptateur de traduction. Mais il peut aussi avoir à remplacer des paramètres dans la chaîne de traduction. Donc, il accepte des paramètres de deux manières : soit comme une liste de paramètres, soit comme un tableau de paramètres. Par exemple :

    Exemple 77.49. Paramètres unique

    Pour utiliser un paramètre unique, ajoutez le en fin de méthode :

    // à l'intérieur de votre vue
    $date "Monday";
    $this->translate("Today is %1\$s"$date);
    // ceci retourne 'Heute ist Monday'

    [Note] Note

    Gardez à l'esprit que si vous utilisez des paramètres qui sont aussi des textes, vous pouvez aussi avoir à traduire ces paramètres.

    Exemple 77.50. Liste de paramètres

    Ou utiliser une liste de paramètres et ajoutez les en fin de méthode :

    // à l'intérieur de votre vue
    $date "Monday";
    $month "April";
    $time "11:20:55";
    $this->translate("Today is %1\$s in %2\$s. Actual time: %3\$s",
                     
    $date,
                     
    $month,
                     
    $time);
    // ceci retourne 'Heute ist Monday in April. Aktuelle Zeit: 11:20:55'

    Exemple 77.51. Tableau de paramètres

    Ou utiliser un tableau de paramètres et ajoutez le en fin de méthode :

    // à l'intérieur de votre vue
    $date = array("Monday""April""11:20:55");
    $this->translate("Today is %1\$s in %2\$s. Actual time: %3\$s"$date);
    // Could return 'Heute ist Monday in April. Aktuelle Zeit: 11:20:55'

    Parfois il est nécessaire de changer la locale pour une traduction. Ceci peut être fait soit dynamiquement par traduction ou statiquement pour toutes les traductions suivantes. Et vous pouvez utiliser ceci avec une liste de paramètres ou un tableau de paramètres. Dans les deux cas la locale doit être fournie comme un paramètre unique final.

    Exemple 77.52. Changement dynamique de la locale

    // à l'intérieur de votre vue
    $date = array("Monday""April""11:20:55");
    $this->translate("Today is %1\$s in %2\$s. Actual time: %3\$s"$date'it');

    Cet exemple retourne la traduction italienne pour l'identifiant de message. Mais la locale ne sera utilisée qu'une seule fois. La traduction suivante utilisera la locale de l'adaptateur. Normalement vous réglerez la locale au niveau de votre adaptateur avant de le mettre dans le registre. Mais vous pouvez aussi paramétrer la locale avec l'aide de vue :

    Exemple 77.53. Changement statique de la locale

    // à l'intérieur de votre vue
    $date = array("Monday""April""11:20:55");
    $this->translate()->setLocale('it');
    $this->translate("Today is %1\$s in %2\$s. Actual time: %3\$s"$date);

    L'exemple ci-dessus paramètre 'it' comme nouvelle locale par défaut, elle sera utilisée pour toutes les traductions ultérieures.

    Bien sûr il existe aussi la méthode getLocale() pour récupérer le réglage courant de la locale.

    Exemple 77.54. Récupération de la locale courante

    // à l'intérieur de votre vue
    $date = array("Monday""April""11:20:55");

    // retourne 'de' comme réglé dans les exemples précédents
    $this->translate()->getLocale();

    $this->translate()->setLocale('it');
    $this->translate("Today is %1\$s in %2\$s. Actual time: %3\$s"$date);

    // retourne 'it' comme nouvelle locale par défaut
    $this->translate()->getLocale();

    77.4.2. Chemin des aides

    Comme pour les scripts de vue, votre contrôleur peut spécifier une pile de chemins dans lesquels Zend_View cherchera les classes d'aides. Par défaut, Zend_View cherche dans "Zend/View/Helper/*". Vous pouvez dire à Zend_View de regarder dans d'autres chemins en utilisant les méthodes setHelperPath() et addHelperPath(). De plus, vous pouvez indiquer un préfixe de classe pour utiliser les aides dans le répertoire fourni, et permettre de donner des espaces de noms à vos classes d'aide. Par défaut, si aucun préfixe n'est fourni, "Zend_View_Helper_" est utilisé.

    $view = new Zend_View();
    $view->setHelperPath('/chemin/vers/plus/de/classes/d-aides',
                         
    'Ma_View_Helper');

    En fait, vous pouvez "empiler" les chemins en utilisant la méthode addHelperPath(). Comme vous ajoutez des chemins dans la pile, Zend_View va regarder dans le chemin le plus récemment ajouté, pour inclure la classe d'aide. Cela vous permet d'ajouter (ou bien de redéfinir) la distribution initiale des aides, avec vos propres aides personnalisées.

    $view = new Zend_View();

    // Ajoute /chemin/vers/des/aides avec le préfixe
    // de classe 'Ma_View_Helper'
    $view->addHelperPath('/chemin/vers/des/aides',
                         
    'Ma_View_Helper');
    // Ajoute /autre/chemin/vers/des/aides avec le préfixe
    // de classe 'Votre_View_Helper'
    $view->addHelperPath('/autre/chemin/vers/des/aides',
                         
    'Votre_View_Helper');

    // maintenant, lorsque vous appelerez $this->helperName(), Zend_View
    // va rechercher en premier /autre/chemin/vers/des/aides/HelperName.php
    // en utilisant la classe "Votre_View_Helper_HelperName", et ensuite
    // dans /chemin/vers/des/aides/HelperName.php en utilisant la classe
    // "Ma_View_Helper_HelperName", et finalement dans
    // Zend/View/Helpers/HelperName.php en utilisant la classe
    // "Zend_View_Helper_HelperName"

    77.4.3. Écrire des aides personnalisées

    Écrire des aides personnalisées est facile, vous devez juste suivre ces règles :

    • Bien qu'il ne soit pas strictement nécessaire, il est recommandé soit d'implémenter Zend_View_Helper_Interface ou d'étendre Zend_View_Helper_Abstract quand vous créez vos aides. Introduit en 1.6.0, ceux-ci définissent la méthode setView() ; cependant, dans les prochaines releases, nous prévoyons d'implémenter un motif de conception Stratégie qui permettra de simplifier en grande partie le schéma de nomination détaillé ci-dessous. Contruire sur ces bases à partir de maintenant vous aidera pour vos codes futurs.

    • Le nom de la classe doit, au minimum, se terminer avec le nom de l'aide en utilisant une notation en casseMélangée. Par exemple, si vous écrivez une aide appelée "actionSpeciale", le nom de la classe doit être au minimum "ActionSpeciale". Vous devriez donner au nom de la classe un préfixe, et il est recommandé d'utiliser "Ma_View_Helper" comme partie de ce préfixe : "Ma_View_Helper_ActionSpeciale". (Vous devez alors fournir le préfixe, avec ou sans le tiret bas, à addHelperPath() ou à setHelperPath()).

    • La classe doit avoir une méthode publique dont le nom correspond au nom de l'aide ; c'est la méthode qui sera appelée quand votre template appellera $this->actionSpeciale(). Dans notre exemple $this->actionSpeciale(), la déclaration de méthode requise serait public function actionSpeciale().

    • En général, la classe ne devrait pas afficher directement les données (via echo ou print). Elle devrait retourner les valeurs pour être ensuite affichées. Les valeurs retournées devrait être échappées de façon appropriées.

    • La classe doit être dans un fichier ayant le même nom que la méthode d'aide. Si on utilise la méthode actionSpeciale(), le fichier devra être nommé "ActionSpeciale.php"

    Placez le fichier de classe d'aide quelque part dans la pile des chemins d'aide, et Zend_View le chargera, l'instanciera, le rendra persistant, et l'exécutera automatiquement pour vous.

    Voici un exemple de fichier "ActionSpeciale.php" :

    class Ma_View_Helper_ActionSpeciale
    {
        protected 
    $_count 0;
        public function 
    actionSpeciale()
        {
            
    $this->_count++;
            
    $output "J'ai vu 'The Big Lebowsky' {$this->_count} fois.";
            return 
    htmlspecialchars($output);
        }
    }

    Ensuite, dans un script de vue, vous pouvez appeler l'aide ActionSpeciale autant de fois que vous le souhaitez ; elle sera instanciée une fois, et rendue persistante pendant toute la vie de l'instance de Zend_View.

    // rappelez vous, $this se réfère à l'instance de Zend_View
    echo $this->actionSpeciale();
    echo 
    $this->actionSpeciale();
    echo 
    $this->actionSpeciale();

    La sortie pourrait alors ressembler à ceci :

    J'ai vu 'The Big Lebowsky' 1 fois.
    J'
    ai vu 'The Big Lebowsky' 2 fois.
    J'ai vu 'The Big Lebowsky' 3 fois.

    Quelquefois vous devez accéder à l'objet Zend_View appelant - par exemple, si vous devez utiliser l'encodage enregistré ou voulez effectuer le rendu d'un autre script de vue comme une sous partie de votre aide. Pour avoir accès à votre objet de vue, votre classe d'aide doit avoir une méthode setView($view), comme ceci :

    class Ma_View_Helper_ScriptPath
    {
        public 
    $view;

        public function 
    setView(Zend_View_Interface $view)
        {
            
    $this->view $view;
        }

        public function 
    scriptPath($script)
        {
            return 
    $this->view->getScriptPath($script);
        }
    }

    Si votre classe d'aide a une méthode setView(), elle sera appelée quand votre classe sera instanciée la première fois et fournira l'objet de la vue courante. Il est de votre responsabilité de maintenir la persistance de l'objet dans votre classe, de même que de déterminer la façon dont il peut être accéder.

    77.4.4. Registering Concrete Helpers

    Sometimes it is convenient to instantiate a view helper, and then register it with the view. As of version 1.10.0, this is now possible using the registerHelper() method, which expects two arguments: the helper object, and the name by which it will be registered.

    $helper = new My_Helper_Foo();
    // ...do some configuration or dependency injection...

    $view->registerHelper($helper'foo');

    If the helper has a setView() method, the view object will call this and inject itself into the helper on registration.

    [Note] Helper name should match a method

    The second argument to registerHelper() is the name of the helper. A corresponding method name should exist in the helper; otherwise, Zend_View will call a non-existent method when invoking the helper, raising a fatal PHP error.

    digg delicious meneame google twitter technorati facebook

    Comments

    Loading...