This document is for a version of CakePHP that is no longer supported. Please upgrade to a newer release!

Page Contents

Vues

Vues

Les « Vues » sont le V dans MVC. Les vues sont chargées de générer la sortie spécifique requise par la requête. Souvent, cela est fait sous forme HTML, XML ou JSON, mais le streaming de fichiers et la création de PDFs que les utilisateurs peuvent télécharger sont aussi de la responsabilité de la couche Vues.

Templates de Vue

La couche vue de CakePHP c’est la façon dont vous parlez à vos utilisateurs. La plupart du temps, vos vues afficheront des documents (X)HTML pour les navigateurs, mais vous pourriez aussi avoir besoin de fournir des données AMF à un objet Flash, répondre à une application distante via SOAP ou produire un fichier CSV pour un utilisateur.

Les fichiers de vues de CakePHP sont écrits en pur PHP et ont comme extension par défaut .ctp (Cakephp TemPlate). Ces fichiers contiennent toute la logique de présentation nécessaire à l’organisation des données reçues du contrôleur, dans un format qui satisfasse l’audience que vous recherchez.

Les fichiers de vues sont stockées dans /app/views/, dans un dossier portant le nom du contrôleur qui utilise ces fichiers et le nom de la vue correspondante. Par exemple, l’action voir() du contrôleur Produits devrait normalement se trouver dans /app/views/produits/voir.ctp

La couche vue de CakePHP peut être constituée d’un certain nombre de parties différentes. Chaque partie a différent usages qui seront présentés dans ce chapitre :

  • layouts : fichiers de vue contenant le code de présentation qui se retrouve dans plusieurs interfaces de votre application. La plupart des vues sont rendues à l’intérieur d’un layout.

  • elements : morceaux de code de vue plus petits, réutilisables. Les éléments sont habituellement rendus dans les vues.

  • helpers : ces classes encapsulent la logique de vue qui est requise à de nombreux endroits de la couche vue. Parmi d’autres choses, les helpers (assistants) de CakePHP peuvent vous aider à créer des formulaires, des fonctionnalités AJAX, de paginer les données du modèle ou à délivrer des flux RSS.

Gabarits (layouts)

Un layout (gabarit) contient le code de présentation qui enveloppe une vue. Tout ce que vous voulez voir dans toutes vos vues devrait être placé dans un layout.

Les fichiers de gabarits devraient être placés dans /app/views/layouts. Le gabarit par défaut de CakePHP peut être surchargé, en créant un nouveau layout par défaut dans /app/views/layouts/default.ctp. Une fois qu’un nouveau layout par défaut a été créé, le code de rendu de vue du contrôleur est placé à l’intérieur de celui-ci lorsque la page est affichée.

