Então você quer saber como criar o seu próprio Widget para WordPress? Na verdade não é algo tão dificil assim e pode ser rapidamente implementado em seu blog através do tão famoso ficheiro functions.php que se encontra na pasta de seu tema. Para o ajudar a explicar, criámos um Widget que conta os números das suas redes sociais igual ao que temos aqui no Escola WordPress e que pode ser instalado em forma de plugin. O link para o download encontra-se no fundo deste artigo.

Depois de instalado o Widget, é este o seu aspecto na sidebar:

NOTA: Tenha especial atenção ao facto de o plugin ser responsivo, ou seja, se a barra lateral do seu template for mais larga, todos os contadores irão aparecer lado-a-lado como acontece aqui na Escola WordPress. Se a sua barra lateral for ainda mais pequena, ele colocará todos os contadores em formato vertical, e assim sucessivamente para as diferentes barras laterais de blogs, não sendo necessário você fazer qualquer tipo de alteração!

Gostou? Então vamos lá seguir e tentar aprender como fazer este e outros Widgets para nós e podermos até compartilhar com outros. Quero deixar primeiro uma salva bastante clara: visto termos que lidar com código PHP e HTML e o foco deste tutorial é a de criação de Widgets em WordPress, pressupomos que:

  • Você já tem alguns conhecimentos básicos de HTML e PHP ou pelo menos já tentou fazer um script. Não está no escopo deste tutorial explicar o que é a função echo ou como se inicia um objecto de uma classe. Para isso existem vários recursos na internet, sendo um deles o W3Schools que é um portal onde você pode aprender tudo sobre programação para a internet inclusive PHP, HTML, SQL e CSS.
  • Você sabe o que é e onde se encontra o ficheiro functions.php do seu tema e pelo menos já o abriu e editou alguma coisa nele.

Caso você não saiba sequer o que é um Widget, a secção seguinte é capaz de lhe dar umas luzes.

O QUE É UM WIDGET

Para quem não sabe, um Widget é uma porção de código que segue determinadas regras de programação, usando a API do WordPress. Essa estrutura programática, possibilita que, quando carregada pelo WordPress, se crie um bloco de funcionalidades que possam ser usadas ou não pelo utilizador do WordPress no seu blog através da ativação desse mesmo Widget numa determinada Sidebar.

Não me vou alongar muito acerca da estrutura dos Widgets uma vez que este não é o foco deste tutorial, no entanto você pode procurar na internet. Existe muito material sobre o assunto e não é dificil encontrar alguma coisa.

OS BENEFÍCIOS DE UM WIDGET

  • Pode ser usado em qualquer Sidebar quantas vezes vocês quiser
  • É de fácil organização, activação e remoção, uma vez que existe uma interface visual bastante simples e intuitiva que pode ser usado por qualquer usuário expert ou leigo
  • Pode ser usado mesmo por quem não sabe nada de programação
  • Tem várias opções para se customizar o Widget à nossa imagem

COMO CRIAR O WIDGET

Vamos então avançar com a explicação do código. Primeiro que tudo, sugiro que faça o download do plugin que se encontra no rodapé deste tutorial e que dê uma olhada e o mantenha aberto enquanto lê este artigo.

Um Widget começa sempre por extender a classe WP_Widget que é nativa do WordPress e responsável por todo o processo de registo, criação, display e gestão do conteúdos de todos os Widgets ativos e inativos de um blog. Assim, quando criamos o nosso Widget, criamos uma classe que extende esta classe “pai”, passando a ser herdeira por assim dizer, de todos estes métodos, propriedades e processos inerentes ao Widget.

Explicado o nosso processo, passaremos a desvendar este nosso código.

Este é um Widget básico inicial com o estender da classe WP_Widget mas que ainda não é usável:

class Widget_EwpSocialCounter extends WP_Widget {

}

Chamámos à nossa classe Widget_EwpSocialCounter e é assim que o nosso Widget irá ser reconhecido internamente no WordPress. No entanto, iremos continuar-lhe a chamar simpesmente de Widget Social que é mais curto e conciso. :)

