Yii – Criando um widget – parte 2

Demorou, mas aqui está. Finalmente posto a segunda parte do tutorial de criação de um widget para uso com o Yii Framework.

Na parte 1 mostrei o funcionamento básico de um widget simples, que exibe um vídeo do youtube.
Nesta sequência mostro como você pode utilizar arquivos externos, como javascript e css. Criaremos um widget que irá incorporar as funções do plugin jcarousel. Primeiramente, baixe o plugin, salve-o em alguma pasta e descompacte, caso tenha baixado como .zip.

Lembre-se de onde salvou e descompactou o plugin, logo iremos utilizar alguns de seus arquivos.

Agora, crie uma pasta chamada “jcarousel” dentro da pasta “protected\extensions” de sua aplicação.
Nessa pasta, crie duas subpastas: “css” e “js”.

Voltando à pasta onde salvou o jcarousel, entre na subpasta “examples\basic”. Vamos utilizar esse exemplo em nosso plugin. Antes de mais nada, abra o arquivo index.html em seu navegador, e veja o plugin funcionando:

jcarousel - exemplo básico

jcarousel – exemplo básico

Iremos reproduzir esse exemplo (com algumas diferenças no css) em nosso widget. Copie então, o arquivo “jcarousel.basic.js” para a pasta “protected\extensions\jcarousel\js” de sua aplicação.
Copie também o arquivo “jcarousel.basic.css”, mas para a pasta “protected\extensions\jcarousel\css”.

O arquivo “jcarousel.basic.js” (abra-o para ver) contém o código de manipulação do plugin. O jcarousel.basic.css contém as personalizações dos estilos do carousel (como por exemplo, os links de navegação).

Falta copiar o javascript do plugin. Para isso, copie o arquivo “jquery.jcarousel.js” que está na pasta “dist” do plugin e cole-o na pasta “protected\extensions\jcarousel\js”.

Agora procure pela pasta “examples\_shared\css”, também nos arquivos do plugin. Copie o arquivo “style.css” para a pasta “protected\extensions\jcarousel\css”.

Copie então a pasta “_shared\img” para a pasta “images” de seu projeto. Renomeie a pasta “img” para “carousel”. Essas são as imagens que serão exibidas no carrossel, Caso queira, você poderá trocá-las por outras depois.

Com todos os arquivos necessários copiados, iremos agora criar nosso widget. Dentro da pasta “protected\extensions\jcarousel”, crie um arquivo chamado “jcarousel.php”. Nela, cole o seguinte código:

class jcarousel extends CWidget
{
	public function run()
	{

		$css = dirname(__FILE__).DIRECTORY_SEPARATOR.'css'.DIRECTORY_SEPARATOR.'jcarousel.basic.css';

		$css2 = dirname(__FILE__).DIRECTORY_SEPARATOR.'css'.DIRECTORY_SEPARATOR.'style.css';

		$jsBasic = dirname(__FILE__).DIRECTORY_SEPARATOR.'js'.DIRECTORY_SEPARATOR.'jcarousel.basic.js';
		$jsCarousel = dirname(__FILE__).DIRECTORY_SEPARATOR.'js'.DIRECTORY_SEPARATOR.'jquery.jcarousel.min.js';

		$cssPub = Yii::app()->getAssetManager()->publish($css);

		$css2Pub = Yii::app()->getAssetManager()->publish($css2);

		$jsBasicPub = Yii::app()->getAssetManager()->publish($jsBasic);

		$jsCarouselPub = Yii::app()->getAssetManager()->publish($jsCarousel);

		$cs=Yii::app()->clientScript;

		$cs->registerCssFile($cssPub);
		$cs->registerCssFile($css2Pub);
		$cs->registerScriptFile($jsBasicPub);
		$cs->registerScriptFile($jsCarouselPub);

		$cs->registerCoreScript('jquery');
	}

}

Como você já deve estar ciente, a pasta protected (e suas subpastas) são inacessíveis pelo navegador. Somente o código do Yii tem acesso a esse conteúdo. Isso vale também para as nossas extensões. Se chamarmos os scripts e css diretamente da nossa pasta, eles não funcionarão, pois o .htacess (ou o web.config, no caso do windows) protege essas pastas do acesso direto. Quando quisermos disponibilizar algum desses arquivos para o acesso direto pelo navegador, precisamos copiá-los para a nossa pasta assets. Para isso, utilizaremos a classe CAssetManager.

