Version: 5.x

Utiliser les vues

Introduction

Les vues contiennent le code HTML fourni par votre application et séparent votre logique de contrôleur/application de votre logique de présentation.

Configuration

Moteurs de template

Bow Framework implémente 2 moteurs de template et le template par défaut est Tintin.

La configuration des vues se trouve dans le fichier view.php du dossier config/.

Spécifiez le nom du template à utiliser avec l'option engine de la configuration, cette option peut prendre les valeurs suivantes : tintin, twig et php. Par défaut Bow utilise tintin.

Remarque

Notez que si vous définissez php, le rendu des vues se fera sans moteur de template.

Vous pouvez aussi changer l'extension de template en modifiant la valeur de l'entrée extension. Vous verrez également que les vues sont stockées dans le répertoire templates par défaut.

Création de vue

Une simple vue peut ressembler à ceci :

<!-- View stored in templates/greeting.tintin.php -->
<html>
  <body>
    <h1>Hello, {{ $name }}</h1>
  </body>
</html>

Après avoir modifié et sauvegardé votre vue dans templates/greeting.tintin.php, vous pouvez maintenant l'envoyer aux utilisateurs avec le helper view comme ceci :

$app->get('/', function() {
  return view('greeting', ['name' => 'Tintin']);
});

Utilisation

Exemple d'utilisation avec la classe statique View::parse :

View::parse(string $view, array $data = []): View

Paramètre	Type	Description
`$view`	`string`	Le nom de la vue, sans extension, relatif au dossier des vues
`$data`	`array`	Les données passées au template

use Bow\View\View;

echo View::parse('nom-de-la-vue-sans-extension');

Pour passer des variables à la vue :

use Bow\View\View;

echo View::parse('nom-de-la-vue-sans-extension', ['name' => 'bow']);

Helper

Vous pouvez utiliser le helper view qui s'utilise de la même façon.

Pour fixer un code de statut HTTP, utilisez plutôt response()->render('vue', $data, $code) (voir la documentation des réponses HTTP). View::parse() ne prend pas de code.

Avec la vue suivante :

<!-- View stored in templates/greeting.tintin.php -->
<html>
 <body>
  <h1>Hello, {{ $name }}</h1>
 </body>
</html>

Exemple dans un contrôleur :

namespace App\Controllers;

use App\Controllers\Controller;

class HomeController extends Controller
{
  /**
   * Show hello page
   *
   * @return mixed
   */
  public function show()
  {
    return view('greeting', ['name' => 'Bowphp']);
    // Ou
    return $this->render('greeting', ['name' => "Bowphp"]);
    // Ou
    return response()->render('greeting', ['name' => "Bowphp"]);
  }
}

Introduction Tintin

Tintin

Tintin est un template PHP qui se veut très simple et extensible. Il peut être utilisable dans n'importe quel projet PHP. Par défaut, Tintin est le moteur de template utilisé par Bow Framework.

Hello, {{ $name }}.

Bien entendu, vous n'êtes pas limité à afficher le contenu des variables transmises à la vue. Vous pouvez également faire écho aux résultats de toute fonction PHP. En fait, vous pouvez insérer n'importe quel code PHP dans une instruction echo Tintin:

Hello, {{ strtoupper($name) }}.

Les instructions Tintin {{ }} sont automatiquement envoyées via la fonction PHP htmlspecialchars pour empêcher les attaques XSS.

Affichage des données non échappées

Par défaut, les instructions Tintin {{ }} sont automatiquement envoyées via la fonction PHP htmlspecialchars pour empêcher les attaques XSS. Si vous ne souhaitez pas que vos données soient protégées, vous pouvez utiliser la syntaxe suivante:

Hello, {{{ $name }}}.

Ajouter un commentaire

