Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Le moteur d'affichage de pages

gplanchat edited this page · 18 revisions

Le moteur d'affichage de pages

Généralités

Wootook gère l'affichage de ses pages grâce à 3 éléments différents :

  • Les templates sont des parties d'une page HTML, qui une fois assemblées forment une page complète. Ils sont composé de code HTML et de code PHP simple. Aucune fonction, classe ou constante ne doit y être déclarée.
  • Les blocs sont des objets instanciés par le layout, ils sont organisés selon une hiérarchie arborescente, où chaque bloc peut avoir un ou plusieurs blocs fils. Chaque bloc a une tâche d'affichage précise et ne peut être utilisé pour autre chose. Il peut par contre utiliser un bloc fils pour réaliser une tâche pour laquelle il n'est pas conçu.
  • Le layout gère l'organisation des blocs, c'est lui qui instanciera tous les blocs et qui se chargera de lancer la génération de la page.

Le domaine, les packages et les thèmes

Dans la gestion d'affichage, trois notions élémentaires viennent apporter des possibilités de personnalisation. Elles permettent de définir des apparences différentes et de personnaliser Wootook.

Le domaine définit le type d'application que Wootook est en train d'exécuter. Il en existe 3 :

  • frontend qui est le domaine principal, celui sur lequel les joueurs participent au jeu
  • backend qui est le domaine dans lequel l'administrateur accède au panneau d'administration
  • install qui est un domaine à part, dans lequel l'installeur sexécute

Un domaine regroupe un ou plusieurs package, qui lui-même regroupe un ou plusieurs thèmes. Pour faciliter le travail des graphistes et intégrateurs, le thème default doit toujours être défini dans un package, il sert de référence pour les autres thèmes du package. Par exemple, si un fichier de définition de layout ou un template n'est pas défini dans le thème courant (appelons-le theme1), celui de default sera utilisé à sa place s'il existe.

Enfin, le package base est le package de référence. Comme pour le thème default, si un fichier de définition de layout ou un template n'existent ni dans le thème séléctionné, ni dans le thème default du package sélectionné, alors le thème default du package base sera utilisé.

L'ensemble de ces fichiers se situe dans le dossier application/design/.

NB : Il est très fortement déconseillé de modifier le package base, cette tâche est réservée à l'équipe de développement de Wootook. Vous risquez de ne pas pouvoir faire de mises à jour sans perdre vos modifications.

Le layout

Le layout est un objet qui permet de gérer la disposition de chaque bloc dans la page. Il suit les directives des fichiers de configuration situés dans le dossier layouts de chaque thème. Ces fichiers se constituent d'un fichier XML décrivant les dispositions de chacune des pages.

Le fichier XML comprend un ensemble d'éléments nommés <handle>, qui définissent des types de pages à afficher.

Utilisation basique

L'utilisation basique du layout est très simple, elle consiste à indiquer le nom de la page que l'on souhaite afficher et d'afficher le rendu que génère le layout :

    $layout = new Wootook_Core_Layout();
    $layout->load('login');
    echo $layout->render();

L'exemple plus haut affichera la page de login. La structure de la page, dont les en-têtes (meta, link, css, script, ect...), seront placés au bon endroit.

Utilisation dans un environnement MVC

Dans un environnement MVC le contrôleur d'action intègre des méthodes de chargement et de rendu du layout.

class Foo_BarController
    extends Wootook_Core_Mvc_Controller_Action
{
    public function bazAction()
    {
        // Chargement du layout
        $this->loadLayout('login');
        // Rendu du layout
        $this->renderLayout();
    }
}

L'objet de layout peut être accédé avec la méthode getLayout.

L'exemple plus haut affichera la page de login, de la même manière que l'exemple précédent.

Ces deux exemples iront chercher dans le fichier user.xml le handle de layout nommé login, défini tel que :

<handle name="login">
    <update name="1column" />

    <reference name="content">
        <block name="login" type="core/template" template="user/login.phtml" />
    </reference>

    <reference name="head">
        <action method="addCss">
            <param name="stylesheet">css/deprecated/styles.css</param>
        </action>
        <action method="addCss">
            <param name="stylesheet">css/deprecated/about.css</param>
        </action>
    </reference>
</handle>

Voir la page sur les fichiers de layout

Les blocs

Un bloc est une instance d'une classe spécialisée dans la génération rendu (généralement HTML ou texte). Dans certains cas particuliers d'autres tâches sont aussi attribuées à des types de blocs. Certains blocs ne sont pas conçus pour générer eux-même du HTML, mais leur tâche reste exclusivement dédiée au rendu des pages HTML.