Voltando ao nosso código, as linhas 8-13 gerarão os caminhos físicos dos arquivos protegidos que queremos disponibilizar.

Nas linhas 15-21 utilizamos o método Publish() da classe CAssetManager. Esse método exige apenas um parâmetro, que é o caminho para o arquivo ou pasta que você deseja publicar (para saber os outros parâmetros, consulte a documentação). Ele copia nossos arquivos para a pasta assets e retorna um link, para que possamos indicar ao navegador onde achar tais arquivos.

No nosso caso, como estamos usando javascript e css, usaremos esses links com a classe CClientScript. Essa classe disponibiliza vários métodos, para que possamos gerenciar e embutir scripts e folhas de estilo em nossas aplicações.

Em nosso código, a linha 23 gera uma referência à classe CClientScript de nossa aplicação.
As linhas 25-28 incluem os scripts/css na página que usará nosso widget.
A linha 30 inclui a chamada para o jquery (se ele já não tiver sido chamado anteriormente).

Hora de utilizar nosso widget. Em uma view qualquer, cole o seguinte código:

<?php
$this->beginWidget('ext.jcarousel.jcarousel');
?>
	<div class="wrapper">
            <h1>jcarousel</h1>

            <p>Exemplo básico através de um widget do Yii.</p>

            <div class="jcarousel-wrapper">
                <div class="jcarousel">
                    <ul>
                        <li><img src="images/carousel/img1.jpg" width="600" height="400" alt=""></li>
                        <li><img src="images/carousel/img2.jpg" width="600" height="400" alt=""></li>
                        <li><img src="images/carousel/img3.jpg" width="600" height="400" alt=""></li>
                        <li><img src="images/carousel/img4.jpg" width="600" height="400" alt=""></li>
                        <li><img src="images/carousel/img5.jpg" width="600" height="400" alt=""></li>
                        <li><img src="images/carousel/img6.jpg" width="600" height="400" alt=""></li>
                    </ul>
                </div>

                <p class="photo-credits">
                    Photos by <a href="http://www.mw-fotografie.de">Marc Wiegelmann</a>
                </p>

                <a href="#" class="jcarousel-control-prev">&lsaquo;</a>
                <a href="#" class="jcarousel-control-next">&rsaquo;</a>

                <p class="jcarousel-pagination">

                </p>
            </div>
        </div>
<?php
$this->endWidget();
?>

Aqui, na linha 2, inicializamos nosso widget.
Nas linhas 4-32, colocamos o código html que o plugin jcarousel irá utilizar para gerar nosso carrossel.
A linha 34 fecha o widget. Poderíamos simplesmente ter chamado nosso widget da mesma forma que no exemplo anterior, utilizando somente “$this->widget(‘ext.jcarousel.jcarousel’);” e deixando o html das imagens em uma parte qualquer. Mas acho uma boa prática fazer dessa forma, pois isso deixará nosso código mais organizado, pois saberemos que entre o beginWidget e o endWidget está o conteúdo que será tratado pelo widget.

Execute então a action que chama essa view:
widget - jcarousel

Veja que o widget está funcionando, exatamente igual ao exemplo do próprio jcarousel.
Veja também como ficou o código gerado com a chamada para o css e os scripts. Exiba o código fonte da página e veja as linhas 17-21 (ou linhas próximas, pode variar):
script_gerado

Fácil e prático, não?

Agora, gostaria de propor alguns exercícios baseados no que você aprendeu nos dois últimos artigos:

  1. melhore um pouco o código da classe jcarousel.php. Ao invés de a cada linha (15-21) ficar chamando o Asset Manager, chame-o apenas uma vez e utilize os métodos apropriados para publicar os scripts.
  2. coloque outras imagens no código da view, para que você veja as diferenças.
  3. Lembra-se que na parte 1 havia um parâmetro que indicava a id do vídeo que seria exibido? Faça algo parecido. Acrescente parâmetros ao plugin, onde o usuário poderá passar, por exemplo, qual o nome das classes de “next” e “previous” do carrossel. Tente também customizar outros parâmetros do jcarousel (veja a documentação) através de parâmetros passados pelo usuário do widget. Dica: para isso, você precisará copiar o conteúdo do arquivo “jcarousel.basic.js” e editá-lo no próprio código do widget. Utilize a classe CclientScript para isso.
Gustavo disse:
5

Show de bola esse tutorial cara!!