Back-End

16 jan, 2013

Guia completo de integração com o ambiente gráfico do WordPress – Parte 04

Publicidade

Este artigo é a quarta parte da série sobre desenvolvimento de plugins e temas com o foco na integração com o ambiente nativo da administração do WordPress, o uso dos componentes gráficos tais como botões, tabelas, frames, entre outro CSS nativo, incluindo as API de configurações, nonces entre outras ferramentas que o WordPress já nos oferece. Reveja a parte 01, a parte 02 e a parte 03 desta série.

Depois de abordar como usar diferentes tipos de elementos UI na nossa página, iremos aprender nesta parte como usar a API de opções do WordPress para escrever os nossos controladores nas páginas de opções do WordPress, desde a criação simples de um novo controlador numa página já existente até à criação de novas seções para albergar nossos controladores em novas páginas customizadas.

No último artigo criamos vários elementos dentro da nossa página de opções. Vamos primeiro aprender como adicionar um controlador com a API em uma das páginas de opções do WordPress pegando nesse arquivo e criando novas funções. Em seguida vamos modificar o conteúdo da nossa página para também usar a API de opções. Vamos começar por pegar nesse arquivo.

A API de opções do WordPress

Uma API é um interface com que podemos comunicar com determinada aplicação. No caso do WordPress, existem várias API para acessar ou escrever conteúdo, atribuir novas tarefas e funcionalidades, etc. A API de opções é uma interface que permite a um desenvolvedor criar mais inputs dentro das páginas de opções para controlar a aplicação de novas funcionalidades que determinados plugins podem dar ao WordPress.

Esta API é uma combinação de funções que simplifica o processo de criação, saneamento, limpeza, salvamento e controle de novos dados por parte dos usuários, tornando mais seguro para o sistema.

Porquê usar a API de opções?

Antes de começarmos a usar, temos que entender porque é importante usar esta API de opções. Ficam aqui algumas sugestões:

  • Comunica diretamente com o core do WordPress e permite que tenhamos acesso aos dados sem muito esforço;
  • As opções criadas através da API não irão quebrar em futuras versões, opondo-se ao fato de que, se criarmos as opções na nossa página sem a API, já não podemos garantir isso;
  • Aquando do salvamento de dados correm vários processos e funções de saneamento e verificação de dados para que não sejam guardados dados malaciosos no banco de dados;
  • Torna-se mais rápido criar e modificar opções.
Existem imensos benefícios em usar a API de opções, basta fazer uma pesquisa no Google e olhar para vários artigos sobre o assunto. Infelizmente, alguns programadores, principalmente dos plugins ou temas pagos, não usam esta API, no entanto, esta tendência está mudando e começa a surgir a ideia geral de que realmente a API do WordPress é muito mais viável que qualquer outra forma que os programadores possam arranjar à margem do “oficial” do WordPress, criado pelos próprios programadores.

Criar o primeiro controlador na página de opções gerais

Como explicado no início, vamos primeiro ver como é simples criar um campo na página de opções gerais do WordPress. Para isso, vamos abrir o nosso arquivo e no vamos introduzir o seguinte código:

// Criar um campo na página de opções gerais do WordPress
add_action( 'admin_init', 'test_ui_general_options_input' );
function test_ui_general_options_input() {
    // Por conveniência guardamos alguns valores neste array
    // de modo a ser apenas preciso alterar os dados num único lugar
    $args = array(
        'id' => 'id-da-opcao',
        'name' => 'nossa_opcao',
    );
    // Registamos a opção de modo que o WordPress possa guardá-la automaticamente na tabela wp_options
    // O primeiro parâmetro deve ser igual ao valor da função settings_field() usada na página onde
    // se quer que a opção apareça. O segundo parâmetro é o nome com que queremos guardar a opção e
    // o terceiro é o nome da função a ser chamada para testar os nossos valores: pode ser qualquer função
    // que retorne um valor, por exemplo intval() para validar apenas numeros inteiros.
    register_setting( 'general', $args['name'], 'test_ui_valida_opcao' );
    // Diz ao WordPress onde ir buscar a opção, o que mostrar e onde.
    add_settings_field( 'id-da-opcao', 'Este é o título da opção', 'test_ui_conteudo_da_opcao', 'general', 'default', $args );
}
function test_ui_conteudo_da_opcao( $args ) {
    // Buscar a opção guardada na tabela wp_options e imprimir o nosso primeiro input
    $dados_do_bd = get_option( 'nossa_opcao' );
    ?>
    <input id="<?php echo $args['id']; ?>" name="<?php echo $args['name']; ?>" type="text" value="<?php echo $dados_do_bd; ?>" class="regular-text" />
    <?php
}
function test_ui_valida_opcao( $value ) {
    // Vamos remover todos os caracteres HTML
    // script, etc, de modo a podermos guardar
    // estes dados no banco de dados seguramente.
    return strip_tags( $value );
}

