Como deixei claro no meu último post, recentemente resolvi vender alguns sites com administração via WP - o que me exigiu esforço para achar alguma informação sobre como criar temas e plugins para WordPress. Meu inglês é péssimo e ler um artigo nesse idioma pode ser uma tarefa cansativa e demorada (e às vezes impossível) para mim. A documentação no site do Wordress é clara e bastante completa, mas tudo está em inglês… por isso resolvi escrever este post dando algumas dicas e mostrando o método que usei depois de decifrar alguns artigos de documentação e destrinchar alguns plugins que baixei da rede.
O WordPress hoje conta com uma API (Application Programming Interface) para dar suporte ao desenvolvimento de plugins que facilita as coisas de um modo incrível, tornando a tarefa de escrever um plugin algo bastante tranquilo, sem grandes dificuldades e sem interferir no funcionamento do núcleo do WP. Usando o que eles chamaram de "Hooks" (ganchos) podemos definir funções para serem executadas em momentos específicos a execução do WordPress, quando o usuário fizer isso ou aquilo ou filtrar conteúdos antes que sejam enviados para a tela.
O que é um plugin?
Um plugin, por definição, é um programa que se conecta em outro para ampliar as funcionalidades ou resolver problemas deste segundo. Normalmente um plugin para WordPress adiciona ou modifica algo no conteúdo ou na apresentação do blog e oferece uma interface para configurações e/ou outras ações na administração do WP.
Ao construir um plugin para qualquer aplicativo, há certos cuidados que deveríamos tomar.
- Evite colisões de nomes de funções e variáveis
é prudente usar um prefixo em todos os nomes, como "myplug_" - Não modifique arquivos originais do programa
para não haver problemas se o plugin for desinstalado - Crie um sistema de desinstalação
evitando deixar arquivos perdidos ou dados inúteis poluindo a database se o plugin for desinstalado - Evite erros desnecessários de imcompatibilidade
testando pela existência de variáveis, funções e classes antes de tentar usá-las no seu código
A estrutura do plugin
Para ser aceito como um plugin utilizável, há apenas uma exigência: é preciso criar um cabeçalho segundo certas regras, como descrito aqui (em inglês). Veja um exemplo:
/*
Plugin Name: Nome do Plugin
Plugin URI: homepage do plugin
Description: Descrição do plugin.
Version: Número da versão, como 1.0
Author: Nome do autor do plugin
Author URI: Homepage do autor do plugin
*/
?>
Após inserir esses dados no seu arquivo (.php) e colocá-lo em "…/wp-contents/plugins/" ele já estará disponível na página de gerenciamento de plugins da administração do WP.
Esse cabeçalho deve ser colocado apenas no arquivo principal do plugin e deve estar no diretório citado acima, solto ou em um subdiretório, como em "…/wp-contents/plugins/myplug/myplug.php". Não importa o nome que você der ao arquivo, o WP vai procurar por algo semelhante ao cabeçalho mostrado acima em todos os arquivos PHP no diretório pluins e em seus subdiretórios (apenas um nível).
Naturalmente, um plugin pode ter vários arquivos, mas tudo deve ser detonado a partir do arquivo principal, que contém o cabeçalho. É ele que vai ser executado se o plugin estiver ativado.
O que faz o seu plugin?
Existem centenas de plugins para WordPress disponíveis na web, alguns super bem feitos, outros nem tanto… Antes de iniciar seu plugin, busque na rede. Talvez haja algo pronto que atenda às suas necessidades.
Mas se você teve uma idéia genial ou tem uma necessidade específica, mantenha em mente o seu objetivo e mãos à obra!
Entendendo os Hooks
Há dois tipos de ganchos para usar em seu plugin:
- Actions (ações) referência (inglês)
As actions nos dão a possibilidade de executar funções em situações determinadas da execução do WordPress, como ao escrever um post, ao editar um post, etc. - Filters (filtros) referência (inglês)
Os filters permitem literalmente filtrar a sáida de dados do WP. Podemos por exemplo procurar por ":)" no texto dos posts e substituir por um smile em imagem (claro que isso já existe…) . Nesse caso, nossa função recebe o texto do post depois de processado pelo WP e antes de ser impresso na tela, processa e retorna, só então o texto é exibido.
Para usar actions e filters existem duas funções específicas, que recebem parâmetros iguais:
Há dois parâmetros opcionais relativos à prioridade para a execução da função e aos parâmetros recebidos por sua função, mas nem falaremos deles - apenas os dois primeiros são obrigatórios e são suficientes. Quando sua função for executada, estará literalmente "dentro" do WordPress, com acesso a funções e variáveis. Antes de sair escrevendo, consulte a referência de funções do WP e, se necessário, vá olhar a função sobre a qual tiver dúvidas. Isso evitará a construção de funções redundantes, diminuindo consideravelmente seu código - o WP tem muitas funções úteis e disponíveis. Quanto às variáveis, vale dar uma pesquisada para encontrar os dados que procura… tudo está "flutuando" nas variáveis globais do WP.
A linha de código abaixo vai retornar um resultado enorme, mas vai te ajudar a achar o que procura. Muitos dos valores estão em objetos, como em $post, que contém os dados de um post, e é importante lembrar que para acessar as propriedades não funciona a fórmula do array, como em $post[’ID’], o correto é $post->ID.
// Descomente para ver os dados ao seu alcance:
// die(print_r($GLOBALS, true));
// Para recuperar um dos valores globais, não
// esqueça de colocar dentro de sua função:
// global $varn;
// (torna acessível o valor em $GLOBALS["varn"])
Ok, com os hooks posso executar qualquer coisa para implementar a funcionalidade proposta pelo meu plugin. Mas e para inserir uma página na administração do WP?
Inserindo uma página na administração do WordPress
Aqui a liberdade é total. Podemos criar um novo item no menu principal e depois criar subpáginas para esse tópico ou simplesmente criar uma subpágina para um item existente, como em Options, por exemplo - muito usado pelos plugins. Para fazer isso, usamos as funções:
add_menu_page(page_title, menu_title, access_level/capability, file, [function]);
add_menu_page adiciona um item ao menu principal. Essa opção nas últimas versões do WP pode ser desabilitada pelo administrador, portanto deve ser usada com cautela.
add_submenu_page(parent, page_title, menu_title, access_level/capability, file, [function]);
add_submenu_page adiciona um item a um tópico do menu principal, seja uma das páginas padrão do WP ou um tópico criado com add_menu_page().
Veja os parâmetros:
- parent -> o arquivo relativo ao tópico do menu principal - apenas para add_submenu_page()
- page_title -> valor que será aplicado ao título da página
- menu_title -> Rótulo do item que será inserido no menu
- access_level/capability -> nível ou capacidade do usuário
Aqui definimos que usuários terão acesso às funcionalidades do nosso plugin (os níveis vão de 0 a 10 e as capacidades são: administrator, editor, author, contributor e subscriber). - file -> o endereço do arquivo PHP que é a interface do plugin ou um ID (uma string de identificação) para a página, se você optou por usar o parâmetro seguinte (function)
- function -> o nome da função que inclui ou mostra a iterface do plugin.
Guardando seus dados
Seu plugin pode usar a database de duas formas:
- Criando tabelas no banco de dados
Para criar suas próprias tabelas, é preciso seguir certas normas.
- Talvez seja prudente antes de qualquer coisa tentar entender a classe wpdb - aqui (em inglês)
- Não esqueça de que o administrador pode configurar um prefixo para as tabelas no banco, portanto é importante usar esse prefixo que está em $wpdb->prefix.
- Use o hook "activate_[arquivo_do_plugin]" para chamar a função de instalação
- Aqui é mais importante que nunca ter uma função de desinstalação, chamada através do hook "deactivate_[arquivo_do_plugin]"
- Usando as funções nativas do WordPress
O WordPress oferece algumas funções para os plugins armazenarem informações no banco de dados, o chamado "Mecanismo de opções", que nos permite guardar variáveis serializadas no banco de dados. Essas variáveis podem ser de vários tipos, acho que até objetos (se você usar a propriedade mágica __SLEEP), sei lá. Veja as funções que implementam a idéia:
- add_option(option_name, value, [description], [autoload])
- get_option(option_name)
- update_option(option_name, value, [description], [autoload])
- delete_option(option_name)
Os parâmetros
As funções recebem parâmetros semelhantes, sendo que description e autoload são aplicáveis apenas- option_name -> nome da opção.
- value -> valor (inicial ou novo valor) da opção.
- description -> Uma descrição da opção sem muito uso prático. (opcional)
- autoload -> pode-se usar esse parâmetro para definir se a opção será carregada automaticamente ou não. Também sem muito uso. (opcional)
Usando Javascript e CSS em seu plugin
O WordPress oferece duas funções para incluir o seu script automaticamente, carregando até bibliotecas como o prototype se você especificar, mas eu não pesquisei nem usei essas funções (wp_print_scripts, wp_register_script, wp_deregister_script e wp_enqueue_script - todas sem referência oficial).
Mas sem usar essas funções, como fazer? Simples. Como já foi dito, temos acesso à todos os "momentos" da execução do WP - isso significa que podemos escolher quando (e aqui quando quer dizer aonde) nossa função será executada. Estamos dentro do WordPress por assim dizer, qualquer print ou echo irá imprimir na página diretamente, então basta procurar o hook certo e imprimir o que precisamos na seção HEAD da página e o hook para isso é "wp_head" para as páginas do site e "admin_head" para as páginas da administração. Faríamos então algo assim:
add_action("wp_head", "addHeadContents");
function addHeadContents() {
?>
<style type="text/css">
@import url(../css/myplug.css);
</style>
<script type="text/javascript">
function myplug() {
var mypageRe = /minha_pagina\.php([\?#].+)?$/;
if(mypageRe.test(location.href) && !_recebido) alert("Benvindo!");
}
</script>
<?php
}
…
Simples, né?
Internacionalizando seu plugin
Isso é necessário se você deseja compartilhar seu plugin com o resto do planeta e não apenas com os que falam português. O mais correto, de qualquer modo, seria escrever o plugin em inglês e então traduzir para o português brasileiro, para que seus clientes possam entender.
O sistema utilizado é o gettext da GNU e há duas funções que você deve lembrar, a __() que retorna o texto original (em inlês) traduzido para a linguagem selecionada pelo administrador do sistema e _e() que imprime a tradução diretamente na tela. Mas para os plugins, é preciso criar um text domain (uma palavra-chave que identifique seu plugin), no nosso exemplo, "myplug" - veja adiante. Então…
// invés de escrever
$action = "Write";
// escreveremos
$action = __("Write", "myplug");
?>
<!– invés de escrever –>
<p>Define your settings</P>
<!– escreveremos –>
<p>
<?php _e("Define your settings", "myplug"); ?>
</P>
Você pode desenvolver seu plugin até o final sem se preocupar, apenas onde houver um texto legível, use as fórmulas acima. Mas a coisa ainda não funciona, pois precisamos agora carregar o domínio criado (myplug) e indicando o caminho para o diretório onde estará o arquivo myplug-pr_BR.mo, que criaremos em seguida. Para isso você precisará de um editor específico para arquivos .POT, .PO e .MO. Eu uso e recomendo o poEdit, mas não vou me alongar mais sobre ele - veja aqui ou aqui (em inglês) .
Após criar o arquivo POT inicial, basta atualizar que o programa vai ler e mostrar cada texto que foi enviado para as funções __() e _e(). Traduza e salve. Isso irá gerar o arquivo .MO, que deve ter um nome assim:
text-domain_do_pligin-linguagem escolhida.mo
Como por exemplo: myplug-pt_BR.mo.
Agora basta carregar o text-domian criado com a seguinte linha de código:
$dir_name = preg_replace("/^.+(\\\\|\/)/", "", dirname(__FILE__));
load_plugin_textdomain("myplug", "wp-content/plugins/".$dir_name);
Agora tudo deve estar funcionando.
Acho que isso vai ajudar bastante os que estão iniciando com o WP, esse programa fantástico. Boa programação e tenha sempre em mente a nota de rodapé do site do WordPress: CODE IS POETRY!
Mapa do site