Yii – Criando um widget – parte 1

Como você já reparou, o Yii vem com diversos widgets para facilitar nosso trabalho: Grid, Listview, Menu, Campos de formulários e muitos outros.
Mas e se nenhum desses widgets servir para solucionar algum requerimento de nossos projetos, como faremos?

Neste artigo irei mostrar como é fácil criar um widget para uso com o Yii.

Um widget nada mais é (como você já deve saber) do que uma classe utilizada para exibirmos informações na página. No Yii, a classe de um widget deve herdar da classe CWidget. Nossa classe deve implementar os métodos init (é executado quando chamamos $this->beginWidget) e run (é executado quando chamamos $this->endWidget). Ambos também são executados (nessa ordem citada) quando chamamos apenas via $this->widget.

Nosso widget fará algo simples: exibir vídeos do Youtube. Acredito que seja bom começar com um exemplo simples, para ficar mais fácil entender o funcionamento dessa classe.

Nosso widget receberá 3 parâmetros: videoId, que deverá ser o código do vídeo do Youtube, width e height, que especificarão as dimensões do vídeo exibido.

Primeiramente, crie um arquivo chamado embedYoutube.php. Nele, teremos apenas uma classe, onde usaremos o mesmo nome: embedYoutube:

class EmbedYoutube extends CWidget
{
    public $videoId;
    public $width = '560';
    public $height = '315';

No código acima, declaramos nossa classe (linha 1), indicando que ela herda da classe CWidget. Nas linhas 3-5, definimos os parâmetros que serão passados ao widget. Repare que as variáveis $width e $height receberam um valor inicial. Isso significa que, caso algum desses 2 parâmetros não seja passado pelo usuário, nosso widget usará valores padrão.

Vamos então à implementação do método init:

public function init()
{
    if (empty($this->videoId))
        throw new CException('O parâmetro videoId é obrigatório.');
}

No código acima, na linha 9 checamos se o parâmetro videoId foi passado. Caso negativo, geramos um erro, pois esse parâmetro é obrigatório:
Parâmetro faltando

No exemplo, coloquei a mensagem em português, mas o ideal seria (principalmente se o objetivo é distribuir o widget) colocá-la em inglês e usar os recursos de internacionalização do Yii, mas isso é assunto para outro artigo.

No nosso caso, o método init() precisará somente desse código. Vejamos então o método run:

public function run()
{
    $this->renderVideo();
}

Aqui, a linha 15 chama o método renderVideo, que será o responsável por gerar o código de exibição do vídeo. Eu poderia ter colocado o código diretamente no método run, mas preferi acrescentar o método renderVideo para que o código fique mais organizado. Isso é útil se em algum momento eu quiser acrescentar algo ao widget.
Veja o código do método renderVideo:

protected function renderVideo() //mostra o vídeo
{
     $embedCode = '<iframe width="' . $this->width . '"';
     $embedCode .= ' height="' . $this->height . '"';
     $embedCode .= 'src="http://www.youtube.com/embed/' . $this->videoId . '">';
     $embedCode .= '</iframe>';

     echo $embedCode;
}

Aqui, as linhas 22-25 geram o código do iframe (forma padrão que o youtube gera p/ incorporar vídeos) que exibirá nosso vídeo, utilizando os valores dos parâmetros que passamos ao widget.

Já a linha 27 faz exibir o código gerado.
Abaixo, mostro o código completo da classe:


class EmbedYoutube extends CWidget
{

    public $videoId;
    public $width = '560';
    public $height = '315';

    public function init()
    {
         if (empty($this->videoId))
             throw new CException('O parâmetro videoId é obrigatório.');
    }

    public function run()
    {
         $this->renderVideo();
    }

    protected function renderVideo() //mostra o vídeo
    {
         $embedCode = '<iframe width="' . $this->width . '"';
         $embedCode .= ' height="' . $this->height . '"';
         $embedCode .= 'src="http://www.youtube.com/embed/' . $this->videoId . '">';
         $embedCode .= '</iframe>';

         echo $embedCode;
    }
}

Vamos testar nosso widget. Para isso, crie uma subpasta chamada “embedYoutube” dentro da pasta protected\extensions\ de algum projeto onde você possa testar o widget (caso necessário, crie um novo projeto do Yii). Salve nossa classe(embedYoutube.php) dentro dessa subpasta.

Agora, na view que quer utilizar o widget, basta acrescentar o código:


$this->widget('ext.embedYoutube.embedYoutube', array(
	'width'=>'600',
	'height'=>'500',
    'videoId'=>'C1m9Zwfwc44',
));

Aqui, a linha 1 faz a chamada para nosso widget. Como você deve ter percebido, o primeiro parâmetro (‘ext.embedYoutube.embedYoutube’) indica que iremos utilizar o componente (no caso, widget) de nome embedYoutube, que está dentro da pasta embedYoutube, que por sua vez está dentro da pasta extensions de nosso projeto. As outras linhas customizam os parâmetros do widget.

Então, ao executar a página que utiliza nosso widget, teremos o vídeo exibido:

Widget de vídeo

Fácil, não? Na parte 2 desse artigo mostrarei como criar um widget mais elaborado, que utilize javascript e arquivos externos.

gustavo disse:
5

Muito bacana! Gostei da forma q mostrou 😀

Ednei disse:
4

Ótimo tutorial! Ideal para quem está começando no Yii como eu, ajudando a organizar melhor o codigo!
Valeu!
Aguardando a parte 2.