Se você colocar este código no nosso plugin, verá uma opção na página de opções gerais do WordPress igual à que se encontra na imagem. Você pode testar para ver se a opção é guardada ou não e se a função retorna um valor correto. Poderá (e deverá) implementar um teste Unit para cada uma das funções de verificação, caso estas sejam complexas. Irei falar num próximo artigo, fora desta série, sobre como implementar testes Unit aos nossos plugins e temas no WordPress através da framework PHPUnit e de alguns plugins que ajudam no processo.

Selecção_053

Este código é muito simples e apresenta essencialmente duas novas funções que pertencem à API de opções do WordPress: register_setting e add_settings_field. Estas funções fazem apenas isso: pedir ao WordPress (gentilmente) para guardar a nova opção customizada sempre que for solicitado e mostrar a interface para essa opção. É simples, não é?

Como referência, ficam aqui os valores que podem ser usados no primeiro parâmetro da função register_setting de acordo com as páginas de opções donde se espera que a opção seja guardada:

  • Opções Gerais: “general”
  • Escrita: “writing”
  • Leitura: “reading”
  • Mídia: “media”,
  • Discussão: “discussion”
  • Privacidade: “privacy”
  • Links Permanente: “permalink”

Na função add_settings_field, o penúltimo parâmetro será normalmente “default”, e corresponde à da página onde queremos colocar o nosso campo, no entanto existem algumas páginas que têm mais que uma seção. Como referência, deixo aqui mais algumas combinações que podem ser usadas:

Escrita: 

  • “writing”, “default”
  • “writing”, “post_via_email”
  • “writing”, “remote_publishing”
Mídia:
  • “media”, “default”
  • “media”, “embeds”
  • “media”, “uploads”
Discussão:
  • “discussion”, “default”
  • “discussion”, “avatar”
Permalinks:
  • “permalink”, “optional”
Nota: a página de Links Permanentes tem uma seção para você usar que se chama “optional”.

Estas são duas funções fundamentais neste processo de construção de campos para o WordPress. O nosso código fica muito mais limpo e, caso um dia o WordPress altere a estratégia de implementação de campos de opções, não haverá problemas de haver alguma quebra no código.

Criando seções de campos

Imagine que pretende criar vários campos dentro de uma página, mas pretende agrupá-los de forma que não se misturarem uns com os outros. Como vimos anteriormente, isso é possível através de secções, porém não estamos restringidos apenas às secções que o WordPress nos fornece. Também podemos criar as nossas secções de maneira muito simples, bastando para isso fazer algumas alterações e incluir a função add_settings_section no nosso código. Vamos então incluir à seguinte linha na função test_ui_general_options_input depois de register_setting e antes de add_settings_field:

// Diz ao WordPress para registar uma nova secção na página
add_settings_section( 'nossa-seccao', 'Nova secção customizada', 'test_ui_conteudo_seccao', 'general' );

Esta função aceita um ID no primeiro parâmetro que será usado na função add_settings_field, um título, o nome da função que irá colocar conteúdo e adicionar no cabeçalho da seção e o ID da página onde a seção deverá aparecer. Seguidamente, deveros alterar o ID da seção na função add_settings_section para o ID da nova seção, passando então de default para nossa-seccao:

// Diz ao WordPress onde ir buscar a opção, o que mostrar e onde.
add_settings_field( 'id-da-opcao', 'Este é o título da opção', 'test_ui_conteudo_da_opcao', 'general', 'nossa-seccao', $args );

E o resultado se recarregar o WordPress será:

Selecção_054

Você poderá criar mais campos replicando as funções register_settingadd_settings_filed alterando os valores variáveis obviamente. Não existe limite teórico para este processo, que deverá ser sempre da mesma maneira.

Usando a API de opções numa página nova

Agora, chegando à reta final do nosso artigo de hoje, vamos implementar a solução da API de opções na nossa página que tinhamos criado anteriormente. Para isso, vamos manter o nosso código que acabamos de criar e expandir para adaptar a nossa página. É bastante simples até, basta usar duas funções: settings_fields e do_settings_sections.

