Helpers (Assistants)¶

Utiliser et configurer les Helpers¶

Vous activez les helpers 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:

class BakeriesController extends AppController {
    public $helpers = array('Form', 'Html', 'Js', 'Time');
}

L’ajout des helpers depuis les plugins utilise la syntaxe de plugin utilisé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 dans aucune autre action du 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 alias de helper 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 fera un alias de MyHtmlHelper vers $this->Html dans vos vues.

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 serez capable d’y accéder en faisant ce qui suit:

echo $this->Html->css('styles');

Ce qui est au-dessus appelera 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:

$mediaHelper = $this->Helpers->load('Media', $mediaSettings);

Le HelperCollection est une collection et 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 de API de Helper et Collections pour 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 pourra ê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 helper LienHelper. Le fichier de la classe PHP ressemblera à 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...
    }
}

/* /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>';
    }
}

class PostsController extends AppController {
    public $helpers = array('Lien');
}

<!-- 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é.

Helper::url($url, $full = false)¶

Génère une URL échappée de HTML, qui délégue à Router::url().

Helper::value($options = array(), $field = null, $key = 'value')¶

Récupère la valeur pour un nom d’input donné.

Helper::domId($options = null, $id = 'id')¶

Génère une valeur id en CamelCase pour le champ sélectionné courant. Ecraser cette méthode dans votre AppHelper vous permettra de changer la façon dont CakePHP génère les attributs ID.