Helpers (Assistants)¶

Chargement Conditionnel des Helpers¶

Vous pouvez utiliser le nom de l’action courante pour charger conditionnellement des helpers:

class AppView extends View
{
    public function initialize(): void
    {
        parent::initialize();
        if ($this->request->getParam('action') === 'index') {
            $this->loadHelper('ListPage');
        }
    }
}

Vous pouvez également utiliser la méthode beforeRender() de vos controllers pour charger des helpers:

class ArticlesController extends AppController
{
    public function beforeRender(Event $event)
    {
        parent::beforeRender($event);
        $this->viewBuilder()->helpers(['MyHelper']);
    }
}

Options de Configuration¶

Vous pouvez passer des options de configuration dans les helpers. Ces options peuvent être utilisées pour définir les valeurs d’attributs ou modifier le comportement du helper:

namespace App\View\Helper;

use Cake\View\Helper;
use Cake\View\View;

class AwesomeHelper extends Helper
{
    public function initialize(array $config): void
    {
        debug($config);
    }
}

class AwesomeController extends AppController
{
    public $helpers = ['Awesome' => ['option1' => 'value1']];
}

Les options peuvent être spécifiées lors de la déclaration des helpers dans le controller comme montré ci-dessous:

namespace App\Controller;

use App\Controller\AppController;

class AwesomeController extends AppController
{
    public $helpers = ['Awesome' => ['option1' => 'value1']];
}

Par défaut, toutes les options de configuration sont fusionnées avec la propriété $_defaultConfig. Cette propriété doit définir les valeurs par défaut de toute configuration dont votre helper a besoin. Par exemple:

namespace App\View\Helper;

use Cake\View\Helper;
use Cake\View\StringTemplateTrait;

class AwesomeHelper extends Helper
{

    use StringTemplateTrait;

    protected $_defaultConfig = [
        'errorClass' => 'error',
        'templates' => [
            'label' => '<label for="{{for}}">{{content}}</label>',
        ],
    ];
}

Toute configuration fournie au constructeur de votre helper sera fusionnée avec les valeurs par défaut pendant la construction et les données fusionnées seront définies à _config. Vous pouvez utiliser la méthode config() pour lire la configuration actuelle:

// Lit l'option de config errorClass.
$class = $this->Awesome->config('errorClass');

L’utilisation de la configuration du helper vous permet de configurer de manière déclarative vos helpers et de garder la logique de configuration en dehors des actions de votre controller. Si vous avez des options de configuration qui ne peuvent pas être inclues comme une partie de la classe de déclaration, vous pouvez les définir dans le callback beforeRender() de votre controller:

class PostsController extends AppController
{
    public function beforeRender(Event $event)
    {
        parent::beforeRender($event);
        $builder = $this->viewBuilder();
        $builder->helpers([
            'CustomStuff' => $this->_getCustomStuffConfig()
        ]);
    }
}

Faire des Alias de Helpers¶

Une configuration habituelle à utiliser est l’option className, qui vous permet de créer des alias de helpers dans vos vues. Cette fonctionnalité est utile quand vous voulez remplacer $this->Html ou une autre référence du Helper habituel avec une implémentation personnalisée:

// src/View/AppView.php
class AppView extends View
{
    public function initialize(): void
    {
        $this->loadHelper('Html', [
            'className' => 'MyHtml'
        ]);
    }
}

// src/View/Helper/MyHtmlHelper.php
namespace App\View\Helper;

use Cake\View\Helper\HtmlHelper;

class MyHtmlHelper extends HtmlHelper
{
    // Ajout de code pour surcharger le HtmlHelper du cœur
}

Ce qui est au-dessus va faire un alias de MyHtmlHelper vers $this->Html dans vos vues.

Charger les Helpers à la Volée¶

Il peut y avoir des cas où vous aurez besoin de charger dynamiquement un helper depuis l’intérieur d’une vue. Pour cela, vous pouvez utiliser le Cake\View\HelperRegistry:

