La passion du libre

Le guide complet de Yii 2 (traduction du guide officiel)

Cliquez sur le bouton pour afficher les conseils de lecture.Cliquez à nouveau pour les masquer

Fenêtres surgissantes explicatives

Certains mots dans le texte, affichés en vert et en gras, sont précédés d'une étoile verte sur fond orange. Par exemple, ce mot : lien.

Si vous placez le pointeur de la souris sur un tel mot, une fenêtre surgissante – popup – s'ouvre alors que l'affichage du reste du documment s'atténue. Cette fenêtre contient une explication détaillée du mot en question

Une fois que vous avez pris connaissance de ce que vous affiche cette fenêtre surgissante, vous pouvez retourner à l'état normal en cliquant ailleurs dans le document.

Navigation

Pour naviguer, utilisez le menu vertical à gauche du texte. Les entrées de menu marquées d'une petite flèche vers le bas ouvrent un sous-menu lorsqu'on clique dessus.

Vous pouvez également choisir une lecture continue en cliquant sur un des liens proposés en bas de page.

Objets graphiques

Les objets graphiques (widgets) sont des blocs de construction réutilisables dans des vues pour créer des éléments d'interface utilisateur complexes et configurables d'une manière orientée objet. Par exemple, un composant d'interface graphique de sélection de date peut générer un sélecteur de date original qui permet aux utilisateurs de sélectionner une date en tant qu'entrée. Tout ce que vous avez besoin de faire, c'est d'insérer le code dans une vue comme indiqué ci-dessous :

<?php
use yii\jui\DatePicker;
?>
<?= DatePicker::widget(['name' => 'date']) ?>

Il existe un grand nombre d'objets graphiques fournis avec Yii, tels que les[[yii\widgets\ActiveForm|active form]], [[yii\widgets\Menu|menu]], jQuery UI widgets, Twitter Bootstrap widgets. Dans ce qui suit, nous introduisons les connaissances de base sur les objets graphiques. Reportez-vous à la documentation de la classe dans l'API si vous désirez en apprendre davantage sur un objets graphique particulier.

Utilisation des objets graphiques

Les objets graphiques sont utilisés en premier lieu dans des vues. Vous pouvez appeler la méthode [[yii\base\Widget::widget()]] pour utiliser un objets graphique dans une vue. Cette méthode accepte un tableau de configuration pour initialiser l'objet graphique d'interface et retourne le résultat du rendu de cet objet. Par exemple, le code suivant insère un objets graphique de sélection de date qui est configuré dans la langue russe et conserve l'entrée dans l'attribut from_date du $model.

<?php
use yii\jui\DatePicker;
?>
<?= DatePicker::widget([
    'model' => $model,
    'attribute' => 'from_date',
    'language' => 'ru',
    'clientOptions' => [
        'dateFormat' => 'yy-mm-dd',
    ],
]) ?>

Quelques objets graphiques peuvent accepter un bloc de contenu qui doit être compris entre l'appel des méthodes [[yii\base\Widget::begin()]] et [[yii\base\Widget::end()]]. Par exemple, le code suivant utilise l'objets graphique [[yii\widgets\ActiveForm]] pour générer une ouverture de balise <form> à l'endroit de l'appel de begin() et une fermeture de la même balise à l'endroit de l'appel de end(). Tout ce qui se trouve entre les deux est rendu tel quel.

<?php
use yii\widgets\ActiveForm;
use yii\helpers\Html;
?>

<?php $form = ActiveForm::begin(['id' => 'login-form']); ?>

    <?= $form->field($model, 'username') ?>

    <?= $form->field($model, 'password')->passwordInput() ?>

    <div class="form-group">
        <?= Html::submitButton('Login') ?>
    </div>

<?php ActiveForm::end(); ?>

Notez que contrairement à la méthode [[yii\base\Widget::widget()]] qui retourne le résultat du rendu d'un objets graphique, la méthode [[yii\base\Widget::begin()]] retourne une instance de l'objets graphique que vous pouvez utiliser pour construire le contenu de l'objet d'interface.

Note: quelques objets graphiques utilisent la mise en tampon de sortie pour ajuster le contenu inclus quand la méthode [[yii\base\Widget::end()]] est appelée. Pour cette raison, l'appel des méthodes [[yii\base\Widget::begin()]] and [[yii\base\Widget::end()]] est attendu dans le même fichier de vue. Ne pas respecter cette règle peut conduire à des résultats inattendus.

Configuration des variables globales par défaut

Les variables globales par défaut pour un objets graphique peuvent être configurées via le conteneur d'injection de dépendances (DI container) :