Iniciada a nossa classe, é necessário agora fornecer-lhe mais algumas informações, uma vez que assim, deste modo o Widget não irá fazer nada pois encontra-se vazio, nem sequer tem um nome para quando for visualizado na página de Administração dos Widgets. Para que isso aconteça temos que adicionar-lhe o método com o mesmo nome da nossa classe do Widget Social colocando o código do seguinte function dentro da classe:

class Widget_EwpSocialCounter extends WP_Widget {

	function Widget_EwpSocialCounter() {
		parent::WP_Widget( false, 'EWP Social Counter' );

	}

}

Esta é sempre a primeira função a ser executada quando o WordPress carrega o Widget. O que esta função faz é simplesmente dizer à classe “pai” ou parent – classe WP_Widget – que um novo Widget vai iniciar, passando-lhe dois parâmetros:

  • o segundo argumento é o título que queremos que seja visualizado no painel de Widgets na administração. No nosso caso iremos usar o título EWP Social Counter, você pode usar o seu. Tenha sempre em conta que um título esclarecedor do Widget é sempre uma mais valia.

Com isto, já poderia ativa o seu seu Widget e ele seria visível no painel de Widgets da administração, porém não teria nenhuma funcionalidade. É isso que iremos criar agora:

class Widget_EwpSocialCounter extends WP_Widget {

	function Widget_EwpSocialCounter() {
		parent::WP_Widget( false, 'EWP Social Counter' );

	}

	/**
	 * Exibe o Conteúdo do Widget na sidebar do Blog
	 */
	function widget($args, $instance) {
		extract( $args );
		echo $before_widget;

                echo $before_title;
                echo $title;
                echo $after_title;
		echo $after_widget;

	}

	/**
	 * Quando clica em "Guardar" no Widget esta função é responsável por fazer esse procedimento
	 */
	function update($new_instance, $old_instance) {
		return $new_instance;

	}

	/**
	 * Esta função exisbe todos os controladores do Widget na administração
	 */
	function form($instance) {

	}

}

Estes quatro métodos são as únicas expressões da classe necessárias e suficientes para a maior parte dos Widgets. Vamos desvendar qual o papel de cada uma destas funções nas funcionalidades do nosso novo Widget.

FUNÇÃO FORM() – O CONTROLO DO WIDGET

A função form() exibe na interface de administração o controlo do Widget que é nada mais nada menos que um formulário com vários campos com as opções do nosso Widget. Estes campos pedem ao usuário da administração alguns elementos para serem exisbidos ou levarem a um correcto funcionamento do Widget.

Por exemplo, é natural quase todos os Widgets incluirem um campo para se acrescentar um título. Com o seguinte código HTML:

<p>
	<label for="<?php echo $this->get_field_id("titulo"); ?>">
		Título:
		<input class="widefat" id="<?php echo $this->get_field_id("titulo"); ?>" name="<?php echo $this->get_field_name("titulo"); ?>" type="text" value="<?php echo esc_attr( (string) isset( $instance["titulo"] ) ? $instance["titulo"] : '' ); ?>" />
	</label>
</p>

Nesta função form(), será renderizado dentro do controlo do Widget um input de texto. É aqui deixar o nosso Widget com mais ou menos capacidades de customização por isso é sempre importante estudar o que se deve pedir ao usuário ou não.

Os métodos PHP get_field_id() e get_field_name() retornam valores para cada um destes campos registados e devem ser usados ao invés de atribuir valores concretos a cada atributo, pois o que estas funções fazem é garantir que os nomes destes campos são sempre diferentes uns dos outros inclusivé das instancias do mesmo Widget que foram iniciadas. Uma vez que os Widgets podem ser usados mais do que uma vez em cada sidebar, estas funções evitam que os campos tenham nomes iguais, podendo assim as opções ficassem mal configuradas.