Cette clause {## ##} permet d'ajouter un commentaire à votre code tintin.

{## This comment will not be present in the rendered HTML ##}

La directive %verbatim

Si vous affichez des variables JavaScript dans une grande partie de votre modèle, vous pouvez envelopper le code HTML dans la directive %verbatim afin de ne pas avoir à préfixer chaque instruction Tintin echo avec un symbole % :

%verbatim
  <div class="container">
    Hello, {{ name }}.
  </div>
%endverbatim

les directives `%if`

Ce sont les clauses qui permettent d'établir des branchements conditionnels comme dans la plupart des langages de programmation.

Vous pouvez construire des instructions if en utilisant les directives %if, %elseif, %elif, %else et %endif. Ces directives fonctionnent de la même manière que leurs homologues PHP :

%if ($name == 'tintin')
  {{ $name }}
%elseif ($name == 'template')
  {{ $name }}
%else
  {{ $name }}
%endif

Vous pouvez utiliser %elif à la place de %elseif.

Petite spécificité, le %unless quant à lui, il permet de faire une condition inverse du %if. Pour faire simple, voici un exemple:

%unless ($user->isAdmin())
  // do something else
%endunless

En plus des directives conditionnelles déjà discutées, les directives %isset, %empty, %notempty peuvent être utilisées comme raccourcis pratiques pour leurs fonctions PHP respectives :

%isset($records)
  // $records is defined and is not null...
%endisset

%empty($records)
  // $records is "empty"...
%endempty

%notempty($records)
  // $records is not "empty"...
%endnotempty

Vous pouvez ajouter %else pour effectuer une action contraire.

Les directives `%loop` / `%for` / `%while`

Souvent vous pouvez être amener à faire des listes ou répétitions sur des éléments. Par exemple, afficher tout les utilisateurs de votre plateforme.

L'utilisation de `%loop`

Cette clause faire exactement l'action de foreach.

%loop($names as $name)
  Bonjour {{ $name }}
%endloop

Cette clause peux être aussi coupler avec tout autre clause telque %if. Un exemple rapide.

%loop($names as $name)
  %if($name == 'tintin')
    Bonjour {{ $name }}
    %stop
  %endif
%endloop

Vous avez peut-être remarquer le %stop il permet de stoper l'éxécution de la boucle. Il y a aussi son conjoint le %jump, lui parcontre permet d'arrêter l'éxécution à son niveau et de lancer s'éxécution du prochain tour de la boucle.

Les sucres syntaxiques `%jump` et `%stop`

Souvent le dévéloppeur est amené à faire des conditions d'arrêt de la boucle %loop comme ceci:

%loop($names as $name)
  %if($name == 'tintin')
    %stop
    // Ou
    %jump
  %endif
%endloop

Avec les sucres syntaxique, on peut réduire le code comme ceci:

%loop($names as $name)
  %stop($name == 'tintin')
  // Ou
  %jump($name == 'tintin')
%endloop

L'utilisation de `%for` et `%while`

Cette clause faire exactement l'action de for.

%for($i = 0; $i < 10; $i++)
 // ..
%endfor

Cette clause faire exactement l'action de while.

%while($name != 'tintin')
 // ..
%endwhile

Classes et styles conditionnels

La directive %class compile conditionnellement une chaîne de classe CSS. La directive accepte un tableau de classes où la clé du tableau contient la ou les classes que vous souhaitez ajouter, tandis que la valeur est une expression booléenne. Si l'élément de tableau a une clé numérique, il sera toujours inclus dans la liste de classe rendue :

%php
  $isActive = false;
  $hasError = true;
%endphp

<span %class([
  'p-4',
  'font-bold' => $isActive,
  'text-gray-500' => ! $isActive,
  'bg-red' => $hasError,
])></span>
 
<span class="p-4 text-gray-500 bg-red"></span>

De même, la directive %style peut être utilisée pour ajouter conditionnellement des styles CSS en ligne à un élément HTML :

%php
  $isActive = true;
%endphp
 
<span %style([
    'background-color: red',
    'font-weight: bold' => $isActive,
])></span>
 
<span style="background-color: red; font-weight: bold;"></span>

Inclure les sous-vues

Souvent lorsque vous dévéloppez votre code, vous êtes amener à subdiviser les vues de votre application pour être plus flexible et écrire moin de code.

%include permet d'include un autre fichier de template dans un autre.

<div id="container">
  %include('filename', %data)
</div>

Si vous essayez d'inclure une vue qui n'existe pas, Tintin lancera une erreur. Si vous souhaitez inclure une vue qui peut ou non être présente, vous devez utiliser la directive %includeIf :

%includeIf("filename", ["name" => "Tintin"])

Si vous souhaitez %include une vue si une expression booléenne donnée est évaluée comme vraie ou fausse, vous pouvez utiliser les directives %includeWhen et %includeUnless:

%includeWhen($user->isAdmin(), "include-file-name", ["name" => "Tintin"])

PHP brut

Dans certaines situations, il est utile d'intégrer du code PHP dans vos vues. Vous pouvez utiliser la directive Tintin %php ou %raw pour exécuter un bloc de PHP simple dans votre template:

%php
  $counter = 1;
%endphp

%raw
  $counter = 1;
%endraw

Flash session

Dans le cas ou vous voulez afficher un message flash directement vue vous pouvez utiliser %flash. Et pour vérifier si une message flash existe %hasflash et %endhasflash :

%hasflash("error")
  <div class="alert alert-danger">
    %flash("error")
  </div>
%endhasflash

Injection de services

La directive %service peut être utilisée pour récupérer un service du conteneur. Le premier argument passé à %service est le nom de la variable dans laquelle le service sera placé, tandis que le second argument est le nom de la classe ou de l'interface du service que vous souhaitez résoudre :

%service('user_service', 'App\Services\UserService')
 
<div>
  %loop($user_service->all() as $user)
    <p>{{ $user->name }}</p>
  %endloop
</div>

Directives d'authentification

Les directives %auth et %guest peuvent être utilisées pour déterminer rapidement si l'utilisateur actuel est authentifié ou est un invité :

%auth
  // The user is authenticated...
%endauth
 
%guest
  // The user is not authenticated...
%endguest

Si nécessaire, vous pouvez spécifier la garde d'authentification qui doit être vérifiée lors de l'utilisation des directives %auth et %guest :

%auth('admin')
  // The user is authenticated...
%endauth
 
%guest('admin')
  // The user is not authenticated...
%endguest

Environment Guidelines

Vous pouvez vérifier si l'application s'exécute dans l'environnement de production à l'aide de la directive %production :

%production
  // Production specific content...
%endproduction

Ou, vous pouvez déterminer si l'application s'exécute dans un environnement spécifique à l'aide de la directive %env :

%env('staging')
  // The application is running in "staging"...
%endenv

%env(['staging', 'production'])
  // The application is running in "staging" or "production"...
%endenv

Champ CSRF

Chaque fois que vous définissez un formulaire HTML dans votre application, vous devez inclure un champ de jeton CSRF masqué dans le formulaire afin que le middleware de protection CSRF puisse valider la demande. Vous pouvez utiliser la directive %csrf Tintin pour générer le champ de jeton :

<form method="POST" action="/profile">
  %csrf
</form>

Champ Méthode

Étant donné que les formulaires HTML ne peuvent pas effectuer de requêtes PUT, PATCH ou DELETE, vous devrez ajouter un champ _method masqué pour usurper ces verbes HTTP. La directive %method Tintin peut créer ce champ pour vous :

<form action="/foo/bar" method="POST">
  %method('PUT')
</form>

Héritage avec %extends, %block et %inject

Comme tout bon système de template tintin support le partage de code entre fichier. Ceci permet de rendre votre code flexible et maintenable.

Considérérons le code tintin suivant:

# le fichier `layout.tintin.php`
<!DOCTYPE html>
<html>
<head>
  <title>Hello, world</title>
</head>
<body>
  <h1>Page header</h1>
  <div>
    %inject('content')
  </div>
  <p>Page footer</p>
</body>
</html>

Et aussi, on a un autre fichier qui hérite du code du fichier layout.tintin.php

# le fichier se nomme `content.tintin.php`
%extends('layout')

%block('content')
  <p>This is the page content</p>
%endblock

Explication

Le fichier content.tintin.php va hérité du code de layout.tintin.php et si vous rémarquez bien, dans le fichier layout.tintin.php on a la clause %inject qui a pour paramètre le nom du %block de content.tintin.php qui est content. Ce qui veut dire que le contenu du %block content sera remplacé par %inject. Ce qui donnéra à la fin ceci:

<!DOCTYPE html>
<html>
<head>
  <title>Hello, world</title>
</head>
<body>
  <h1>Page header</h1>
  <div>
    <p>This is the page content</p>
  </div>
  <p>Page footer</p>
</body>
</html>

Directive personnelisée

Tintin peut être étendu avec son systême de directive personnalisé, pour ce faire utilisé la méthode directive Créons des directives pour gérer un formulaires:

$tintin->directive('input', function (string $type, string $name, ?string $value) {
  return '<input type="'.$type.'" name="'.$name.'" value="'.$value.'" />';
});

$tintin->directive('button', function (string $type, string $label) {
  return '<button type="'.$type.'">'.$label.'"</button>';
});

$tintin->directive('form', function (string $action, string $method, string $enctype = "multipart/form-data") {
  return '<form action="'.$action.'" method="'.$method.'" enctype="'.$enctype.'">';
});

$tintin->directive('endform', function () {
  return '</form>';
});

Pour utiliser ces directives, rien de plus simple. Ecrivez le nom de la directive précédé la par %. Ensuite si cette directive prend des paramètres, lancer la directive comme vous lancez les fonctions dans votre programme.

<div class="container">
  %form("/posts", "post", "multipart/form-data")
    %input("text", "name")
    %button('submit', 'Add')
  %endform
</div>

La compilation se fait comme d'habitude, pour plus d'information sur la compilation.

echo $tintin->render('form');

Sortie après compilation:

<form action="/posts" method="post" enctype="multipart/form-data">
  <input type="text" name="name" value="" />
  <button type="submit">Add</button>
</form>

Ajouter vos directives via la configuration

Pour enregistrer vos directives au démarrage de Bow Framework, créez (ou modifiez) un provider dans app/Configurations/ qui étend Bow\Configuration\Configuration :

app/Configurations/ApplicationConfiguration.php
namespace App\Configurations;

use Bow\Configuration\Configuration;
use Bow\Configuration\Loader as Config;

class ApplicationConfiguration extends Configuration
{
  /**
   * Launch configuration
   */
  public function create(Config $config): void
  {
    $tintin = app('view')->getEngine();

    $tintin->directive('super', function () {
      return "Super !";
    });
  }

  public function run(): void
  {
    //
  }
}

N'oubliez pas d'enregistrer ce provider dans Kernel::configurations() pour qu'il soit exécuté au boot.

Maintenant la directive %super est disponible et vous pouvez l'utiliser.

return $tintin->render('%super');
// => Super !

La directive `%macro`

Souvent, vous serez amené utiliser ou réutiliser un bloc de template pour optimiser l'écriture de votre application. Alors les macros sont là pour cela.

Les macros doivent être définies dans un fichier séparé.

Pour vous utiliser les %macro vous devez passer en premier paramêtre le nom du macro et ensuite les paramêtres du macro.

Considérons le fichier user-macro.tintin.php.

%macro('users', array $users)
  %loop($users as $user)
    <div>{{ $user }}</div>
  %endloop
%endmacro

Pour utiliser le macro vous devez l'importer dans un autre fichier avec %import. Nous allons appeler le fichier app.tintin.php contenant le template suivant:

%import('user-macro')

%extends('layout')

%block('content')
  <div class="container">
    {{ users($users) }}
  </div>
%endblock

Pour la compilation nous allons passer la liste des utilisateurs suivant:

$users = ["franck", "lucien", "brice"];

$tintin->render('app', compact('users'));

Après compilation du fichier

<div>franck</div>
<div>lucien</div>
<div>brice</div>

Il manque quelque chose ?

Si vous rencontrez des problèmes avec la documentation ou si vous avez des suggestions pour améliorer la documentation ou le projet en général, veuillez déposer une issue pour nous, ou envoyer un tweet mentionnant le compte Twitter @bowframework ou sur directement sur le github.

Introduction​

Configuration​

Création de vue​

Utilisation​

Introduction Tintin​

Affichage des données non échappées​

Ajouter un commentaire​

La directive %verbatim​

les directives %if​

Les directives %loop / %for / %while​

L'utilisation de %loop​

Les sucres syntaxiques %jump et %stop​

L'utilisation de %for et %while​

Classes et styles conditionnels​

Inclure les sous-vues​

PHP brut​

Flash session​

Injection de services​

Directives d'authentification​

Environment Guidelines​

Champ CSRF​

Champ Méthode​

Héritage avec %extends, %block et %inject​

Explication​

Directive personnelisée​

Ajouter vos directives via la configuration​

La directive %macro​