Componente

As aplicações feitas com o Yii são construídas por componentes, que são objetos desenvolvidos para um fim específico. Um componente é uma instância da classe CComponent, ou uma de suas classes derivadas. A utilização de um componente basicamente envolve o acesso à suas propriedades e a execução/manipulação de seus eventos. A classe base CComponent especifica como definir propriedades e eventos.

1. Propriedade de um Componente ¶

Uma propriedade de um componente é como uma variável membro pública de um objeto. Nós podemos ler seu conteúdo ou lhe atribuir novos valores. Por exemplo:

$width=$component->textWidth;     // acessa a propriedade textWidth
$component->enableCaching=true;   // altera a propriedade enableCaching

Para definir uma propriedade em um componente, podemos simplesmente declarar uma variável membro pública na classe do componente. No entanto, existe uma maneira mais flexível, que consiste em definir métodos acessores (getters e setters), como no exemplo a seguir:

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

No código acima, definimos uma variável alterável chamada textWidth (o nome é case-insensitive, não faz diferença entre maiúsculas e minúsculas). Ao acessar a propriedade, o método getTextWidth() é executado e seu valor de retorno é o valor da propriedade. De maneira parecida, ao alterar o valor da propriedade, utilizamos o método setTextWidth(). Se o método setter não não for definido, a propriedade será do tipo somente leitura e a tentativa de alterar seu valor lançará uma exceção.

Nota: Existe uma pequena diferença entre uma propriedade definida via métodos acessores (getters e setters) e variáveis membros de classe. No primeiro caso, o nome da variável é case-insensitive, enquanto que, no último, o nome é case-sensitive (há diferença entre maiúsculas de minúsculas).

2. Eventos de um Componente ¶

Os eventos de um componente são propriedades especiais que aceitam métodos (chamados de event handlers, manipuladores de eventos) como seus valores. Ao atribuir um método a um evento, fará com que ele seja executado cada vez que o evento for disparado. Portanto, o comportamento de um componente pode ser alterado para funcionar de maneira diferente de como foi desenvolvido.

Um evento pode ser criado definindo-se um método cujo nome inicie com on. Assim como as propriedades definidas via métodos acessores, os nomes de eventos também são case-insensitive. O código abaixo define um evento chamado onClicked:

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

No exemplo acima, $event é uma instância da classe CEvent, ou de uma de suas classes derivadas, e está representando o parâmetro do evento.

Podemos atribuir um método para esse evento da seguinte maneira:

$component->onClicked=$callback;

Onde $callback refere-se a um callback válido em PHP. Ele pode ser uma função global ou um método de classe. No último caso, o callback deve ser passado como um vetor no formato: array($objeto,'nomeDoMetodo').

A assinatura de um manipulador de evento deve ser a seguinte:

function nomeDoMetodo($event)
{
    ......
}

Onde $event é o parâmetro descrevendo o evento ocorrido (originado na chamada do método raiseEvent()). O parâmetro $event é uma instância da classe CEvent, ou uma de suas classes derivadas, e, no mínimo, ele contém a informação sobre quem originou o evento.

Agora, se executarmos o método onClicked(), o evento onClicked será disparado e o manipulador de evento a ele atribuído será invocado automaticamente.

Um evento pode ter diversos manipuladores. Quando o evento é disparado, os manipuladores serão executados, um a um, na ordem em que foram atribuídos ao evento. Um manipulador pode impedir que os manipuladores restantes sejam executados, para isso altere o valor de $event->handled para true.

3. Comportamento de um Componente ¶

A partir da versão 1.0.2, os componentes passaram a suportar mixin, e, portanto, ganharam a possibilidade de receber um ou mais comportamentos. Um comportamento (behavior) é um objeto cujo os métodos podem ser "herdados" pela classe que o anexou, com a finalidade de coleta de funcionalidades em vez de especialização (por exemplo, a herança normal de classes). Um componente pode receber diversos comportamentos e, assim, utilizar a "herança múltipla".

Classes de comportamento devem implementar a interface IBehavior. A maioria dos comportamentos podem utilizar a classe CBehavior como base, estendendo-a. Se um comportamento precisar ser atribuído a um modelo, ele deve estender as classes CModelBehavior ou CActiveRecordBehavior, que implementam características específicas para modelos.

Para utilizar um comportamento, primeiro ele deve ser atribuído a um componente, utilizando o método attach(). Em seguida, podemos executar o comportamento através do componente, da seguinte maneira:

// $nome identifica únicamente o comportamento dento do componente
$componente->attachBehavior($nome, $comportamento);
// test() é um método de $comportamento
$componente->test();

Um comportamento atribuído pode ser acessado normalmente, como uma propriedade do componente. Por exemplo, se um comportamento denominado tree é atribuído a um componente, podemos obter obter uma referência dele da seguinte maneira:

$behavior=$component->tree;
// equivalente a:
// $behavior=$component->asa('tree');

Podemos desabilitar um comportamento temporariamente, para que seus métodos não estejam disponíveis através do componente:

$component->disableBehavior($name);
// a linha abaixo irá gerar uma exceção
$component->test();
$component->enableBehavior($name);
// agora funciona
$component->test();

É possível que dois comportamentos atribuídos ao mesmo componente tenham métodos com o mesmo nome. Nesse caso, o método do comportamento atribuído primeiro terá precedência.

Os comportamentos são ainda mais poderosos quando utilizado com eventos. Um comportamento, quando atribuído a um componente, pode utilizar alguns de seus métodos como callbacks para os eventos do componente. Dessa forma, o comportamento tem a possibilidade de observar ou alterar o fluxo de execução do componente.