// Les deux solutions fonctionnent.
$mediaHelper = $this->loadHelper('Media', $mediaConfig);
$mediaHelper = $this->helpers()->load('Media', $mediaConfig);

Le HelperCollection est une registry et supporte l’API collection utilisée partout ailleurs dans CakePHP.

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:

/* src/View/Helper/LinkHelper.php (utilisant d'autres helpers) */

namespace App\View\Helper;

use Cake\View\Helper;

class LinkHelper extends Helper
{
    public $helpers = ['Html'];

    public function makeEdit($title, $url)
    {
        // Utilise le Helper Html pour afficher la sortie
        // des données formatées:

        $link = $this->Html->link($title, $url, ['class' => 'edit']);

        return '<div class="editOuter">' . $link . '</div>';
    }
}

Utiliser votre Helper¶

Une fois que vous avez créé votre helper et l’avez placé dans src/View/Helper/, vous pouvez le charger dans vos vues:

class AppView extends View
{
    public function initialize(): void
    {
        parent::initialize();
        $this->loadHelper('Link');
    }
}

Une fois que votre helper est chargé, vous pouvez l’utiliser dans vos vues en accédant à l’attribut de vue correspondant:

<!-- fait un lien en utilisant le nouveau helper -->
<?= $this->Link->makeEdit('Changez cette Recette', '/recipes/edit/5') ?>

Accéder aux variables de la View dans votre Helper¶

Si vous voulez accéder à une variable de la View dans votre helper, vous pouvez utiliser $this->_View->viewVars, comme illustré ci-dessous:

class AwesomeHelper extends Helper
{

    public $helpers = ['Html'];

    public someMethod()
    {
        // Définit la meta description
        echo $this->Html->meta(
            'description', $this->_View->viewVars['metaDescription'], ['block' => 'meta']
        );
    }
}

Rendre un Element de Vue dans votre Helper¶

Si vous souhaiter rendre un Element dans votre Helper, vous pouvez utiliser $this->_View->element() comme ceci:

class AwesomeHelper extends Helper
{
    public someFunction()
    {
        // Affiche directement dans votre helper
        echo $this->_View->element('/path/to/element',['foo'=>'bar','bar'=>'foo']);

        // ou le retourne dans votre vue
        return $this->_View->element('/path/to/element',['foo'=>'bar','bar'=>'foo']);
    }
}

Callbacks¶

En implémentant une méthode de callback dans un helper, CakePHP va automatiquement inscrire votre helper à l’évènement correspondant. A la différence des versions précédentes de CakePHP, vous ne devriez pas appeler parent dans vos callbacks, puisque la classe Helper de base n’implémente aucune des méthodes de callback.

Helper::beforeRenderFile(Event $event, $viewFile)¶

Est appelé avant que tout fichier de vue soit rendu. Cela inclut les elements, les vues, les vues parentes et les layouts.

Helper::afterRenderFile(Event $event, $viewFile, $content)¶

Est appelé après que tout fichier de vue est rendu. Cela inclut les elements, les vues, les vues parentes et les layouts. Un callback peut modifier et retourner $content pour changer la manière dont le contenu rendu est affiché dans le navigateur.

Helper::beforeRender(Event $event, $viewFile)¶

La méthode beforeRender() est appelée après la méthode beforeRender() du controller, mais avant les rendus du controller de la vue et du layout. Reçoit le fichier à rendre en argument.

Helper::afterRender(Event $event, $viewFile)¶

Est appelé après que la vue est rendu, mais avant que le rendu du layout ait commencé.

Helper::beforeLayout(Event $event, $layoutFile)¶

Est appelé avant que le rendu du layout commence. Reçoit le nom du fichier layout en argument.

Helper::afterLayout(Event $event, $layoutFile)¶

Est appelée après que le rendu du layout est fini. Reçoit le nom du fichier layout en argument.