Les blocs de rendu HTML

Généralités

Tous les blocs de rendu HTML héritent de la classe Wootook_Core_Block_Template, c'est la classe de base qui permettra d'exécuter des fichiers de template. Cette classe a diverses fonctionnalités d'aide de vue, dont on peut lister :

  • getUrl, cette méthode génère des URL absolues sur le site et 2 paramètres : le fichier à appeler et les paramètres de la requête (tout le contenu situé après le caractère ? dans l'URL)
  • getSkinUrl, comme la précédente cette méthode renvoie une URL, mais pour des fichiers de skin (CSS, Javascript, images, ect...)
  • renderNumber, cette méthode permet de créer un rendu de nombre, elle permet de rendre uniforme l'affichage des nombres très larges (jusqu'à 10e30).
  • renderTime, cette méthode permet d'afficher des dates localisées
  • translate et __, ces méthodes permettent de traduire des textes à afficher. elles utilisent la méthode Gettext et la syntaxe de printf.

Additionnellement, toutes les instances de bloc disposent de la méthode render qui génèrera le rendu HTML.

Accès aux blocs fils

Les blocs disposent des méthodes pour accéder à leurs blocs enfants, dont getPartial, setPartial, hasPartial, unsetPartial et getAllPartials. Il est également possible d'accéder aux blocs fils grâce à l'opérateur -> suivi du nom du bloc fils, par exemple dans un template :

<?php echo $this->header->render() ?>

Ce petit bout de code ira chercher un bloc fils nommé header, puis affichera son rendu. De manière équivalente, il est aussi possible de faire :

<?php echo $this->renderPartial('header') ?>

Le nom d'attribut virtuel est linéarisé, comme pour les types de blocs que l'on a pu voir dans le chapitre sur le layout, les noms de blocs sont linéarisés pour être accédés avec l'opérateur ->. Les caractères - sont supprimés et le caractère qui les suit directement sera mis en majuscule. Un bloc nommé test-child-bloc pourra être accédé en utilisant l'attribut virtuel $this->testChildBlock.

Blocs de base

Si tous les blocs ne peuvent pas être décrits ici, une liste non exhaustive des blocs les plus souvent utilisés peut être faite :

Wootook_Core_Block_Template

Wootook_Core_Block_Template est le bloc de base permettant de générer du HTML d'après un template phtml. Décrit plus haut, il est utilisé lorsqu'aucun bloc dédié n'a encore été créé ou qu'un nouveau bloc n'a pas de vraie utilité.

Wootook_Core_Block_Text

Wootook_Core_Block_Text est un bloc de base qui n'exécute pas de template pthml, mais auquel on envoie un contenu texte brut, qu'il affiche ensuite sans effectuer aucun traitement. Il dispose d'une méthode setContent qui permettra de lui fournir le contenu texte à afficher.

Wootook_Core_Block_Concat

Wootook_Core_Block_Concat est particulier, il n'est pas capable de générer lui-même du contenu, mais il permet de gérer un groupe de blocs à afficher. Lors de la génération de la page, il exécutera la génération du contenu de chacun de ses blocs enfants un à un, puis il concatènera l'ensemble du contenu et le retournera à son tour.

Wootook_Core_Block_Messages

Wootook_Core_Block_Messages est instancié automatiquement par le layout et n'est pas présent dans l'arbre hiérarchique des blocs. Il est accessible dans n'importe quel template et permet d'afficher l'ensemble des messages stockés par la messagerie applicative de session. A chaque affichage de ce bloc, tous les messages qui n'ont pas encore étés affichés le sont. Ce bloc peut être accédé directement avec la méthode getMessagesBlock du layout, ou bien en utilisant une référence sur le nom de bloc messages.

Les sessions étant organisées par espace de noms, la méthode prepareMessages permet d'ajouter un nouvel espace de nom de session à afficher. Par exemple, si dans mon contrôleur, j'ai le code suivant :