// Esta função faz o display do conteúdo da página
// Alterámos esta função para usar a aPI de Opções do WordPress
function test_ui_submenu_page_callback() {
?>
<div>
<?php screen_icon(); ?>
<h2>
Plugin de Teste UI
</h2>

<!-- O corpo da página vem aqui -->

<!-- Criamos um formulário a apontar para a página options.php -->
<form id="formulario" action="options.php" method="post">

// Todo o interior do formulário foi apagado de modo
// a podermos processar cada campo através da API de Opções.
// Esta função constrói um array com os campos que serão
// visualizados aqui.
// O argumento é um ID qualquer que você pode escolher para
// usar nas funções register_setting, add_settings_field e
// do_settings_sections.
<?php settings_fields( 'nossos-campos' ); ?>

// Esta função renderiza a tabela, as secções e cada campo.
// Faz todo o trabalho por nós sem ser necessário usar HTML
// para além do input dos campos.
<?php do_settings_sections( 'nossos-campos' ); ?>

<?php submit_button(); ?>

</form>

</div>
<?php

}

Aqui temos o código da nossa nova página que irá usar a API de opções do WordPress. Repare no ID que coloquei dentro das funções settings_fields e do_settings_sections e veja que estas funções partilham o mesmo ID. Este será usado também nas funções register_setting e add_settings_page no lugar do parâmetro da página (atualmente general).

Para isso temos que eliminar a linha:

// Criar um campo na página de opções gerais do WordPress
add_action( 'admin_init', 'test_ui_general_options_input' );
e modificar da seguinte maneira, para que a função que regista os nossos campos e seções só seja chamada durante o carregamento da nossa página:
function test_ui_submenu_page() {
 // Adicionar um submenu para a página do plugin onde iremos criar controladores
 $page = add_submenu_page( 'options-general.php', __( 'Teste UI', 'plugin-test-ui' ), __( 'Teste UI', 'plugin-test-ui' ), 'manage_options', 'plugin-test-ui', 'test_ui_submenu_page_callback' );

// Vamos passar a chamar a função que regista os campos e secções da nossa
// página apenas quando ela é carregada ou quando guardamos os dados através
// da página options.php em vez de usarmos a chamada ao admin_init
add_action( "load-options.php", 'test_ui_general_options_input' );
add_action( "load-{$page}", 'test_ui_general_options_input' );

}

Também continuaria a ser possível usarmos a chamada admin_init, no entanto, as boas práticas recomendam não carregar código desnecessário. Desta forma, conseguimos obter um código muito mais viável e que não comprometa outros plugins.

Por último será necessário alterar o ID das funções register_setting, add_settings_section e add_settings_field (lembra-se do ID que colocámos em cima na nossa página?) dentro da função test_ui_general_options_input:

register_setting( 'nossos-campos', $args['name'], 'test_ui_valida_opcao' );

// Diz ao WordPress para registar uma nova secção na página
add_settings_section( 'nossa-seccao', 'Nova secção customizada', 'test_ui_conteudo_seccao', 'nossos-campo<strong>s</strong>' );

// Diz ao WordPress onde ir buscar a opção, o que mostrar e onde.
add_settings_field( 'id-da-opcao', 'Este é o título da opção', 'test_ui_conteudo_da_opcao', 'nossos-campos', 'nossa-seccao', $args );

Repare que apenas alteramos o ID da página de geral para nossos-campos. Lembre-se que este ID pode ser qualquer coisa (desde que não entre em conflito com IDs já existentes e mensionados em cima) porém tem de ser o mesmo ID em todas as funções.

Agora, ao dirigir-se à página de opções que implementamos, o resultado será parecido com este:

Selecção_055

Adicionando mensagens de erro

Também é muito simples adicionar mensagens de erro nas páginas de opções do WordPress. Basta usarmos a função add_settings_error durante a função de validação de cada campo. Para vermos isso em ação, vamos dar algum contexto ao nosso formulário, alterando o label do nosso campo para pedir ao usuário a introdução de um email:

add_settings_field( 'id-da-opcao', 'Introduza um email', 'test_ui_conteudo_da_opcao', 'nossos-campos', 'nossa-seccao', $args );

Agora vamos alterar a função de validação para incluir a seguinte verificação:

function test_ui_valida_opcao( $value ) {
// Vamos analizar se o usuário introduzio um email válido.
// Para isso usamos a função do WordPress is_email()
// Caso não seja email retomamos um valor vazio e acionamos o erro
if ( ! is_email( $value ) )
return add_settings_error( 'erro_1', 'id-do-erro', 'Isso não é um email!', 'error' );

return $value;

}

Ao adicionar a função add_settings_error é necessário passar como parâmetros um nome e um ID arbitrários para associar este erro, assim como uma mensagem a mostrar no terceiro parâmetro e por fim se é um erro ou uma mensagem de atualização, sendo os possíveis valores errorupdated.

Selecção_057

Espero que este artigo tenha simplificado a ideia de como usar a API de opções do WordPress tanto para incluir campos em páginas existentes, como para criar novas páginas de opções para os seus plugins. Este é o básico da API e não haverá muito mais a acrescentar para além de técnicas e formas de organizar os dados.

Até para a semana!