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 butõ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 I, a parte II e a parte III desta série.

Depois de abordado a forma 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 paginas de opções do WordPress, desde a criação simples de um novo controlador numa página já existente até à criação de novas secções para albergar nossos controladores em novas páginas customizadas.

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

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 developer 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 controlo 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 rapidamente 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 nós 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, como quase sempre, alguns programadores, principalmente dos plugins ou temas pagos as suas páginas de configurações não usam esta API, no entanto esta tendência está a mudar e começa a surgir a ideia geral que realmente a API do WordPress é muito mais fiá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 ficheiro e no cimo 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á aparecer 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.

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 secçã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 apenas tem uma secçã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 alterar a estratégia de implementação de campos de opções, não haverá problemas de haver alguma quebra no código.

CRIANDO SECÇÕES DE CAMPOS

Imagine que pretende criar vários campos dentro de uma página mas pretende agrupá-los de forma a 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 a 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 adicionar no cabeçalho da secção e o ID da página onde a secção deverá aparecer. Seguidamente deveremos alterar o ID da secção na função add_settings_section para o ID da nova secçã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á:

Você poderá criar mais campos replicando as funções register_setting e add_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 NOVA PÁGINA

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 criádo anteriormente. Para isso vamos manter o nosso código que acabámos 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 class="wrap">
    <?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 de facto 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, por forma a que a função que regista os nossos campos e secções seja só 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-nos a não carregar código desnecessário. Desta forma conseguimos obter um código muito mais fiá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-campos' );

// 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 alterámos o ID da página de general 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 asfunções.

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

ADICIONANDO MENSAGENS DE ERRO

Também é muito simples adicionar mensagens de erro nas páginas de opções do WordPress, incluindo na nossa, basta para isso usarmos a função add_settings_error durante a função de validação de cada campo. Para vermos isso em acçã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 error e updated.

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 assim 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.

Download do código deste artigo!

Não se esqueça de acompanhar esta série até ao próximo artigo, o último, onde irei mostrar como usar a API de tabelas do WordPress para renderizarmos uma tabela com ligação a dados externos.

Até para a semana!