View Cells¶

Quand utiliser les Cells¶

Les Cells sont idéales pour la construction de components de page réutilisables qui nécessitent une interaction avec les models, la logique de view, et la logique de rendu. Un exemple simple serait un caddie dans un magasin en ligne, ou un menu de navigation selon des données dans un CMS.

Créer une Cell¶

Pour créer une cell, vous définissez une classe dans src/View/Cell, et un template dans templates/cell/. Dans cet exemple, nous ferons une cell pour afficher le nombre de messages dans la boite de messages de notification de l’utilisateur. D’abord, créons le fichier de classe. Son contenu devrait ressembler à ceci:

namespace App\View\Cell;

use Cake\View\Cell;

class InboxCell extends Cell
{

    public function display()
    {
    }

}

Sauvegardez ce fichier dans src/View/Cell/InboxCell.php. Comme vous pouvez le voir, comme pour les autres classes dans CakePHP, les Cells ont quelques conventions:

• Les Cells se trouvent dans le namespace App\View\Cell. Si vous faîtes une cell dans un plugin, le namespace sera PluginName\View\Cell.

• Les noms de classe doivent finir en Cell.

• Les classes doivent hériter de Cake\View\Cell.

Nous avons ajouté une méthode vide display() à notre cell, c’est la méthode conventionnelle par défaut pour le rendu de cell. Nous couvrirons la façon d’utiliser les autres méthodes plus tard dans la doc. Maintenant, créons le fichier templates/cell/Inbox/display.php. Ce sera le template pour notre nouvelle cell.

Vous pouvez générer ce bout de code rapidement en utilisant bake:

bin/cake bake cell Inbox

Générera le code que nous avons tapé.

namespace App\View\Cell;

use Cake\View\Cell;

class InboxCell extends Cell
{

    public function display()
    {
        $unread = $this->fetchTable('Messages')->find('unread');
        $this->set('unread_count', $unread->count());
    }

}

<!-- templates/cell/Inbox/display.php -->
<div class="notification-icon">
    Vous avez <?= $unread_count ?> messages non lus.
</div>

Charger les Cells¶

Les cells peuvent être chargées à partir des views en utilisant la méthode cell() et fonctionne de la même manière dans les deux contextes:

// Charge une cell d'une application
$cell = $this->cell('Inbox');

// Charge une cell d'un plugin
$cell = $this->cell('Messaging.Inbox');

Ce qui est au-dessus va charger la classe de cell nommée et exécuter la méthode display(). Vous pouvez exécuter d’autres méthodes en utilisant ce qui suit:

// Lance la méthode expanded() dans la cell Inbox
$cell = $this->cell('Inbox::expanded');

Si vous avez besoin que votre controller décide quelles cells doivent être chargées dans une requête, vous pouvez utiliser le CellTrait dans votre controller pour y activer la méthode cell():

namespace App\Controller;

use App\Controller\AppController;
use Cake\View\CellTrait;

class DashboardsController extends AppController
{
    use CellTrait;

    // More code.
}

$cell = $this->cell('Inbox::recent', ['-3 days']);

public function recent($since)
{
}

Afficher une Cell¶

Une fois qu’une cell a été chargée et exécutée, vous voudrez probablement l’afficher. La façon la plus simple pour rendre une cell est de faire une echo:

<?= $cell ?>

Ceci va afficher le template correspondant à la version en minuscule et avec des underscores de notre nom d’action, par exemple display.php.

Puisque les cells utilisent View pour afficher les templates, vous pouvez charger les cells supplémentaires dans un template de cell si nécessaire.

// Appel de render() explicitement
echo $this->cell('Inbox::recent', ['-3 days'])->render('messages');

// Définit le template avant de faire un echo de la cell.
$cell = $this->cell('Inbox'); ?>
$cell->viewBuilder()->setTemplate('messages');

echo $cell;

// Le Cache utilisant la config par défaut et une clé générée
$cell = $this->cell('Inbox', [], ['cache' => true]);

// Mise en cache avec une config de cache spécifique et une clé générée
$cell = $this->cell('Inbox', [], ['cache' => ['config' => 'cell_cache']]);

// Spécifie la clé et la config à utiliser.
$cell = $this->cell('Inbox', [], [
    'cache' => ['config' => 'cell_cache', 'key' => 'inbox_' . $user->id]
]);

Paginer des Données dans une Cell¶

Créer une cell qui qui rend des résultats paginés peut être fait en utilisant la classe Paginator de l’ORM. Voici un exemple de pagination des messages favoris d’un utilisateur:

namespace App\View\Cell;

use Cake\View\Cell;
use Cake\Datasource\Paginator;

class FavoritesCell extends Cell
{
    public function display($user)
    {
        // Création du paginator
        $paginator = new Paginator();

        // Pagination du model
        $results = $paginator->paginate(
            $this->fetchTable('Messages'),
            $this->request->getQueryParams(),
            [
                // Utilisation d'un finder personnalisé avec paramètre
                'finder' => ['favorites' => [$user]],

                // Utilisation de paramètre de query 'scoped'.
                'scope' => 'favorites',
            ]
        );
        $this->set('favorites', $results);
    }
}

La cell ci-dessus va paginer le model Messages en utilisant les paramètres de pagination “scopés”.

Utiliser des Helpers dans une Cell¶

Les cells ont leur propre contexte et leur propre instance View, mais les helpers chargés dans AppView::initialize() restent chargés comme d’habitude.

Pour charger un Helper spécifique uniquement pour une Cell spécifique, procédez de la façon suivante:

namespace App\View\Cell;

use Cake\View\Cell;

class FavoritesCell extends Cell
{
    public function initialize(): void {
        $this->viewBuilder()->addHelper('MonHelperPersonnalise');
    }
}