yii/docs/guide/fr/basics.component.txt

Composant
=========

Les applications Yii sont construites à partir de composants, i.e. d'objets
écrits dans le but de répondre à des spécifications et un cahier des charges précis.
Un composant est une instance de [CComponent] ou d'une de ses classes dérivées.
L'utilisation d'un composant consiste principalement à accéder à ses propriétés et
utiliser ses événements. La classe de base [CComponent] spécifie comment définir les
propriétés et les événements.

Définir et utiliser la propriété d'un composant
-----------------------------------------------

Une propriété d'un composant est similaire à une variable publique d'un
objet. Il est possible d'y lire ou d'y assigner une valeur. Par exemple,

~~~
[php]
$width=$component->textWidth;     // récupère la propriété textWidth
$component->enableCaching=true;   // définit la propriété enableCaching
~~~

Pour définir une propriété, il est possible soit de déclarer une
variable publique au sein de la classe du composant, soit de définir
les getter et setter correspondant comme ceci:

~~~
[php]
public function getTextWidth()
{
	return $this->_textWidth;
}

public function setTextWidth($value)
{
	$this->_textWidth=$value;
}
~~~

Le fragment de code ci-dessus définit un accès en lecture/écriture
à la propriété nommée `textWidth` (le nom n'est pas sensible à la casse).
Lors de la lecture de la propriété, `getTextWidth()` est appelée et la
valeur retournée devient la valeur de la propriété; le fonctionnement est
similaire lorsque l'on y accède en écriture, la méthode `setTextWidth()` est
appelée. Si le setter n'est pas défini, la propriété est accessible en
lecture seule et un accès en écriture lève une exception. L'utilisation
de getter et setter à l'avantage de permettre d'insérer de la logique de traitement
lors de l'accès à la propriété (e.g. effectuer une validation, lever un événement).


>Attention: Il existe une légère différence entre une propriété définie
par un getter/setter et une variable de classe. Lors de l'utilisation d'un
getter/setter, le nom de la propriété est insensible à la casse ce qui n'est
pas le cas pour une variable de classe.

Evénement et composant
----------------------

Les événements d'un composant sont des propriétés spéciales qui prennent pour
valeur des méthodes (appelées `gestionnaires d'événement`). Le fait d'attacher
(assigner ou affecter) une méthode à un événement va permettre d'invoquer automatiquement
la méthode dès que l'événement est levé. Par conséquent, le comportement d'un composant
peut être modifié d'une manière qui ne peut parfois pas être prévue pendant le développement et
la mise au point du composant.


Un événement est défini par une méthode dont le nom commence par `on`.
Tout comme pour les propriétés définies par des getter/setter, les noms des
événements ne sont pas sensibles à la casse. Le code suivant définit
un événement `onClicked`:

~~~
[php]
public function onClicked($event)
{
	$this->raiseEvent('onClicked', $event);
}
~~~

où `$event` est une instance de [CEvent] ou de l'une de ses classes filles.

Une méthode est attachée à un événement de la façon suivante:

~~~
[php]
$component->onClicked=$callback;
~~~

où `$callback` est une fonction de rappel PHP valide. Ce peut être une fonction
globale ou une méthode de classe. Dans ce cas (méthode de classe), la fonction
de rappel doit être donnée via un array: `array($object,'methodName')`.

La signature d'un gestionnaire d'événement doit être:

~~~
[php]
function methodName($event)
{
	......
}
~~~

où le paramètre `$event` décrit l'événement (il provient de l'appel de
`raiseEvent()`). Le paramètre `$event` doit être une instance de [CEvent]
ou de l'une de ses classes dérivées. A minima, il doit permettre de
savoir qui a levé l'événement.

A partir de la version 1.0.10, un gestionnaire d'événement peut être une fonction anonyme (ou une fonction lambda)
ce qui est supporté depuis PHP 5.3. Par exemple,

~~~
[php]
$component->onClicked=function($event) {
	......
}
~~~


Désormais, si l'on appelle `onClicked()`, l'événement `onClicked` va être
levé (à l'intérieur de `onClicked()`), et le gestionnaire d'événement
associé va être invoqué automatiquement.

Un événement peut être attaché à plusieurs gestionnaires. Lorsqu'un événement
est levé, les gestionnaires seront invoqués dans l'ordre dans lequel ils ont été attachés.
Si un gestionnaire doit interdire l'invocation des autres gestionnaires, il lui
suffit de mettre la propriété [$event->handled|CEvent::handled] à true.


Comportement d'un composant
---------------------------

A partir de la version 1.0.2, le support des [mixin](http://en.wikipedia.org/wiki/Mixin) a été
ajouté pour permettre d'attacher un composant à plusieurs comportements.
Un *comportement* (behavior) est un objet dont les méthodes peuvent être
'héritées' par les composants qui y sont attachés. L'idée étant de collecter
des fonctionnalités au lieu de spécialiser les composants (i.e. notion
d'héritage classique). Un composant peut donc être attaché à plusieurs
composants pour simuler 'l'héritage multiple'.

Les classes de comportement doivent implémenter l'interface [IBehavior].
La plupart des comportements peuvent directement étendre la classe de
base [CBehavior]. Si un comportement doit être attaché à un
[modèle](/doc/guide/basics.model), il est possible de le faire hériter
de [CFormBehavior] ou [CActiveRecordBehavior] qui implémentent des
fonctionnalités spécifiques à la gestion des modèles.

Pour pouvoir utiliser un comportement, il doit tout d'abord être attaché
à un composant en appelant la méthode [attach()|IBehavior::attach]. Ensuite,
le comportement peut être appelé via le composant comme ceci:

~~~
[php]
// $name identifie de façon unique le comportement du composant
$behavior->attach($name,$component);
// test() est une méthode de $behavior
$component->test();
~~~

Un comportement attaché à un composant peut être accédé comme une propriété
classique. Par exemple, si le comportement `tree` est attaché au composant
`component`, on peut obtenir la référence du comportement en utilisant:

~~~
[php]
$behavior=$component->tree;
// équivalent de la syntaxe
// $behavior=$component->asa('tree');
~~~

Un comportement peut être temporairement désactivé pour que ses méthodes
ne puissent être appelées par le composant.
Par exemple:

~~~
[php]
$component->disableBehavior($name);
// la ligne suivante va lever une exception
$component->test();
$component->enableBehavior($name);
// elle fonctionne désormais
$component->test();
~~~

Il est possible que deux comportements attachés au même composant aient des méthodes
avec un même nom. Dans ce cas, la méthode appartement au comportement qui a été
attaché en premier aura la précédence.

Lorsqu'ils sont utilisés avec les [événements](#component-event), les comportements
peuvent être extrêmement puissants. Un comportement, lorsqu'il est affecté à un
composant, peut attacher certaines de ses méthodes à des événements du composant.
Cela permet à un comportement d'observer et/ou de changer le cycle d'exécution du
composant.

Depuis la version 1.1.0, les propriétés d'un `comportement` sont accessibles directement depuis
le composant auquel il est rattaché. Les propriétés intègrent à la fois les variables publiques
et les propriétés du comportement définies par les getter/setter. Par exemple, si un comportement
à une propriété `xyz` et que ce comportement est attaché à un composant `$a`. Alors il devient possible
d'utiliser l'expression `$a->xyz` pour accéder à la propriété du comportement.

<div class="revision">$Id: basics.component.txt 1476 $</div>