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

Komponente
==========

Yii-Anwendungen bestehen aus Komponenten. Eine Komponente ist ein Objekt vom
Typ [CComponent] (oder einere davon abgeleitete Klasse), das eine ganz
bestimmte Aufgabe übernimmt. Meist greift man nur auf Eigenschaften von
Komponenten zu oder reagiert auf deren Events bzw. löst diese aus. Die
Basisklasse [CComponent] legt fest, wie man Eigenschaften und Events
definiert.


Definieren und Verwenden von Eigenschaft 
----------------------------------------

Eine Eigenschaft einer Komponente verhält sich wie eine öffentliche 
Klassenvariable. Man kann Ihren Wert lesen oder ihr einen Wert zuweisen. 
Zum Beispiel:

~~~
[php]
$width=$component->textWidth;     // Liest die Eigenschaft textWidth
$component->enableCaching=true;   // Setzt die Eigenschaft enableCaching
~~~

Eine Eigenschaft kann daher einfach eine öffentliche Variable in der Klasse
sein, die wie folgt definiert ist:

~~~
[php]
class Document extends CComponent
{
    public $textWidth;
}
~~~

Alternativ kann man aber auch, wesentlich flexiblere, Getter- 
und Setter-Methoden verwenden. Damit ist es möglich Eigenschaften
zu erzeugen, die nur lesbar oder nur schreibbar sind.
Wie das funktioniert sehen wir an folgendem Beispiel:

~~~
[php]
class Document extends CComponent
{
    private $_textWidth;
    protected $_completed=false;

    public function getTextWidth()
    {
        return $this->_textWidth;
    }

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

    public function getTextHeight()
    {
        // berechnet die Texthöhe und gibt anschließend das Ergebnis zurück
    }

    public function setCompleted($value)
    {
        $this->_completed=$value;
    }
}
~~~

Die oben gezeigte Klasse kann nun wie folgt verwendet werden:

~~~
[php]
$document=new Document();

// Wir können die Eigenschaft textWidth lesen und schreiben
$document->textWidth=100;
echo $document->textWidth;

// Wir können textHeight nur lesend verwenden
echo $document->textHeight;

// Wir können auf die Eigenschaft completed nur schreibend zugreifen
$document->completed=true;
~~~

Beim Lesen einer Eigenschaft, die nicht als öffentliche Variable definiert ist,
wird Yii versuchen eine Getter-Methode zu finden. Im Beispiel mit `textWidth`
ist die zugehörige Getter-Methode `getTextWidth`.
Als Wert der Eigenschaft gilt dann der Rückgabewert der Methode.
Analog funktioniert das auch, wenn wir schreibend zugreifen wollen.
In diesem Fall würde dann die Setter-Methode `setTextWidth` aufgerufen, der
als Parameter der zu setzende Wert übergeben wird.

Wenn die Setter-Methode nicht definiert ist, ist die Eigenschaft
nur lesbar und beim Schreiben würde eine Exception ausgelöst. Der Einsatz von
Getter-/Setter-Methoden zum Definieren einer Eigenschaft hat den Vorteil, das
beim Lesen und Schreiben zusätzliche Logik ausgeführt werden kann 
(z.B. Gültigkeitsprüfung durchführen, Events auslösen).


>Note|Hinweis: Es gibt einen kleinen Unterschied zwischen einer Eigenschaft,
>die durch Getter-/Setter-Methoden definiert wurde und einer Klassenvariable. Bei der
>ersteren spielt die Groß-/Kleinschreibung keine Rolle, bei letzerer schon.

Event
-----

Events (Ereignisse) sind spezielle Komponenteneigenschaften, die 
sog. `Eventhandler`-Methoden (sinngem.: Ereignisbearbeiter) als Wert erwarten. 
Hängt man eine Methode an ein Event an (engl.: attach), wird diese aufgerufen,
sobald das Event ausgelöst wird. Auf diese Weise kann man das Verhalten einer
Komponente nachträglich noch anpassen.

Ein Event wird definiert, indem man in einer Komponente eine Methode anlegt,
deren Name mit `on` beginnt. Auch bei Eventnamen wird die Schreibweise
(groß/klein) ignoriert. Das Event `onClicked` wird z.B. wie folgt definiert:

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

`$event` ist dabei eine Instanz vom Typ [CEvent] bzw. einer Kindklasse und
stellt den Eventparameter dar.

Eine Methode kann wie folgt an ein Event angehägt werden:

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