Lorsque vous créez un gabarit, vous devez dire à CakePHP où placer le code de vos vues. Pour ce faire, assurez-vous que votre gabarit contient la variable $content_for_layout (et optionnellement, $title_for_layout). Voici un exemple de ce à quoi pourrait ressembler un layout par défaut :

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title><?php echo $title_for_layout?></title>
<link rel="shortcut icon" href="favicon.ico" type="image/x-icon">
<!-- Inclure les fichiers et scripts externes ici (Voir le HTML Helper pour plus d'informations) -->
<?php echo $scripts_for_layout ?>
</head>
<body><!-- Si vous aimeriez qu'une sorte de menu se voit sur toutes vos vues, incluez-le ici -->
<div id="header">
    <div id="menu">...</div>
</div>
<!-- Voici où je veux que mes vues soient affichées -->
<?php echo $content_for_layout ?>

<!-- On ajoute un pied de page à chaque page affichée -->
<div id="footer">...</div>
</body>
</html>

$scripts_for_layout contient tout fichier externe et script inclus avec le Helper HTML livré avec Cake. Ceci est utile pour inclure des fichiers javascript et CSS depuis les vues.

Lorsque vous utilisez $html->css() ou $javascript->link() dans les fichiers de vues, spécifiez “false” pour l’argument “in-line” afin de placer le code source HTML dans $scripts_for_layout. (Voir l’API pour plus de détails sur l’usage).

$content_for_layout contient la vue. C’est ici que le code de la vue sera placé.

$title_for_layout contient le titre de la page.

Pour définir le titre du gabarit, c’est encore plus simple de le faire depuis le contrôleur, en définissant la variable $title_for_layout.

<?php

class UtilisateursController extends AppController {
    function voirActifs() {
        $this->set('title_for_layout', 'Voir les utilisateurs actifs');
    }
}
?>

Vous pouvez créer autant de gabarits que vous le souhaitez : placez-les simplement dans le dossier app/views/layouts, et basculez de l’un à l’autre à l’intérieur des actions de vos contrôleurs, en utilisant la variable $layout du contrôleur ou la fonction setLayout().

Par exemple, si une section de mon site incluait un plus petit espace pour les bannières publicitaires, je pourrais créer un nouveau gabarit avec l’espace publicitaire plus petit et le spécifier comme layout pour toutes les actions des contrôleurs en utilisant quelque chose comme :

var $layout = “petite_pub_defaut”;

<?php

class UtilisateursController extends AppController {
    function voirActifs() {
        $this->set('title_for_layout', 'Voir les utilisateurs actifs');
        $this->layout = 'petite_pub_defaut'
    }

    function voirImage() {
        $this->layout = 'image';
        // affiche l'image de l'utilisateur
    }
}
?>

CakePHP présente deux gabarits du cœur (en plus du layout par défaut) que vous pouvez utiliser dans vos propres applications : “ajax” et “flash”. Le gabarit Ajax est pratique pour façonner les réponses Ajax - c’est un layout vide (la plupart des appels ajax nécessitent seulement un peu de balisage en retour, plutôt qu’une interface entièrement rendue). Le gabarit Flash est utilisé pour l’affichage des messages affichés par la méthode flash() des contrôleurs.

Trois autres gabarits : xml, js et rss - existent dans le cœur afin de générer de manière simple et rapide du contenu qui n’est pas du text/html.

Eléments

De nombreuses applications disposent de petits blocs de présentation qui doivent se répéter de page en page, parfois à des endroits différent du layout. CakePHP peut vous aider à répéter ces parties de votre site web qui ont besoin d’être réutilisées. Ces parties sont appelées Eléments. Avertissements, boîtes d’aide, contrôles de navigation, extra menus, formulaires de login et infos-bulles sont souvent implémentés comme des éléments dans CakePHP. Un élément est simplement une mini-vue qui peut être incluse dans d’autres vues, dans des layouts et même dans d’autres éléments. Les Eléments peuvent être utilisés pour rendre une vue plus lisible, en plaçant les éléments répétitifs dans leur propre fichier. Ils peuvent aussi vous aider à réutiliser des fragments de contenu dans votre application.

Les éléments sont dans le dossier /app/views/elements/ et ont l’extension de fichier .ctp. Ils sont affichés en utilisant la méthode element de la vue.

<?php echo $this->element('boite_dialogue'); ?>

Transmettre des variables à un élément

Vous pouvez faire passer des données à un élément via le second argument :

<?php echo
$this->element('aide',
    array("texteaide" => "Oh, ce texte est vraiment utile."));
?>

Dans le fichier correspondant à l’élément, toutes les variables passées sont accessibles dans le tableau parameter (de la même manière que, dans le contrôleur, set() envoie les variables aux vues). Dans l’exemple ci-dessus, vous pouvez utiliser la variable $texteaide dans le fichier /app/views/elements/aide.ctp.

<?php
echo $texteaide; //affichera "Oh, ce texte est vraiment utile."
?>

Dans la fonction element() sont regroupées les options de l’élément avec les données à transmettre. Les deux options sont “cache” et “plugin”. Par exemple :

<?php echo
$this->element('aide',
    array(
        "texteaide" => "Transmis à l'élément dans la variable $texteaide",
        "toto" => "Transmis à l'élément dans la variable $toto",
        "cache" => "+2 days", // mettra l'élément en cache pour 2 jours.
        "plugin" => "" // pour fournir une partie d'un plugin
    )
);
?>

Pour mettre en cache plusieurs versions du même élément dans l’application, vous pouvez attribuer une clé unique de cache de la manière suivante :

<?php
$this->element('aide',
    array(
        "cache" => array('time'=> "+7 days",
                         'key'=>'valeur unique')
    )
);
?>

Vous pouvez profiter pleinement des élements en utilisant requestAction(). Cette fonction retourne dans un tableau les variables de vue à partir d’une action d’un contrôleur. Cela permet à vos éléments de fonctionner en respectant la logique MVC. Créez une action dans un contrôleur qui prépare les variables de vue pour votre élément, et appelez requestAction() dans le second paramètre de votre fonction element() pour directement passer à l’élément les variables issues du contrôleur.

Pour cela, ajoutez dans votre contrôleur un code similaire au suivant :

<?php
class MessagesController extends AppController {
    ...
    function index() {
        $messages = $this->paginate();
        if (isset($this->params['requested'])) {
            return $messages;
        } else {
            $this->set('messages',$messages);
        }
    }
}
?>

Puis, dans la vue, nous pouvons accéder aux messages triés par pages. Pour avoir les cinq derniers messages triés, nous pouvons faire quelque chose de ce style :

<h2>Derniers messages</h2>
<?php $messages= $this->requestAction('messages/index/sort:created/direction:asc/limit:5'); ?>
<?php foreach($messages as $message): ?>
<ol>
    <li><?php echo $message['Message']['titre']; ?></li>
</ol>
<?php endforeach; ?>

Mettre en cache les Éléments

Vous pouvez tirer avantage du cache de vue CakePHP si vous fournissez un paramètre de cache. S’il est défini à true, la mise en cache sera d’un jour. Sinon, vous pouvez définir d’autres délais d’expiration du cache. Voir Mettre en cache pour plus d’information sur les réglages d’expiration.

<?php echo $this->element('boite_dialogue', array('cache' => true)); ?>

Si vous utilisez le même élément plus d’une fois dans une vue et que vous avez activé la mise en cache, assurez-vous de définir le paramètre “key” avec un nom différent chaque fois. Cela empêchera chaque appel successif d’écraser le résultat mis en cache lors du précédent appel à element(). Par exemple :

<?php
echo $this->element('boite_dialogue', array('cache' => array('key' => 'premier_usage', 'time' => '+1 day'), 'var' => $variable));

echo $this->element('boite_dialogue', array('cache' => array('key' => 'second_usage', 'time' => '+1 day'), 'var' => $variableDifferente));
?>

De cette façon, on s’assure que chacun des éléments possède sa propre mise en cache, séparée de l’autre.

Appeler des Eléments depuis un Plugin

Si vous utilisez un plugin et que vous souhaitez utiliser des éléments avec lui, spécifiez simplement le paramètre plugin. Si la vue doit être rendue pour une action de contrôleur de plugin, elle pointera automatiquement vers l’élément destiné au plugin. Si l’élément n’existe pas dans le plugin, elle regardera dans le dossier APP prinicpal.

<?php echo $this->element('boite_dialogue', array('plugin' => 'nom_plugin')); ?>

Méthodes de Vue

Les méthodes de Vue sont accessibles dans tous les fichiers vue, élément et layout. Pour appeler toute méthode de vue utiliser $this->methode()

set()

set(string $var, mixed $value)

Les vues ont une méthode set() analogue au set() trouvé dans les objects Contrôleur. Elle vous permet d’ajouter des variables à viewVars. Utiliser set() depuis votre fichier de vue ajoutera les variables au layout et aux éléments qui seront rendus ultérieurement. Voyez Controller::set() pour plus d’information sur l’utilisation de set().

Dans votre fichier de vue vous pouvez faire

$this->set('activeMenuBouton', 'posts');

Ensuite dans votre layout la variable $activeMenuBouton sera disponible et contiendra la valeur “posts”.

getVar()

getVar(string $var)

Retourne la valeur de viewVar dont le nom est $var

getVars()

getVars()

Retourne une liste de toutes les variables de vue disponibles dans le champ de rendu courant. Retourne un tableau des noms de variable.

error()

error(int $code, string $name, string $message)

Affiche une page d’erreur à l’utilisateur. Utilise layouts/error.ctp pour rendre la page.

$this->error(404, 'Non trouvée', 'Cette page n\'a pas été trouvée, désolé');

Ceci rendra une page d’erreur avec le titre et le message spécifiés. Il est important de noter que l’exécution du script n’est pas arrêtée par View::error(). Donc vous devrez stopper l’exécution du code vous même, si vous voulez interrompre le script.

element()

element(string $elementPath, array $data, bool $loadHelpers)

Rends un élément ou une vue partielle. Voyez la section sur View Elements pour plus d’informations et d’exemples.

uuid

uuid(string $object, mixed $url)

Génère un ID DOM unique non-aléatoire pour un objet, basé sur le type d’objet et l’url. Cette méthode est souvent utilisée par les assistants, tels que AjaxHelper, qui ont besoin de générer des ID DOM uniques pour les éléments.

$uuid = $this->uuid('form', array('controller' => 'posts', 'action' => 'index'));
//$uuid contient 'form0425fe3bad'

addScript()

addScript(string $name, string $content)

Ajoute du contenu au tampon (buffer) de scripts interne. Ce buffer est rendu disponible dans le layout par $scripts_for_layout. Cette méthode est pratique pour la création d’assistants qui nécessitent d’ajouter du javascript ou des css directement dans le layout. Gardez à l’esprit que les scripts ajoutés depuis le layout ou depuis les éléments dans le layout ne seront pas ajoutés à $scripts_for_layout. Cette méthode est plus souvent utilisée à l’intérieur des assistants, comme dans les Helpers Javascript et Html.

Thèmes

Vous pouvez tirer avantage des thèmes pour rendre le changement de look et de design de vos pages plus rapide et plus aisé.

Pour utiliser les thèmes, vous devez spécifier à votre contrôleur d’utiliser la classe ThemeView plutôt que la classe par défaut View.

class ExemplesController extends AppController {
    var $view = 'Theme';
}

Pour déclarer quel thème utiliser par défaut, spécifiez le nom de ce thème dans votre contrôleur :

class ExemplesController extends AppController {
    var $view = 'Theme';
    var $theme = 'exemple_theme';
}

Vous pouvez également choisir ou changer le thème dans une action, ou dans les fonctions de rappel beforeFilter ou beforeRender.

$this->theme = 'autre_exemple_theme';

Les vues de votre thème doivent être situées dans le dossier /app/views/themed/. Dans ce dossier, créez un nouveau dossier du même nom que votre thème, par exemple /app/views/themed/exemple_theme/. Ensuite, sa structure sera exactement la même que celle de /app/views/.

Par exemple, la vue de votre fonction editer() d’un contrôleur Messages se situerait à /app/views/themed/exemple_theme/messages/editer.ctp. Les fichiers de mise en page (Layout) seraient quant à eux dans le dossier /app/views/themed/exemple_theme/layouts/.

Si CakePHP ne peut trouver la vue dans le dossier du thème, il la cherchera dans le dossier /app/views/. De cette manière, vous pouvez créer des vues générales, et simplement les adapter à votre thème, au cas-par-cas, dans le dossier adapté.

Si vous avez des fichiers CSS ou JavaScript qui sont spécifiques à votre thème, vous pouvez les stocker dans un dossier de thème à l’intérieur de webroot. Vos feuilles de style seront par exemple situées dans /app/webroot/themed/exemple_theme/css/, et vos fichiers JavaScript seront dans /app/webroot/themed/exemple_theme/js/.

Tous les Helpers natifs de CakePHP savent gérer les thèmes, et créeront les bons chemins d’accès de façon automatique. De même qu’avec les vues, si un fichier n’est pas dans le dossier du thème, l’utilisateur sera renvoyé par défaut à la racine.

Increasing performance of plugin and theme assets

Its a well known fact that serving assets through PHP is guaranteed to be slower than serving those assets without invoking PHP. And while the core team has taken steps to make plugin and theme asset serving as fast as possible, there may be situations where more performance is required. In these situations its recommended that you either symlink or copy out plugin/theme assets to directories in app/webroot with paths matching those used by cakephp.

  • app/plugins/debug_kit/webroot/js/my_file.js becomes app/webroot/debug_kit/js/my_file.js

  • app/views/themed/navy/webroot/css/navy.css becomes app/webroot/theme/navy/css/navy.css

Vues Media

Les vues de media vous permettent d’envoyer des fichiers binaires à l’utilisateur. Par exemple, vous pouvez souhaiter avoir un dossier de fichiers extérieur à votre webroot afin d’empêcher les utilisateurs d’avoir un lien direct vers eux. Vous pouvez utiliser la vue de Media pour récupérer le fichier depuis un dossier spécial de /app/, ce qui vous permet d’effectuer une authentification avant de délivrer le fichier à l’utilisateur.

Pour utiliser la vue Media, vous devez dire à vôtre contrôleur d’utiliser la classe MediaView au lieu de la classe par défaut View. Après ça, passez simplement des paramètres additionnels pour spécifier l’emplacement de votre fichier.

class ExempleController extends AppController {
    function telecharger () {
        $this->view = 'Media';
        $params = array(
              'id' => 'exemple.zip',
              'name' => 'exemple',
              'download' => true,
              'extension' => 'zip',
              'path' => 'fichiers' . DS
       );
       $this->set($params);
    }
}

Voici un exemple de rendu d’un fichier dont le type mime n’est pas inclut dans le tableau $mimeType de MediaView.

function telecharger () {
    $this->view = 'Media';
    $params = array(
        'id' => 'exemple.docx',
        'name' => 'exemple',
        'extension' => 'docx',
        'mimeType' => array('docx' => 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'),
        'path' => APP . 'fichiers' . DS
    );
    $this->set($params);
}

Paramètres

Description

id

L’ID est le nom du fichier tel qu’il est sur le serveur de fichiers, extension incluse.

name

Le nom vous permet de spécifier un nom de fichier alternatif qui sera envoyé à l’utilisateur. Spécifiez le nom sans l’extension du fichier.

download

Une valeur booléenne indiquant si les en-têtes doivent être définis pour forcer le téléchargement. Notez que l’option autoRender de votre contrôleur doit être définie à false pour que ceci fonctionne correctement.

extension

L’extension du fichier. Ceci est comparé avec une liste interne de types mime acceptables. Si le type mime spécifié n’est pas dans la liste, le fichier ne sera pas téléchargé.

path

Le nom du dossier, incluant le séparateur de dossiers final. Le chemin devrait être absolu, mais il peut être relatif au dossier APP/webroot.

mimeType

Un tableau avec des types mime additionnels qui seront fusionnés avec la liste interne des types mime acceptables présent dans la classe MediaView.

cache

Une valeur booléenne ou entière - Si définie à true, autorise les navigateurs à mettre le fichier en cache (si non définie, défaut à false) ; autrement, définissez-la à un nombre de secondes à partir duquel le cache doit expirer.