Framework W :: Documentation

Light & powerful PHP framework

Les vues

À quoi servent les vues ?

Les vues ou templates permettent de séparer le code de présentation du reste de la logique (contrôleur) ou des données (modèles). On y retrouve donc essentiellement des balises HTML et des echo de variables PHP.

W utilise un moteur de template nommé Plates. Plates n'est pas très connu, mais possède un avantage non-négligeable : il utilise PHP comme langage. En effet, la plupart des autres moteurs de templates (comme Twig ou Smarty) impose l'apprentissage d'un nouveau langage. Plates est d'ailleurs fortement inspiré de Twig, le passage de l'un à l'autre se fait assez aisément.

Comment créer un nouveau fichier de vue ?

Où placer ses fichiers de vues ?

Donnée importante à connaître : W vous impose de placer vos fichiers de vues sous le dossier app/Views/. Outre cette règle, vous êtes libre de faire comme bon vous semble.

Ceci étant, la plupart des pages de votre application devrait avoir un fichier de vue propre. Ainsi, il devrait y avoir à peu près autant de routes que de méthodes de contrôleur que de fichiers de vue dans votre application. Il est donc important de les classer un minimum, afin de s'y retrouver. Pour cette raison, W vous suggère de placer vos fichiers de vue dans des répertoires portant le même nom que son contrôleur (sans le suffixe Controller, et en minuscule). Ainsi, si vous avez un PostController et un UserController dans votre application, vous devriez avoir un dossier de vues nommé app/Views/post/ et un autre nommé app/Views/user/. Ce n'est toutefois qu'une convention suggérée.

Les fichiers de vue doivent avoir l'extension .php.

Que contient un fichier de vue ?

Au plus simple, un fichier de vue ne doit contenir qu'une page HTML complète. Lorsque votre contrôleur déclenchera l'affichage de votre fichier de vue, il enverra le contenu de celui-ci en réponse au client.

Le problème avec cette approche est bien sûr la duplication de code d'une page à l'autre, pour tous les nombreux éléments communs entre toutes les pages. Nous verrons plus loin comment Plates résoud d'une manière fort élégante ce problème.

Les CSS, les JS et les images

Tous les fichiers publics de votre application (publics dans le sens que vous considérez qu'un internaute doit pouvoir l'afficher directement dans son navigateur) doivent se trouver dans le dossier web/. Autrement, le navigateur n'y aura tout simplement pas accès. Ainsi, vos fichiers .css, .js et vos images (souvent nommés assets) devront nécessairement y être placés.

En fait, W prend pour acquis que ces fichiers seront dans le sous-répertoire public/assets/, afin de ranger plus finement ce dossier web/.

À l'exception de cette convention, vous faites vos styles et votre JavaScript comme dans toutes applications classiques : W est un framework back-end, et ne se préoccuppe pas de ce que vous faites côté client.

Les méthodes PHP disponibles

Puisque vos fichiers de vue sont des fichiers PHP, toutes les fonctions et structures de contrôles habituelles sont disponibles.

Mais Plates et W ajoutent quelques méthodes utiles par défaut :

/* app/Views/default/home.php */
<!DOCTYPE html>
<html lang="fr">
<head>
	<meta charset="utf-8">
	<title>Document</title>
</head>
<body>
	<?php
		//alias de htmlspecialchars(), pour la protection des attaques XSS
		echo $this->e("une chaîne à échapper");

		//génère et retourne l'URL d'une route nommée
		//à utiliser pour tous les liens internes
		echo $this->url("nom_de_la_route", ["nom_du_param" => "value_du_param"]);

		//génère et retourne l'URL absolue d'un fichier présent dans le dossier web/assets/
		//le chemin à passer en argument est toujours relatif au dossier web/assets/
		echo $this->assetUrl('img/logo.png');

		//joli print_r sur la variable toujours disponible $w_user
		//elle contiendra les données sur l'utilisateur connecté, ou sera null sinon
		debug($w_user);

		// affichera le nom de la route actuelle
		echo $w_current_route;

		// affichera le nom du site défini dans le fichier de configuration
		echo $w_site_name;

		// le flash message contient deux propriétés :
		echo $w_flash_message->message; // Le message utilisateur
		echo $w_flash_message->level; // Le niveau du flash message (utile pour les classes CSS par exemple)

	?>
</body>
</html>

Passer des données à la vue

Si vous avez créer des variables dans votre contrôleur auxquelles vous souhaitez accéder dans le fichier de vue, vous devez explicitement les y rendre disponible, les passer à la vue. Pour ce faire, dans le contrôleur, vous devez les spécifier dans un tableau, dans le second argument de la méthode render(). Voir le chapitre sur les contrôleurs pour plus de détails.

 /* app/Controller/DefaultController.php */