\Yii::$container->set('yii\widgets\LinkPager', ['maxButtonCount' => 5]);

Voir la section "Utilisation pratique " dans le Guide du conteneur d'injection de dépendances pour les détails.

Création d'objets graphiques

Pour créer un objets graphique, étendez la classe [[yii\base\Widget]] et redéfinissez sa méthode [[yii\base\Widget::init()]] et/ou sa méthode [[yii\base\Widget::run()]]. Ordinairement, la méthode init() devrait contenir le code qui normalise les propriétés de l'objets graphique, tandis que la méthode run() devrait contenir le code qui génère le résultat du rendu de cet objets graphique. Le résultat du rendu peut être "renvoyé en écho" directement ou retourné comme une chaîne de caractères par la méthode run().

Dans l'exemple suivant, HelloWidget encode en HTML et affiche le contenu assigné à sa propriété message. Si la propriété n'est pas définie, il affiche "Hello World" par defaut.

namespace app\components;

use yii\base\Widget;
use yii\helpers\Html;

class HelloWidget extends Widget
{
    public $message;

    public function init()
    {
        parent::init();
        if ($this->message === null) {
            $this->message = 'Hello World';
        }
    }

    public function run()
    {
        return Html::encode($this->message);
    }
}

Pour utiliser cet objets graphique, contentez-vous d'insérer le code suivant dans une vue :

<?php
use app\components\HelloWidget;
?>
<?= HelloWidget::widget(['message' => 'Good morning']) ?>

Ce-dessous, nous présentons une variante de HelloWidget qui prend le contenu inséré entre les appels des méthodes begin() et end(), l'encode en HTML et l'affiche.

namespace app\components;

use yii\base\Widget;
use yii\helpers\Html;

class HelloWidget extends Widget
{
    public function init()
    {
        parent::init();
        ob_start();
    }

    public function run()
    {
        $content = ob_get_clean();
        return Html::encode($content);
    }
}

Comme vous pouvez le voir, le tampon de sortie de PHP est démarré dans init() de manière à ce que toute sortie entre les appels de init() et de run() puisse être capturée, traitée et retournée dans run().

Info: lorsque vous appelez [[yii\base\Widget::begin()]], une nouvelle instance de l'objets graphique est créé et sa méthode init() est appelée à la fin de la construction de l'objet. Lorsque vous appelez [[yii\base\Widget::end()]], la méthode run() est appelée et sa valeur de retour est renvoyée en écho par end().

Le code suivant montre comment utiliser cette nouvelle variante de HelloWidget:

<?php
use app\components\HelloWidget;
?>
<?php HelloWidget::begin(); ?>

    content that may contain <tag>'s

<?php HelloWidget::end(); ?>

Parfois, un objets graphique peut avoir à rendre un gros bloc de contenu. Bien que vous puissiez incorporer le contenu dans la méthode run(), une meilleure approche consiste à le mettre dans une vue et à appeler la méthode [[yii\base\Widget::render()]] pour obtenir son rendu. Par exemple :

public function run()
{
    return $this->render('hello');
}

Par défaut, les vues pour un objets graphique doivent être stockées dans le dossier WidgetPath/views, où WidgetPath représente le dossier contenant la classe de l'objets graphique. Par conséquent, l'exemple ci-dessus rend le fichier de vue @app/components/views/hello.php, en supposant que la classe de l'objets graphique est située dans le dossier @app/components. Vous pouvez redéfinir la méthode [[yii\base\Widget::getViewPath()]] pour personnaliser le dossier qui contient les fichiers de vue des objets graphiques.

Meilleures pratiques

Les objets graphiques sont une manière orientée objets de réutiliser du code de vues.

Lors de la création d'objets graphiques, vous devriez continuer de suivre le modèle d'architecture MVC. En général, vous devriez conserver la logique dans les classes d'objets graphiques et la présentation dans les vues.

Les objets graphiques devraient également être conçus pour être auto-suffisants. Cela veut dire que, lors de l'utilisation d'un tel objet, vous devriez être en mesure de vous contenter de le placer dans une vue sans rien faire d'autre. Cela peut s'avérer délicat si un objets graphique requiert des ressources externes, comme du CSS, du JavaScript, des images, etc. Heureusement, Yii fournit une prise en charge des paquets de ressources que vous pouvez utiliser pour résoudre le problème.

Quand un objets graphique contient du code de vue seulement, il est très similaire à une vue. En fait, dans ce cas, la seule différence est que l'objet graphique est une classe redistribuable, tandis qu'une vue est juste un simple script PHP que vous préférez conserver dans votre application.