No nosso Widget Social vamos ter a seguinte função form():

function form($instance) {

?>
<p>
	<label for="<?php echo $this->get_field_id("twitter"); ?>">
		Nome de Twitter:
		<input class="widefat" id="<?php echo $this->get_field_id("twitter"); ?>" name="<?php echo $this->get_field_name("twitter"); ?>" type="text" value="<?php echo esc_attr( (string) isset( $instance["twitter"] ) ? $instance["twitter"] : '' ); ?>" />
	</label>
	<span class="description">O nome do Twitter encontra-se no final da URL: </span><code>http://twitter.com/nome-de-utilizador</code>
</p>

<p>
	<label for="<?php echo $this->get_field_id("facebook"); ?>">
		ID do Facebook:
	</label>
	<input class="widefat" id="<?php echo $this->get_field_id("facebook"); ?>" name="<?php echo $this->get_field_name("facebook"); ?>" type="text" value="<?php echo esc_attr( (string) isset( $instance["facebook"] ) ? $instance["facebook"] : '' ); ?>" />
	<span class="description">Parâmetro id na URL do Facebook da sua página: </span><code>https://www.facebook.com/pages/edit/?id=id-da-página</code>
</p>

<p>
	<label for="<?php echo $this->get_field_id("feedburner"); ?>">
		Utilizador do FeedBurner:
	</label>
	<input class="widefat" id="<?php echo $this->get_field_id("feedburner"); ?>" name="<?php echo $this->get_field_name("feedburner"); ?>" type="text" value="<?php echo esc_attr( (string) isset( $instance["feedburner"] ) ? $instance["feedburner"] : '' ); ?>" />
	<span class="description">Nome do utilizador encontra-se no fim da URL: </span><code>http://feeds.feedburner.com/nome-de-utilizador</code>
</p>
<?php

}

Penso não seu necessário explicar cada pedaço deste código, uma vez que é uma cópia do que foi anteriormente dito. Apenas criámos mais campos para configuração.

FUNÇÃO UPDATE() – VALIDAÇÕES E SALVAR DOS DADOS:

Este método realiza apenas uma tarefa. Ela faz a atualização dos novos dados introduzidos no formulário de controlo, recebendo-os sobre forma de parâmetro e retornando-os de seguida. É aqui que é possível fazer algumas validações ou cálculos dos campos. Não existe muito mais a falar sobre esta função.

FUNÇÃO WIDGET() – A PARTE VISÍVEL DO WIDGET:

Este método imprime o Widget do lado do blog. É portanto a parte central do Widget aquela que os seus usuários vêem e aquele que recebe o propósito do Widget existir. Além de entrar aqui HTML também é preciso ir buscar os valores fornecidos ao controlo do Widget. Esta função pode ser um pouco confusa por vezes, mas o necessário aqui é você entender a lógica do Widget, principalmente os seus argumentos:

function widget($args, $instance) {
	extract( $args );
	echo $before_widget;

        echo $before_title;
        echo $instance['title'];
        echo $after_title;
	echo $after_widget;

}

Esta função aceita dois argumentos:

  • $args – é um conjunto de variáveis por defeito que ajudam na formatação do Widget. Elas são as variáveis passadas à função register_sidebar() que cria a sidebar no seu tema. São elas $before_widget, $after_widget, $before_title, $after_title e, como o próprio nome indica, contém o HTML dos argumentos passados à função register_sidebar() que ão aparecer nessas posições.
  • $instance – é o conjunto de valores dos campos fornecidos ao formulário do controlo do Widget que nós criámos.

A função nativa do PHP extract(), aceita um array de variáveis e define-as no corpo global da função. Ou seja, $args[‘before_widget’] passa a estar disponível como variável $before_widget e por aí fora. Isto não é necesário, é apenas uma forma mais confortável de trabalhar, com variáveis em vez de com um array de variáveis.

