Criando widgets no WordPress e adicionando opções
No WordPress, o sistema de widgets permite que usuários comuns ativem
funcionalidades no site sem precisar, necessariamente, entender HTML,
CSS, PHP, etc. Mas, para isso, esses usuários precisam que
desenvolvedores se dediquem um pouco mais para tornar seus produtos
(plugins, temas, etc) aptos a trabalhar dessa forma.
Para adicionar um widget, basta criar uma uma função e informar para
o WP que aquela função deve ser tratada como um widget. Isso é feito da
seguinte forma:
register_sidebar_widget('Nome do Widget', 'sua_funcao', 'sua_classe');É tão simples quanto parece, o ‘Nome do Widget’ é o identificador do
widget, ‘sua_funcao’ é a função que deve ser chamada quando esse widget
estiver ativo e ‘sua_classe’ é opcional e se refere ao nome da classe
CSS que deve ser inserida nesse widget.
Para que o seu widget se adeque ao tema é importante lembrar sempre
de usar o modelo de widget definido no próprio tema para conter o
conteúdo de sua função. Esse modelo é sempre embutido em forma de
argumento na sua função, você só precisa usá-lo. Um exemplo vale mais
do que mil palavras, então vejamos como ficaria:
sua_funcao($args)<br />{<br /> print $args['before_widget'];<br /> print $args['before_title'] . "Nome do Widget" . $args['after_title'];<br /> print "conteúdo de seu widget";<br /> print $args['after_widget'];<br />}Agora que você sabe que é fácil, não tem desculpa para não
utiliza-lá em seus plugins. Assim, os usuários não precisarão fazer
edições no template para usufruir dos benefícios de seus plugins, além
de tornar mais simples o seu controle.
Juntando o que você aprendeu até agora sobre criar um plugin, mais o que você acabou de aprender sobre criação de widget e um pouco de
criatividade, já é possível fazer algumas coisas interessantes. Que tal
um plugin que mostre no sidebar os posts mais quentes? Veja:
<?php<br />/*<br />Plugin Name: Posts mais quentes<br />Description: Lista posts mais comentados<br />Version: 0.1<br />Author: Marcelo Mesquita<br />Author URI: http://www.marcelomesquita.com/<br />*/<br /><br />// Posts Mais Quentes<br />function posts_mais_quentes($args)<br />{<br /> global $wpdb;<br /><br /> // Recuperando os posts<br /> $hot_posts = $wpdb->get_results("SELECT ID, post_title, comment_count FROM {$wpdb->posts} ORDER BY comment_count DESC LIMIT 5");<br /><br /> // Usando o modelo de widgets do tema<br /> print $args['before_widget'];<br /> print $args['before_title'] . "Mais Quentes" . $args['after_title'];<br /><br /> print "<ul>";<br /><br /> // Listando os posts mais quentes<br /> foreach($hot_posts as $hot_post)<br /> print "<li><a href='" . get_permalink($hot_post->ID) . "'>{$hot_post->post_title} ({$hot_post->comment_count})</a></li>";<br /><br /> print "</ul>";<br /><br /> print $args['after_widget'];<br />}<br /><br />// Ativa o sidebar<br />function posts_mais_quentes_widgets() {<br /> register_sidebar_widget('Posts Mais Quentes', 'posts_mais_quentes');<br />}<br /><br />// Carregar o widget<br />add_action('widgets_init', 'posts_mais_quentes_widgets');<br /><br />?>Agora é só ativar o plugin e adicionar o widget ao sidebar para vê-lo funcionando. Bem simples!
Após criar o widget,
o próximo passo é adicionar algumas opções a ele, tornando-o mais
flexível para o usuário final. Vamos continuar usando esse exemplo do plugin de
posts mais quentes. Digamos que você tenha definido a quantidade de
cinco posts para serem apresentados, mas um usuário queira mostrar
apenas três. Para essas situações utilizamos a seguinte função:
register_widget_control('Nome do Widget', 'sua_funcao_de_configuracao', 'largura', 'altura')
Formulário de configuração do Widget
Essa função permite configurar as opções de seu widget onde ‘Nome do
Widget’ é, claro, o nome do widget que se deseja configurar (o mesmo que informou
em ‘register_sidebar_widget’), ‘sua_funcao_de_configuracao’ é a função
que deve ser chamada para configurar o plugin e ‘largura’ e ‘altura’
são opcionais e se referem ao tamanho do formulário de configuração.
A sua função de configuração deve possuir um formulário com os
campos de configuração e uma rotina para salvar esses dados no banco. O
seu formulário não deve conter as tags ‘form’ nem ‘submit’, pois eles
são acrescentados automaticamente pelo WordPress de forma a englobar
todos os widgets.
Vamos ver uma forma fácil de implementar essa configuração:
function configurar_posts_mais_quentes()<br />{<br /> // Inicializa as variáveis necessárias<br /> $options = array();<br /><br /> // Salvando as opções<br /> if($_POST['salvar_posts_mais_quentes'])<br /> {<br /> $opcoes['quantidade'] = (int) $_POST['quantidade_de_posts_mais_quentes'];<br /><br /> // Valor padrão, caso nada tenha sido informado<br /> if(empty($opcoes['quantidade'])) $opcoes['quantidade'] = 5;<br /><br /> update_option('posts_mais_quentes', $opcoes);<br /> }<br /><br /> // Carregar as opções desse widget<br /> $opcoes = get_option('posts_mais_quentes');<br /><br /> // Formulário<br /> ?><br /> <input type="hidden" name="salvar_posts_mais_quentes" value="1" /><br /><br /> <p><br /> <label for="quantidade_de_posts_mais_quentes">Quantidade:</label><br /> <input type="text" name="quantidade_de_posts_mais_quentes" maxlength="2" value="<?php print $opcoes['quantidade']; ?>" class="widefat" /><br /> </p><br /> <?php<br />}Explicando: começando na linha 18 ($opcoes =
get_option(‘posts_mais_quentes’)) carrega as opções desse widget do
banco. Notem que usei a tabela ‘options’ do banco do WordPress para
salvar as opções do plugins.
Agora vamos para o início do formulário na linha 22, onde adiciono
um campo oculto (<input type=”hidden”
name=”salvar_posts_mais_quentes” value=”1? />) apenas para ter
controle quando o formulário for enviado. Também adicionei um campo de
texto na linha 26 (<input type=”text”
name=”quantidade_de_posts_mais_quentes” maxlength=”2? value=”<?php
print $opcoes[‘quantidade’]; ?>” class=”widefat” />) para que o
usuário possa informar a quantidade de posts que deve aparecer em seu
widget.
Voltando para a linha 7, analiso se o formulário foi enviado,
checando se o campo oculto foi informado, então valido o dado recebido
do formulário ($opcoes[‘quantidade’] = (int)
$_POST[‘quantidade_de_posts_mais_quentes’]) e, finalmente, salvo as
informações no banco (update_option(‘posts_mais_quentes’, $opcoes)).
Notem também que as informações desse widget foram salvas como array,
assim é possível armazenar todas as configurações em um único local,
poupando quantidade de acesso ao banco e organizando os dados.
Tentei montar esse formulário da forma mais simples possível, além
disso coloquei alguns comentários para facilitar o entendimento.
Mas não é só isso. Depois de salvar as configurações desse widget ainda falta carregá-las na hora de montar o widget:
function posts_mais_quentes($args)<br />{<br /> global $wpdb;<br /><br /> // Carregar as opções desse widget<br /> $opcoes = get_option('posts_mais_quentes');<br /><br /> // Recuperando os posts<br /> $hot_posts = $wpdb->get_results("SELECT ID, post_title, comment_count FROM {$wpdb->posts} ORDER BY comment_count DESC LIMIT {$opcoes['quantidade']}");<br /><br /> // Usando o modelo de widgets do tema<br /> print $args['before_widget'];<br /> print $args['before_title'] . "Mais Quentes" . $args['after_title'];<br /> print "<ul>";<br /><br /> // Listando os posts mais quentes<br /> foreach($hot_posts as $hot_post)<br /> print "<li><a href='" . get_permalink($hot_post->ID) . "'>{$hot_post->post_title} ({$hot_post->comment_count})</a></li>";<br /><br /> print "</ul>";<br /> print $args['after_widget'];<br />}Essa função é a mesma que falei acima,
com duas pequenas alterações. Uma na linha 6, onde carrego as
configurações salvas, e na linha 9, onde uso a quantidade de posts
informada pelo usuário para limitar a consulta (LIMIT
{$opcoes[‘quantidade’]}).
É isso – crie novas possibilidades para seus widgets, os usuários
finais possuem sempre gostos diversos, simplifique a vida deles. Abaixo
coloco o código completo desse estudo com uma opção a mais para a
escolha do título do widget.
<?php<br />/*<br />Plugin Name: Posts mais quentes<br />Description: Lista posts mais comentados<br />Version: 0.2<br />Author: Marcelo Mesquita<br />Author URI: http://www.marcelomesquita.com/<br />*/<br /><br />// Posts Mais Quentes<br />function posts_mais_quentes($args)<br />{<br /> global $wpdb;<br /><br /> // Carregar as opções desse widget<br /> $opcoes = get_option('posts_mais_quentes');<br /><br /> // Valor padrão, caso nada tenha sido informado<br /> if(empty($opcoes['quantidade'])) $opcoes['quantidade'] = "5";<br /><br /> // Recuperando os posts<br /> $hot_posts = $wpdb->get_results("SELECT ID, post_title, comment_count FROM {$wpdb->posts} ORDER BY comment_count DESC LIMIT {$opcoes['quantidade']}");<br /><br /> // Usando o modelo de widgets do tema<br /> print $args['before_widget'];<br /> print $args['before_title'] . $opcoes['titulo'] . $args['after_title'];<br /> print "<ul>";<br /><br /> // Listando os posts mais quentes<br /> foreach($hot_posts as $hot_post)<br /> print "<li><a href='" . get_permalink($hot_post->ID) . "'>{$hot_post->post_title} ({$hot_post->comment_count})</a></li>";<br /><br /> print "</ul>";<br /> print $args['after_widget'];<br />}<br /><br />// Configurações dos Posts Mais Quentes<br />function configurar_posts_mais_quentes()<br />{<br /> // Inicializa as variáveis necessárias<br /> $opcoes = array();<br /><br /> // Salvando as opções<br /> if($_POST['salvar_posts_mais_quentes'])<br /> {<br /> $opcoes['titulo'] = $_POST['titulo_dos_posts_mais_quentes'];<br /> $opcoes['quantidade'] = (int) $_POST['quantidade_de_posts_mais_quentes'];<br /><br /> // Valor padrão, caso nada tenha sido informado<br /> if(empty($opcoes['quantidade'])) $opcoes['quantidade'] = "5";<br /><br /> update_option('posts_mais_quentes', $opcoes);<br /> }<br /><br /> // Carregar as opções desse widget<br /> $opcoes = get_option('posts_mais_quentes');<br /><br /> // Formulário<br /> ?><br /> <input type="hidden" name="salvar_posts_mais_quentes" value="1" /><br /><br /> <p><br /> <label for="titulo_dos_posts_mais_quentes">Título:</label><br /> <input type="text" name="titulo_dos_posts_mais_quentes" maxlength="26" value="<?php print $opcoes['titulo']; ?>" class="widefat" /><br /> <label for="quantidade_de_posts_mais_quentes">Quantidade:</label><br /> <input type="text" name="quantidade_de_posts_mais_quentes" maxlength="2" value="<?php print $opcoes['quantidade']; ?>" class="widefat" /><br /> </p><br /> <?php<br />}<br /><br />// Ativar o widget<br />function posts_mais_quentes_widgets()<br />{<br /> // Adicionar o widget<br /> register_sidebar_widget('Posts Mais Quentes', 'posts_mais_quentes');<br /><br /> // Adicionar o controle ao widget<br /> register_widget_control('Posts Mais Quentes', 'configurar_posts_mais_quentes');<br />}<br /><br />// Carregar o widget<br />add_action('widgets_init', 'posts_mais_quentes_widgets');<br />?>Nos próximos artigos falaremos sobre plugins e bancos de dados e a criação de widgets para a versão 2.8 do WordPress.
Boa sorte!
é formado em Desenvolvimento de Sistemas para a Web e há mais de cinco anos trabalha com desenvolvimento de sites. Nos últimos dois anos tem seu foco no WordPress: montagem de temas, desenvolvimento de plugins, scripts, widgets e performance.