`$callback` muss eine gültige PHP-Callbackfunktion sein. Also entweder eine
globale Funktion oder auch eine Klassenmethode. In letzterem
Fall wird die Callbackfunktion als Array `array($objekt,'methodenName')`
angegeben.

Die Signatur eines solchen Eventhandlers (also einer Funktion, die bei einem
Event aufgerufen werden soll), muss wie folgt aussehen:

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

wobei `$event` ein Parameter ist, der das Event näher beschreibt. Er stammt
aus dem Aufruf von `raiseEvent()`. Der Eventparameter ist eine Instanz vom
Typ [CEvent] oder einer Kindklasse. Er enthält mindestens die
Information, wer das Event ausgelöst hat.

Ein Eventhandler kann auch eine anonyme Funktion sein, wie sie
seit PHP 5.3 unterstützt werden. Zum Beispiel:

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

Ruft man nun `onClicked()` auf, wird darin das Event `onClicked` ausgelöst
und der angehängte Eventhandler wird automatisch aufgerufen.

An ein Event können auch mehrere Handlermethoden angehängt sein. Beim Auslösen
des Events werden die Handler in der selben Reihenfolge aufgerufen, in der sie
an das Event angehängt wurden. Sollte in einer Handlermethode entschieden
werden, dass die verbleibenden Handler für dieses Event nicht mehr ausgeführt
werden sollen, kann darin [$event->handled|CEvent::handled] auf true gesetzt
werden.


Behavior
--------

Seit Version 1.0.2 unterstützen Komponenten auch
[Mixins](https://www.wikiservice.at/dse/wiki.cgi?MixIn). An eine Komponente
können damit ein oder mehrere Behaviors (Verhalten) angehägt werden. 
Die Komponente 'erbt' dann die Methoden des *Behavior*-Objekts. Allerdings
nicht als Spezialisierung (normale Klassenvererbung) sondern im Sinne einer
Ansammlung weiterer Funktionalitäten.

Behaviorklassen müssen das [IBehavior]-Interface implementieren. Die meisten
Behaviors können von der Basisklasse [CBehavior] abgeleitet werden. Behaviors
für ein [Model](/doc/guide/basics.model) können auch von den Klassen
[CFormBehavior] oder [CActiveRecordBehavior] abgeleitet werden, 
die zusätzliche Features speziell für diese Models beinhalten.

Möchte man ein Behavior mit einer Komponente verwenden, muss es zunächst mit der
[attach()|IBehavior::attach]-Methode angehängt werden. Danach können die
Behaviormethoden direkt über die Komponente aufgerufen werden.

~~~
[php]
// $name ist ein eindeutiger Bezeichner des Behaviors in der Komponente
$component->attachBehavior($name,$behavior);
// test() ist eine Methode des Behaviors
$component->test();
~~~

Auf ein angehängtes Behavior kann wie auf eine normale Komponenteneigenschaft
zugegriffen weden. Wurde z.B. ein Behavior namens `tree` mit einer
Komponente verbunden, kann man das Behaviorobjekt wie folgt ansprechen:

~~~
[php]
$behavior=$component->tree;
// gleichbedeutend zu:
// $behavior=$component->asa('tree');
~~~

Ein Behavior kann vorübergehend deaktiviert werden, so dass seine Methoden
nicht weiter über die Komponente zur Verfügung stehen. Zum Beispiel:

~~~
[php]
$component->disableBehavior($name);
// Die folgende Anweisung löst eine Exception aus
$component->test();
$component->enableBehavior($name);
// Jetzt funktioniert es wieder
$component->test();
~~~

Sollte eine Methode aufgerufen werden, die in zwei angehängten Behaviors vorhanden ist, 
wird die Methode des zuerst angehängten Behaviors aufgerufen.

Im Zusammenhang mit [Events](#component-event) sind Behaviors noch wesentlich
leistungsfähiger. Wenn ein Behavior an eine Komponente gehängt wird, kann
es eine oder mehrere seiner Methoden an Events dieser Komponente anhängen.
Dadurch kann kann das Behavior den normalen Prozessablauf innerhalb
einer Komponente überwachen oder verändern.

Die Eigenschaften eines Behaviors können auch über die Komponente, an der es
hängt, erreicht werden. Zugänglich sind alle öffentlichen Variablen bzw. 
Eigenschaften die mit Getter-/Setter-Methoden im Behavior definiert wurden. Falls ein
Behavior zum Beispiel eine Eigenschaft namens `xyz` besitzt und an eine
Komponente `$a` angebunden wurde, kann mit `$a->xyz` darauf zugegriffen
werden.