//...
public function demo()
{
	//affiche un template, tout en rendant des données disponibles dans celui-ci
	$this->render('default/demo', [
		'username' => 'will'
	]);
}
//...
Et dans la vue, la variable $username est automatiquement disponible :
/* app/Views/default/demo.php */

<!-- affichera "will" -->
<p>Pseudo : <?=$username;?></p>

Les layouts et l'héritage

Plates fournit un excellente système pour éviter la répétition des codes HTML communs à toutes les pages de votre application. Ce système est inspiré de Twig.

Le layout

Tout d'abord, vous créez un fichier contenant votre squelette HTML, qui sera commun à toutes les pages de votre application. On appelle souvent ce fichier le layout. Il peut être sauvegardé à la racine du dossier app/Views/, vue son importance.

<!DOCTYPE html>
<html lang="fr">
<head>
	<meta charset="utf-8">
	<title></title>
	<link rel="stylesheet" href="<?= $this->assetUrl('css/bootstrap.css') ?>">
</head>
<body>
	<div class="container">
		<header>
			<h1>W</h1>
		</header>
		<section>
			<!-- CONTENU SPÉCIFIQUE À CHAQUE PAGE ICI -->
			<?=$this->section('main_content'); ?>
		</section>
		<footer><?=date('Y');?> © Framework W</footer>
	</div>
</body>
</html>

Ainsi, toutes les pages du site pourront avoir cette structure HTML. Il suffit maintenant de placer le contenu spécifique à chaque page dans cette balise section. C'est là où opère la magie de Plates, en permettant à toutes nos pages d'hériter de cette structure, tout en redéfinissant le contenu des sections.

Hériter du layout

Pour qu'une page hérite de ce layout, il suffit de le spécifier au haut de la page, avec la méthode layout() de Plates.

/* app/Views/default/home.php */
<?php $this->layout('layout'); ?>

Cet appel à la méthode layout() spécifie au moteur de template que nous souhaitons hériter du contenu du fichier layout.php (le paramètre passé à la méthode).

À la manière d'une classe PHP qui hérite des propriétés et des méthodes d'une classe parente, notre fichier home.php hérite du contenu du fichier layout.php. Mais si nous le souhaitons, nous pouvons écraser, ou redéfinir, le contenu de toutes les sections qui ont été définies par la méthode section() du fichier parent. Dans notre exemple, la section définie dans le layout se nomme main_content.

Pour délimiter le contenu que l'on souhaite placer dans cette section, on utilise les méthodes start() et stop().

/* app/Views/default/home.php */
<?php $this->layout('layout'); ?>

<?php $this->start('main_content') ?>
	<h2>Ce texte remplace la section 'main_content' du layout !.</h2>
<?php $this->stop('main_content') ?>

Et voilà !

Définir plusieurs sections

Vous l'aurez peut-être deviné : il est possible de définir autant de sections que vous le souhaitez dans le layout, et de remplacer seulement les sections que vous avez besoin de redéfinir à partir des fichiers de vue enfants.

Par exemple, nous pouvons créer une section qui permettrait d'ajouter des fichiers css et des fichiers js facilement, à partir de n'importe quelle page du site :

<!DOCTYPE html>
<html lang="fr">
<head>
	<meta charset="UTF-8">
	<title></title>
	<link rel="stylesheet" href="<?= $this->assetUrl('css/reset.css') ?>">

	<!-- PERMET D'AJOUTER DES CSS ICI -->
	<?= $this->section('css') ?>
</head>
<body>
	<div class="container">
		<header>
			<h1>W</h1>
		</header>
		<section>
			<!-- CONTENU SPÉCIFIQUE À CHAQUE PAGE ICI -->
			<?= $this->section('main_content') ?>
		</section>
		<footer><?= date('Y') ?> W</footer>
	</div>

	<!-- PERMET D'AJOUTER DES JS ICI -->
	<?= $this->section('js') ?>
</body>
</html>

Et à partir de n'importe quelle page du site :

/* app/Views/default/home.php */
<?php $this->layout('layout'); ?>

<?php $this->start('main_content') ?>
	<h2>Ce texte remplace la section 'main_content' du layout !.</h2>
<?php $this->stop('main_content') ?>

<!-- Ajoute un javascript pour cette page seulement -->
<?php $this->start('js') ?>
	<script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.4/jquery.min.js"></script>
<?php $this->stop('js') ?>

<!-- Ajoute un css pour cette page seulement -->
<?php $this->start('css') ?>
	<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/css/bootstrap.min.css" />
<?php $this->stop('css') ?>

Pour plus d'infos, rendez-vous sur la documentation de Plates.