Seguidamente vamos imprimir, como é óbvio cada uma destas variáveis para podermos formatar o Widget de acordo com o tema. Primeiro usamos as variáveis $before_widget e $after_widget no inicio de no fim do Widget respetivamente. Tudo o resto fica entre estas duas variáveis, nomeadamente o título se houver. No nosso caso, o título não é importante e não vai ser usado.

A FUNÇÃO WIDGET() – PARTE 1: RECEÇÃO DOS DADOS NECESSÁRIOS

Para podermos divulgar os nossos números das redes sociais, temos que ir buscá-los à fonte. Para isso usamos os webservices implementados por cada uma das redes sociais, chamada de API (Application Programming Interface ou Interface de Programação de Aplicativos). A Wikipedia tem um óptimo artigo acerca do que é uma API. É o que iremos fazer na primeira parte desta função:

function widget($args, $instance) {
	global $wpdb;

	extract( $args );

	$get_feedburner = wp_remote_get( 'https://feedburner.google.com/api/awareness/1.0/GetFeedData?uri='.$instance['feedburner'] );
	$get_twitter = wp_remote_get( 'http://twitter.com/users/show.xml?screen_name='.$instance['twitter'] );
	$get_facebook = wp_remote_get( 'http://api.facebook.com/restserver.php?method=facebook.fql.query&query=SELECT%20fan_count%20FROM%20page%20WHERE%20page_id='.$instance['facebook'] );

	$xml = new SimpleXmlElement( $get_feedburner['body'], LIBXML_NOCDATA );
	$rss_counter = $xml->feed->entry['circulation'];

	$xml = new SimpleXmlElement( $get_twitter['body'], LIBXML_NOCDATA );
	$twitter_counter = $xml->followers_count;

	$xml = new SimpleXmlElement( $get_facebook['body'], LIBXML_NOCDATA );
	$fb_counter = $xml->page->fan_count;

	$comments_counter = $wpdb->get_var( "SELECT COUNT(*) FROM $wpdb->comments WHERE comment_approved = '1'" );

	echo $before_widget;

Esta é a parte do PHP, a responsável por ir buscar os valores que nós pretendemos a cada uma das APIs das redes sociais. Você pode colocar aqui a sua rede social preferida se pretender. Hoje em dia quae todas as redes sociais fornecem um webservice ou uma API Restfull. Cabe a você descobrir qual o URL para a API da sua rede social preferída e replicar cada uma destas partes. Existe muita informação na internet sobre as APIs de muitas das redes sociais, basta procurar.

Voltando ao nosso código:

Primeiro globalizamos o objecto $wpdb que é um wrapper criado pelo WordPress para acesso à base de dados. Este objecto é responsável por todos os processos e chamadas SQL à base de dados MySQL. Precisamos deste objecto para podermos buscar o número total de comentários no blog através de uma chamada SQL.

Segundo, precisamos de acessar aos APIs do Twitter, Facebook e Feedburner para podermos receber o número de Seguidores, Fans e Assinantes respectivamente. Para isso usamos a função nativa do WordPress wp_remote_get(). Esta função é um wrapper para várias funções e procedimentos de manipulação de ficheiros usando o protocolo HTTP, nomeadamente Curl.Então com esta função aquilo que vamos fazer é receber o retorno do nosso API em formato XML numa variável.

É de notar que passamos a cada uma das URL os valores armazenados no controlo do Widget através do array $instance. Para ir buscar o valor do Twitter basta passar $instance[‘twitter’] para a URL uma vez que registamos o nosso campo no controlo do Widget com este índice e por aí fora para cada uma das URLs.

Tendo todo o retorno às APIs do nosso lado, iremos ler o XML retornado. Para isso usamos a nova classe SimpleXmlElement() que é nativa do PHP 5.2 por uma questão de facilidade no uso e rapidez de resposta. O que esta classe faz é o seguinte: criamos um objecto passando o conteúdo em XML. Ela converte o XML numa sucessão de objectos que podemos usar mais facilmente no nosso código.

A esta classe passamos dois parâmetros: o corpo do XML retornado pela API e a constante LIBXML_NOCDATA. Não está no escopo deste tutorial explicar este último parâmetro, para isso recomendo dar uma olhadela no W3Schools.

A FUNÇÃO WIDGET() – PARTE 2: APRESENTAÇÃO DOS DADOS EM HTML

Depois de termos todos os valores arrumadinhos em variáveis, temos que os imprimir no Widget através de PHP porém temos que os arrumar em HTML e CSS e dar-lhes um ar mais bonito com icones que descrevem visualmente o que cada um dos números quer dizer. Eis o nosso HTML:

<div class="ewp-social-counter-icon ewp-social-counter-rss">
	<a href="http://feeds.feedburner.com/<?php echo $instance['feedburner']; ?>" target="_blank">
		<img src="<?php echo plugins_url( 'user_rss_32.png', __FILE__ ); ?>" alt="Assinantes no RSS" />
	</a>
	<br />
	<small>Assinantes</small>
	<h3><?php echo $rss_counter; ?></h3>
</div>

<div class="ewp-social-counter-icon ewp-social-counter-twitter">
	<a href="http://www.twitter.com/<?php echo $instance['twitter']; ?>" target="_blank">
		<img src="<?php echo plugins_url( 'user_twitter_32.png', __FILE__ ); ?>" alt="Seguidores no Twitter" />
	</a>
	<br />
	<small>Seguidores</small>
	<h3><?php echo $twitter_counter; ?></h3>
</div>

<div class="ewp-social-counter-icon ewp-social-counter-facebook">
	<a href="http://www.facebook.com/<?php echo $instance['facebook']; ?>" target="_blank">
		<img src="<?php echo plugins_url( 'user_fb_32.png', __FILE__ ); ?>" alt="Fãs do Facebook" />
	</a>
	<br />
	<small>Fãs</small>
	<h3><?php echo $fb_counter; ?></h3>
</div>

<div class="ewp-social-counter-icon ewp-social-counter-comments">
	<img src="<?php echo plugins_url( 'users_32.png', __FILE__ ); ?>" alt="Comentários" />
	<br />
	<small>Comentários</small>
	<h3><?php echo $comments_counter; ?></h3>
</div>

Uma vez que todas as div são iguais, iremos explicar apenas uma das porções do código. Parto do princípio que você já entende e conhece cada uma das tags e seus atributos em HTML. Sendo assim o que irei explicar é o uso da função plugins_url() nativa do WordPress.

Esta função retorna o URL relativamente ao seu blog para o ficheiro dado no seu primeiro parâmetro, a partir da localização do ficheiro do segundo parâmetro, ou seja, neste caso, usando a constante __FILE__ estamos a dizer à função para usar o ficheiro atual, localizado em http://seu-dominio/wp-content/themes/seu-tema/functions.php como selector do caminho, procurando assim o ficheiro em http://seu-dominio/wp-content/themes/seu-tema/.

É neste espaço que você deve dar asas à sua imaginação e tentar fazer de seu Widget o melhor que conseguir.

DOWNLOAD DO PLUGIN GRÁTIS!

Como é normal disponibilizamos aqui o Widget em forma de plugin, já pronto para se poder instalar direitinho. Após a instalação terá que ir a “Apresentação” > “Widgets”, escolher o Widget “EWP Social Counter” e configurá-lo com o nome de utilizador do Twitter, o id da página de fans do Facebook e o seu nome do FeedBurner.

{filelink=1}

Para quem segue este tutorial: recomendo uma análise de como o Widget está implementado.

Para quem usa este plugin: partilhe e divulgue as suas redes sociais com os seus amigos ajudando a divulgar a Escola WordPress também! Não retire os créditos do Plugin por favor!!

Espero que este artigo o tenha ajudado a dar os primeiros passos na criação do seu primeiro Widget. Sugestões? Deixe o seu comentário em baixo. Criou um Widget a partir deste artigo? Divulgue-o aqui!

Um abraço!