$session = Wootook::getSession('galaxy');
$session->addError("La galaxie n'existe pas.');
$session->addSuccess("Votre flotte a bien été expédiée.');

Ce code ajoutera un message d'erreur et un message de succes d'opération à l'espace de nom de session galaxy. Pour afficher les messages de cet espace de noms, il faudra donc placer le code suivant :

$layout = new Wootook_Core_Layout();
$layout->load('galaxy.view');
$layout->getMessagesBlock()->prepareMessages('galaxy');
echo $layout->render();
Wootook_Core_Block_Html_Navigation

Wootook_Core_Block_Html_Navigation est un bloc qui permet la gestion dynamique d'un menu de navigation. Il dispose de 6 méthodes particulières :

  • addLink, qui prend 8 paramètres, dont 4 optionnels
    • name définit un chemin dans l'arborescence du menu. Un caractère / sépare chaque élément de l'arborescence. Pour chaque élément, un bloc est créé. Les blocs de plus haut niveau sont de type Wootook_Core_Block_Html_Navigation_Link, tous les autres sont de type Wootook_Core_Block_Html_Navigation_Node, des noeuds de l'arborescence qui permettent de regrouper des liens et d'autres noeuds.
    • label sera le texte du lien affiché.
    • title sera le texte placé dans la balise title.
    • uri sera l'URL relative sur le site.
    • params (optionnel), de type tableau contient les paramètres de requête supplémentaires à ajouter à l'URL (voir Wootook::getUrl().
    • classes permet d'ajouter des classes CSS supplémentaires au lien.
    • template permet de spécifier un template particulier pour le lien (par défaut page/html/navigation/link.phtml).
    • attributes permet d'ajouter des attributs HTML supplémentaires au lien.
  • addExternalLink, qui prend 7 paramètres, dont 3 optionnels, il permet comme addLink d'ajouter un lien dans le menu, mais en ajoutant cette fois un lien absolu (externe).
    • name voir addLink.
    • label voir addLink.
    • title voir addLink.
    • url sera l'URL absolue du lien.
    • classes permet d'ajouter des classes CSS supplémentaires au lien.
    • template voir addLink.
    • attributes voir addLink.
  • addPopupLink, qui prend 8 paramètres, dont 4 optionnels, il permet comme addLink d'ajouter un lien dans le menu, mais il sera ouvert dans une popup. Les paramètres sont les mêmes que addLink.
  • setNodeTitle permet de définir le texte à afficher sur un noeud (groupe de liens). Cette méthode prend un paramètre name qui contient le chemin vers le noeud à rechercher et un paramètre title qui contient le titre à assigner au bloc.
  • setNodeTemplate permet de définir le template à utiliser pour un noeud (groupe de liens). Cette méthode prend un paramètre name qui contient le chemin vers le noeud à rechercher et un paramètre template qui contient le chemin vers le ficheir de template à assigner au bloc.
  • getNode retourne une instance de bloc dans le menu. Si elle n'existe pas, une instance de type Wootook_Core_Block_Html_Navigation_Node est créée et retournée. Cette méthode prend un paramètre name qui contient le chemin vers le noeud à rechercher.

Les templates

Les templates sont des fichiers .phtml situés dans l'arborescence du design (application/design/package/theme/templates/).

Par convention, leur contenu doit se composer de balises HTML complètes : une balise ouvrante doit avoir sa balise fermante. Ces fichiers peuvent également contenir des éléments PHP : des appels de méthodes de l'instance de bloc courante (disponible dans l'objet $this), des structures de contrôle utilisant la syntaxe alternative et l'instruction echo.

Chaque instruction PHP doit être entourée des tags d'ouverture et de fermeture longs, les tags courts, script et les tags ASP sont depuis PHP 5.0 (2004) très souvent désactivés et donc peu portables. Le caractère ; ne devrait pas être présent dans les tags PHP.

Par exemple, le template affichant la liste des ressource en haut de page de Legacies contient le code suivant :

<div class="resource deuterium">
  <img src="<?php echo $this->getSkinUrl('graphics/images/deuterium.gif')?>" border="0" height="22" width="42" alt="<?php echo $this->__('Deuterium')?>" title="<?php echo $this->__('Deuterium')?>" />
  <p>
  <?php if ($this->getCurrentPlanet()->isResourceCapped(Legacies_Empire::RESOURCE_DEUTERIUM)):?>
    <span class="resource-capped"><?php echo $this->renderNumber($this->getCurrentPlanet()->getResourceAmount(Legacies_Empire::RESOURCE_DEUTERIUM))?></span>
  <?php else:?>
    <?php echo $this->renderNumber($this->getCurrentPlanet()->getResourceAmount(Legacies_Empire::RESOURCE_DEUTERIUM))?>
  <?php endif?>
  </p>
</div>

On voit donc que tout accès aux données des modèles doit se faire grâce aux méthodes de l'instance du bloc courant. Tout autre moyen d'accéder aux données cassera la règle de séparation des données et du contenu, ce qui impliquera de nouvelles contraintes de maintenance.

Something went wrong with that request. Please try again.