Vous pouvez profiter des thèmes, ce qui facilite le changement du visuel et du ressenti de votre page rapide- ment et facilement.
Pour utiliser les thèmes, spécifiez le nom du thème dans votre controller :
class ExempleController extends AppController {
public $theme = ’Exemple’; }
.. versionchanged:: 2.1
Les versions ant é rieures à 2.1 ont besoin de d é finir ‘‘$this->viewClass = ’Theme’‘‘.
2.1 enl è ve cette condition puisque la classe normale ‘‘View‘‘ supporte les th è mes.
Vous pouvez également définir ou modifier le nom du thème dans une action ou dans les fonctions de callback beforeFilter ou beforeRender :
$this->theme = ’AutreExemple’;
Les fichiers de vue du thème ont besoin d’être dans le dossier /app/View/Themed/. Dans le dossier du thème, créez un dossier utilisant le même nom que le nom de votre thème. Par exemple, Le thème ci- dessus serait trouvé dans /app/View/Themed/AutreExemple. Il est important de se souvenir que CakePHP attend des noms de thème en CamelCase. Au-delà de ça, la structure de dossier dans le dossier
/app/View/Themed/Exemple/est exactement le même que /app/View/.
Par exemple, le fichier de vue pour une action edit d’un contôleur Posts residera dans /app/View/Themed/Exemple/Posts/edit.ctp. Les fichiers de Layout résideront dans /app/View/Themed/Exemple/Layouts/.
Si un fichier de vue ne peut pas être trouvé dans le thème, CakePHP va essayer de localiser le fichier de vue dans le dossier /app/View/. De cette façon, vous pouvez créer des fichiers de vue master et simplement les remplacer au cas par cas au sein de votre dossier de thème.
Assets du thème
Les thèmes peuvent contenir des assets statiques ainsi que des fichiers de vue. Un thème peut inclure tout asset nécessaire dans son répertoire webroot. Cela permet un packaging facile et une distribution des thèmes. Pendant le développement, les requêtes pour les assets du thème seront gérés par Dispatcher. Pour améliorer la performance des environnements de production, il est recommandé, soit que vous fassiez un lien symbolique, soit que vous copiez les assets du thème dans le webroot de application. Voir ci-dessous pour plus d’informations.
Pour utiliser le nouveau thème, créez des répertoires de type
app/View/Themed/<nomDuTheme>/webroot<chemin_vers_fichier>dans votre thème. Le
Dispatcher se chargera de trouver les assets du thème corrects dans vos chemins de vue.
Tous les helpers integrés dans CakePHP ont intégrés l’existence des thèmes et vont créer des chemins d’accès corrects automatiquement. Comme pour les fichiers de vue, si un fichier n’est pas dans le dossier du thème, il sera par défaut dans le dossier principal webroot
//Quand dans un thème avec un nom de ’purple_cupcake’
$this->Html->css(’main.css’); //crée un chemin comme
/theme/purple_cupcake/css/main.css //et fait un lien vers
app/View/Themed/PurpleCupcake/webroot/css/main.css
Augmenter la performance des assets du plug-in et du thème
C’est un fait bien connu que de servir les assets par le biais de PHP est assuré d’être plus lent que de servir ces assets sans invoquer PHP. Et tandis que l’équipe du coeur a pris des mesures pour rendre le plugin et l’asset du thème servis aussi vite que possible, il peut y avoir des situations où plus de performance est requis. Dans ces situations, il est recommandé soit que vous fassiez un lien symbolique soit que vous
CakePHP Cookbook Documentation, Version 2.x
fassiez une copie sur les assets du plug-in/thème à des répertoires dans app/webroot avec des chemins correspondant à ceux utilisés par cakephp.
– app/Plugin/DebugKit/webroot/js/my_file.js devient app/webroot/DebugKit/js/my_file.js. – app/View/Themed/Navy/webroot/css/navy.css devient app/webroot/theme/Navy/css/navy.css.
Vues Media class MediaView
Obsolète depuis la version 2.3 : Utilisez Envoyer des pièces jointesà la place. Les vues Media vous per-
mettent d’envoyer des fichiers binaires à l’utilisateur. Par exemple, vous souhaiteriez avoir un répertoire de fichiers en dehors de webroot pour empêcher les utilisateurs de faire un lien direct sur eux. Vous pouvez utiliser la vue Media pour tirer le fichier à partir d’un fichier spécial dans /app/, vous permettant d’améliorer l’authentification avant la livraison du fichier à l’utilisateur.
Pour utiliser la vue Media, vous avez besoin de dire à votre controller d’utiliser la classe MediaView au lieu de la classe View par défaut. Après ça, passez juste les paramètres en plus pour spécifier où votre fichier se trouve :
class ExempleController extends AppController {
public function download() {
$this->viewClass = ’Media’;
// Download app/outside_webroot_dir/example.zip $params = array( ’id’ => ’example.zip’, ’name’ => ’example’, ’download’ => true, ’extension’ => ’zip’,
’path’ => APP . ’outside_webroot_dir’ . DS );
$this->set($params); }
}
Ici vous trouvez un exemple de rendu d’un fichier qui a un type mime qui n’est pas inclu dans le tableau
$mimeTypede MediaView. Nous utilisons aussi un chemin relatif qui va être par défaut dans votre dossier
app/webroot:
public function download() {
$this->viewClass = ’Media’;
// Render app/webroot/files/example.docx $params = array( ’id’ => ’example.docx’, ’name’ => ’example’, ’extension’ => ’docx’, ’mimeType’ => array( ’docx’ => ’application/vnd.openxmlformats-officedocument.wordprocessingml.document’ ), ’path’ => ’files’ . DS );
$this->set($params); }
Paramètres configurables
id L’ID est le nom du fichier tel qu’il réside sur le serveur de fichiers, y compris l’extension de fichier.
name Le nom vous permet de spécifier un nom de fichier alternatif à envoyer à l’utilisateur. Spécifiez le
nom sans l’extension du fichier.
download Une valeur boléenne indiquant si les en-têtes doivent être définis pour forcer le téléchargement. extension L’extension du fichier. Ceci est en correspondance avec une liste interne de types mime ac- ceptables. Si le type MIME spécifié n’est pas dans la liste (ou envoyé dans le tableau de paramètres mimeType), le fichier ne sera pas téléchargé.
path Le nom du dossier, y compris le séparateur de répertoire finale. Le chemin doit être absolu, mais peut
être par rapport au dossier app/webroot.
mimeType Un tableau avec des types MIME supplémentaires à fusionner avec une liste interne dans Me- diaView de types mime acceptables.
cache Une valeur booléenne ou entière - Si la valeur est vraie, elle permettra aux navigateurs de mettre en cache le fichier (par défaut à false si non définie), sinon réglez le sur le nombre de secondes dans le futur pour lorsque le cache expirera.
Vues JSON et XML
Deux nouvelles classes de vue dans CakePHP 2.1. Les vues XmlView et JsonView vous laissent créer
facilement des réponses XML et JSON, et sont intégrées avecRequestHandlerComponent.
En activant RequestHandlerComponent dans votre application, et en activant le support pour les ex- tensions xml et/ou json, vous pouvez automatiquement vous appuyer sur les nouvelles classes de vue.
XmlViewet JsonView feront référence aux vues de données pour le reste de cette page.
Il y a deux façons de générer des vues de données. La première est en utilisant la clé _serialize, et la seconde en créant des fichiers de vue normaux.
Activation des vues de données dans votre application
Avant que vous puissiez utiliser les classes de vue de données, vous aurez besoin de faire un peu de config- uration :
1. Activez les extensions json et/ou xml avecRouter::parseExtensions(). Cela activera Router
pour gérer les multiples extensions.
2. Ajoutez leRequestHandlerComponent à la liste de components de votre controller. Cela ac-
tivera automatiquement le changement de la classe de vue pour les types de contenu.
Introduit dans la version 2.3 : La méthodeRequestHandlerComponent::viewClassMap()a été
ajoutée pour lier les types aux viewClasses. La configuration de viewClassMap ne va pas fonctionner avec les versions précédentes. Après avoir ajouté Router::parseExtensions(’json’); à votre fichier de routes, CakePHP changera automatiquement les classes de vue quand une requête sera faite avec l’extension .json, ou quand l’en-tête Accept sera application/json.
CakePHP Cookbook Documentation, Version 2.x
Utilisation des vues de données avec la clé _serialize
La clé _serialize est une variable de vue spéciale qui indique quel autre(s) variable(s) de vue devraient être sérialisée(s) quan on utilise la vue de données. Cela vous permet de sauter la définition des fichiers de vue pour vos actions de controller si vous n’avez pas besoin de faire un formatage avant que vos données soient converties en json/xml.
Si vous avez besoin de faire n’importe quel formatage ou manipulation de vos variables de vue avant la génération de la réponse, vous devriez utiliser les fichiers de vue. La valeur de _serialize peut être soit une chaîne de caractère, soit un tableau de variables de vue pour sérialiser :
class PostsController extends AppController {
public function index() {
$this->set(’posts’, $this->paginate());
$this->set(’_serialize’, array(’posts’)); }
}
Vous pouvez aussi définir _serialize en tableau de variables de vue pour combiner :
class PostsController extends AppController {
public function index() {
// some code that created $posts and $comments
$this->set(compact(’posts’, ’comments’));
$this->set(’_serialize’, array(’posts’, ’comments’)); }
}
Définir _serialize en tableau a le bénéfice ajouté d’ajouter automatiquement un elément de top-niveau
<response>en utilisantXmlView. Si vous utilisez une valeur de chaîne de caractère pour _serialize
et XmlView, assurez vous que vos variables de vue aient un elément unique de top-niveau. Sans un elément de top-niveau, le Xml ne pourra être généré.
Utilisation d’une vue de données avec les fichiers de vue
Vous devriez utiliser les fichiers de vue si vous avez besoin de faire des manipulations du contenu de votre vue avant de créer la sortie finale. Par exemple, si vous avez des posts, qui ont un champ contenant du HTML généré, nous voudrons probablement omettre ceci à partir d’une réponse JSON. C’est une situation où un fichier de vue serait utile :
// Code du controller
class PostsController extends AppController {
public function index() {
$this->set(compact(’posts’, ’comments’)); }
}
// Code de la vue - app/View/Posts/json/index.ctp
foreach ($posts as &$post) {
unset($post[’Post’][’generated_html’]);
}
echo json_encode(compact(’posts’, ’comments’));
Vous pouvez faire des manipulations encore beaucoup plus complexes, ou utiliser les helpers pour formater aussi.
Note : Les classes de vue de données ne supportent pas les layouts. Elles supposent que le fichier de vue va afficher le contenu sérialisé.
class XmlView
Une classe de vue pour la génération de vue de données Xml. Voir au-dessus pour savoir comment vous pouvez utiliser XmlView dans votre application
Par défaut quand on utilise _serialize, XmlView va enrouler vos variables de vue sérialisées avec un noeud <response>. Vous pouvez définir un nom personnalisé pour ce noeud en utilisant la variable de vue _rootNode. Introduit dans la version 2.3 : La fonctionnalité _rootNode a été ajoutée.
class JsonView
Une classe de vue pour la génération de vue de données Json. Voir au-dessus pour savoir comment vous pouvez utiliser XmlView dans votre application.
JSONP response
Introduit dans la version 2.4. Quand vous utilisez JsonView, vous pouvez utiliser la variable de vue spéciale
_jsonppour permettre de retourner une réponse JSONP. La définir à true fait que la classe de vue vérifie
si le paramètre de chaine de la requête nommé “callback” est défini et si c’est la cas, d’enrouler la réponse json dans le nom de la fonction fournie. Si vous voulez utiliser un nom personnalisé de paramètre de requête à la place de “callback”, définissez _jsonp avec le nom requis à la place de true.
Helpers (Assistants)
Les Helpers (Assistants) sont des classes comme les components, pour la couche de présentation de votre application. Ils contiennent la logique de présentation qui est partagée entre plusieurs vues, éléments ou layouts. Ce chapitre vous montrera comment créer vos propres helpers et soulignera les tâches basiques que les helpers du cœur de CakePHP peuvent vous aider à accomplir.
CakePHP dispose d’un nombre de helpers qui aident à la création des vues. Ils aident à la création de balises bien-formées (y compris les formulaires), aident à la mise en forme du texte, les durées et les numéros, et peuvent même accélérer la fonctionnalité Ajax. Pour plus d’informations sur les helpers inclus dans
CakePHP, allez voirHelpers (Assistants).
Utiliser et configurer les Helpers
Vous activez les helpers (assistants) dans CakePHP, en faisant “prendre conscience” à un controller qu’ils
existent. Chaque controller a une propriété$helpers, qui liste les helpers disponibles dans la vue. Pour
activer un helper dans votre vue, ajoutez son nom au tableau $helpers du controller :
CakePHP Cookbook Documentation, Version 2.x
class BakeriesController extends AppController {
public $helpers = array(’Form’, ’Html’, ’Js’, ’Time’); }
L’ajout des helpers depuis les plugins utilise lasyntaxe de pluginutilisée partout ailleurs dans CakePHP :
class BakeriesController extends AppController {
public $helpers = array(’Blog.Comment’); }
Vous pouvez aussi ajouter les helpers depuis une action, dans ce cas, ils seront uniquement accessibles pour cette action et aucune autre dans le controller. Ceci économise de la puissance de calcul pour les autres actions qui n’utilisent pas le helper, tout en permettant de conserver le controller mieux organisé :
class BakeriesController extends AppController {
public function bake {
$this->helpers[] = ’Time’; }
public function mix {
// Le Helper Time n’est pas chargé ici et n’est par conséquent pas disponible
} }
Si vous avez besoin d’activer un helper pour tous les controllers, ajoutez son nom dans le tableau $helpers du fichier /app/Controller/AppController.php (à créer si pas présent). N’oubliez pas d’inclure les helpers par défaut Html et Form :
class AppController extends Controller {
public $helpers = array(’Form’, ’Html’, ’Js’, ’Time’); }
Vous pouvez passer des options dans les helpers. Ces options peuvent être utilisées pour définir les valeurs d’attributs ou modifier le comportement du helper :
class AwesomeHelper extends AppHelper {
public function __construct(View $view, $settings = array()) {
parent::__construct($view, $settings); debug($options);
} }
class AwesomeController extends AppController {
public $helpers = array(’Awesome’ => array(’option1’ => ’valeur1’)); }
Depuis 2.3 les options sont fusionnées avec la propriété Helper::$settings du helper.
Une configuration courante est d’utiliser l’option className, qui vous permet de créer des helpers alias dans vos vues. Cette fonctionnalité est utile quand vous voulez remplacer $this->Html ou tout autre Helper de référence avec une mise en oeuvre personnalisée :
// app/Controller/PostsController.php
class PostsController extends AppController {
public $helpers = array( ’Html’ => array( ’className’ => ’MyHtml’ ) ); } // app/View/Helper/MyHtmlHelper.php App::uses(’HtmlHelper’, ’View/Helper’);
class MyHtmlHelper extends HtmlHelper {
// Ajouter votre code pour écraser le HtmlHelper du coeur }
Ce qui est au-dessus ferait un alias de MyHtmlHelper vers $this->Html dans vos vues.
Note : Faire un alias d’un helper remplace cette instance partout où le helper est utilisé, y compris dans les autres Helpers.
Astuce : Faire un alias des Helpers Html ou Session pendant que vous utilisez le coeur de PagesController ne fonctionnera pas. Il est préférable de copier lib/Cake/Controller/PagesController.php dans le dossier app/Controller/.
L’utilisation des configurations du helper vous permet de configurer de manière déclarative vos helpers et de garder la logique de configuration de vos actions des controllers. Si vous avez des options de configuration qui ne peuvent pas être inclues comme des parties de déclaration de classe, vous pouvez les définir dans le callback beforeRender de votre controller :
class PostsController extends AppController {
public function beforeRender() {
parent::beforeRender();
$this->helpers[’CustomStuff’] = $this->_getCustomStuffSettings(); }
}
Utiliser les Helpers
Une fois que vous avez configuré les helpers que vous souhaitiez utiliser, dans votre controller, chaque
helper est exposé en propriété publique dans la vue. Par exemple, si vous utilisiez HtmlHelper, vous
seriez capable d’y accéder en faisant ce qui suit :
echo $this->Html->css(’styles’);
Ce qui est au-dessus appelerait la méthode css du HtmlHelper. Vous pouvez accéder à n’importe quel helper chargé en utilisant $this->{$helperName}. Il peut venir un temps où vous aurez besoin de charger dynamiquement un helper à partir d’une vue. Vous pouvez utiliser la vue du HelperCollection pour le faire :
CakePHP Cookbook Documentation, Version 2.x
$mediaHelper = $this->Helpers->load(’Media’, $mediaSettings);
Le HelperCollection est unecollectionet supporte l’API collection utilisée partout ailleurs dans CakePHP.
Méthodes de Callback
Les Helpers disposent de plusieurs callbacks qui vous permettent d’augmenter le processus de rendu de vue.
Allez voir la documentation deAPI de HelperetCollectionspour plus d’informations.
Créer des Helpers
Si un helper du coeur (ou l’un présenté sur github ou dans la Boulangerie) ne correspond pas à vos besoins, les helpers sont faciles à créer.
Mettons que nous voulions créer un helper, qui pourrait être utilisé pour produire un lien CSS, façonné spécialement selon vos besoins, à différents endroits de votre application. Afin de trouver une place à votre logique dans la structure de helper existante dans CakePHP, vous devrez créer une nouvelle classe dans /app/View/Helper. Appelons notre assistant LienHelper. Le fichier de la classe PHP devrait ressembler à quelque chose comme ceci :
/* /app/View/Helper/LienHelper.php */ App::uses(’AppHelper’, ’View/Helper’);
class LienHelper extends AppHelper {
public function lancerEdition($titre, $url) {
// La logique pour créer le lien spécialement formaté se place ici...
} }
Note : Les Helpers doivent étendre soit AppHelper soitHelperou implémenter tous les callbacks dans
API de Helper.
Inclure d’autres Helpers
Vous souhaitez peut-être utiliser quelques fonctionnalités déjà existantes dans un autre helper. Pour faire cela, vous pouvez spécifier les helpers que vous souhaitez utiliser avec un tableau $helpers, formaté comme vous le feriez dans un controller :
/* /app/View/Helper/LienHelper.php (Utilisant d’autres helpers) */ App::uses(’AppHelper’, ’View/Helper’);
class LienHelper extends AppHelper {
public $helpers = array(’Html’);
public function lancerEdition($titre, $url) {
// Utilisation du helper HTML pour sortir une donnée formatée
$link = $this->Html->link($titre, $url, array(’class’ => ’edit’));
return ’<div class="editOuter">’ . $link . ’</div>’; }
}
Utiliser votre Helper
Une fois que vous avez créez votre helper et l’avez placé dans /app/View/Helper/, vous serez capable
de l’inclure dans vos controllers en utilisant la variable spéciale$helpers:
class PostsController extends AppController {
public $helpers = array(’Lien’); }
Une fois que votre controller est au courant de cette nouvelle classe, vous pouvez l’utiliser dans vos vues en accédant à un objet nommé d’après le helper :
<!-- fait un lien en utilisant le nouveau helper -->
<?php echo $this->Lien->lancerEdition(’Changer cette recette’, ’/recipes/edit/5’); ?>
Créer des fonctionnalités à vos Helpers
Tous les helpers étendent une classe spéciale, AppHelper (comme les models étendent AppModel et les controllers étendent AppController). Pour créer une fonctionnalité disponible pour tous les helpers, créez
/app/View/Helper/AppHelper.php:
App::uses(’Helper’, ’View’);
class AppHelper extends Helper {
public function customMethod () { }
}
API de Helper class Helper
La classe de base pour les Helpers. Elle fournit un nombre de méthodes utiles et des fonctionnalités pour le chargement d’autres helpers.
Helper::webroot($file)
Décide du nom de fichier du webroot de l’application. Si un thème est actif et que le fichier existe dans le webroot du thème courant, le chemin du fichier du thème sera retourné.