Este artigo é a terceira 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 e a parte II desta série.

Depois de abordado o básico sobre integração, criando a nossa primeira página e na segunda termos expandido um pouco mais os conhecimentos sobre os elementos UI, iremos nesta parte falar sobre como criar abas para opções e ajuda na nossa página, assim como criar navegação por abas como encontramos na página de gestão de temas e terminando com a criação e manipulação de metaboxes.

No último artigo criámos o wrapper da nossa página assim como um conjunto de botões e links que deverão ser usados nas várias acções. Vamos começar por pegar nesse código e continuar o nosso desenvolvimento.

NAVEGAÇÃO POR ABAS

A navegação por abas é parte integrante da API de CSS da administração do WordPress, embora muitos não saibam e não apliquem. Na verdade esta navegação está ficando cada vez mais em desuso aparecendo apenas atualmente no painel de escolha e gestão de temas do WordPress. Pessoalmente não concordo com esse caminho que o WordPress está a seguir. A navegação por abas facilita em muito a organização de conteúdo e é até benéfica pois possibilita ter mais opções numa única página sem ser necessário preocupar-nos com a mancha gráfica que tanta opção poderá causar.

Vamos nesta secção ver como criar a nossa navegação por abas dentro da nossa página de teste usando o CSS nativo da administração do WordPress. Coloque então substituir o cabeçalho da nossa página, dentro da função test_ui_submenu_page_callback:

function test_ui_submenu_page_callback() {
	$tab = isset( $_GET['tab'] ) ? $_GET['tab'] : 'general';
	?>
<div class="wrap">
	<?php screen_icon(); ?>
	<h2>
		Plugin de Teste UI
		<a href="#" class="add-new-h2">Um link</a>
		<a href="#" class="add-new-h2">Outro link</a>
	</h2>

	<h2 class="nav-tab-wrapper">
		<span>&nbsp;</span>
		<a href="#" class="nav-tab">Primeira Tab</a>
		<a href="#" class="nav-tab">Segunda Tab</a>
	</h2>

[...]

E cá está o código é um simples trecho de HTML com classes que nos permitem ter acesso à interface de abas nativa. Possivelmente também notou uma diferença em relação ao cabeçalho anterior que é a presença da função screen_icon(). Esta função substituiu o techo de código que mostrava o ícone da página. Não foi apenas por isso que substituimos esse código mas principalmente para manter a coerência em futuras versões do WordPress e sobretudo para darmos hipótese de outros plugins com funções específicas poderem fazer alterações ao cabeçalho.

Resumidamente, o código seguinte cria a navegação por abas, no entanto esta ainda não se encontra funcional. Será necessário tomar algumas alterações para que isso seja possível. Vamos adicionar as seguintes ligações no nosso código:

<h2 class="nav-tab-wrapper">
	<span>&nbsp;</span>
	<a href="options-general.php?page=plugin-test-ui&tab=general" class="nav-tab">Primeira Tab</a>
	<a href="options-general.php?page=plugin-test-ui&tab=especifico" class="nav-tab">Segunda Tab</a>
</h2>

Agora que vamos usar a variável $_GET[‘tab’] na URL para podermos alternar o conteúdo entre abas, precisamos de saber qual a aba a ser mostrada. Dessa maneira o código em cima vai condicionalmente obter qual a aba a mostrar:

$tab = isset( $_GET['tab'] ) ? $_GET['tab'] : 'general';

Neste momento temos já tudo pronto, basta dividir o corpo da página em duas grandes condições para mostrar o conteúdo de uma ou de outra aba. Aqui segue a função completa já com essa condição:

// Esta função faz o display do conteúdo da página
// No futuro iremos colocar tudo o que é visível aqui
function test_ui_submenu_page_callback() {
	$tab = isset( $_GET['tab'] ) ? $_GET['tab'] : 'general';
	?>
<div class="wrap">
	<?php screen_icon(); ?>
	<h2>
		Plugin de Teste UI
		<a href="#" class="add-new-h2">Um link</a>
		<a href="#" class="add-new-h2">Outro link</a>
	</h2>

	<h2 class="nav-tab-wrapper">
		<span>&nbsp;</span>
		<a href="options-general.php?page=plugin-test-ui&tab=general" class="nav-tab<?php if ( 'general' == $tab ) echo ' nav-tab-active'; ?>">Geral</a>
		<a href="options-general.php?page=plugin-test-ui&tab=especifico" class="nav-tab<?php if ( 'especifico' == $tab ) echo ' nav-tab-active'; ?>">Específico</a>
	</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">
		<div class="poststuff">

			<?php if ( 'general' == $tab ) : ?>

			<p>Aqui vão os campos para as suas opções gerais</p>

			<?php elseif ( 'especifico' == $tab ) : ?>

			<p>Aqui vão os campos para as suas opções específicas</p>

			<?php endif; ?>

			<div style="clear: both;">
				<?php submit_button(); ?>
			</div>
		</div>
	</form>
</div>
    <?php
}

Desta maneira obtemos  a página como mostrado na imagem acima. Nas próximas secções iremos tratar dos elementos dos formulários de campo e de como adicionar a pestana de ajuda na nossa página.

ELEMENTOS DE FORMULÁRIO

Nesta secção vamos ver como podemos mostrar e organizar os campos de formulário dentro da nossa página, dividindo por secções e usando as classes CSS da administração para manter a coesão gráfica.

Para isso, dentro de uma das abas criadas anteriormente (dou-lhe a liberdade de escolher qual delas quer usar :-)  vamos inserir o código HTML que irá ser a base da flutuação dos nossos elementos, através de uma tabela:

<div class="poststuff">
	<!-- Aqui vão os inputs -->
	<h3>Secção 1</h3>

	<table class="form-table">
		<tbody>

		</tbody>
	</table>
</div>

As classes poststuff e form-table são as únicas que vamos precisar aqui. A primeira auxilia-nos no que toca a atribuir CSS extra a alguns elementos como as metaboxes (iremos falar mais à frente)  e a segunda alinha todos os elementos do formulário de modo a torná-lo consistente. É dentro da tag <tbody> que vamos colocar um por um os nossos campos. A tag <h3> está estilizada de modo a apresentar um título que de certa maneira dê a impressão que unifica os campos numa única secção.

Agora vamos aprender a organizar os elementos dos nossos campos. A base das linhas da tabela que vão ter os campos é a seguinte:

<tr valign="top">
	<th scope="row">
		Input de Texto
	</th>
	<td>
		<!-- Aqui entram os inputs -->
	</td>
</tr>

A tag <th> deve ser sempre a parte que alberga o título para determinado campo. Este título deve ser conciso e mostrar a acção e não a opção, ou seja, deve em curtas palavras explicar resumidamente ao usuário o que vai acontecer posteriormente se o usuário usar aquele campo. Dentro da tag <td> vamos colocar agora o campo que quisermos, podendo ser um campo de texto normal, um conjunto de checkboxes ou radioboxes, uma área de texto ou outro qualquer elemento que se pretenda colocar. Vamos apenas nos centrar nos códigos para os cinco principais tipos campos de formulário:

<!-- Campo de texto regular -->
<input type="text" name="input1" id="input1" value="Escola WordPress" class="regular-text">

<!-- Campo de texto com letra monoespaçada, ideal para introduzir códigos ou URL -->
<input type="text" name="input2" id="input2" value="http://www.escolawp.com" class="regular-text code">

<!-- Checkboxes -->
<p>
	<label for="checkbox1">
		<input type="checkbox" name="checkbox" id="checkbox1" value="1">&nbsp
		Escolher a primeira opção
	</label>
</p>

<!-- Select dropdown box -->
<select name="select" id="select1" class="postform">
	<option class="level-0" value="1">Opção 1</option>
	<option class="level-1" value="2">Opção 2</option>
</select>

<!-- Texto para introdução de número -->
<input type="number" name="number" id="number" value="80" step="5" min="0" max="100" class="small-text">

<!-- Colocar um parágrafo como descrição -->
<p class="description">Descrição sobre o campo</p>

Estes são os códigos base para os cinco principais tipos de campos para formulários usados no WordPress, no entanto vou deixar aqui uma lista completa das classes e inputs que podem ser usados nativamente.

Classes CSS gerais: small-text, regular-text, code, postform, description, trash, delete, widefat

Com a introdução do HTML5 foram propostos novos tipos de inputs, alguns já suportados pelos principais browsers sendo que o Google Chrome (ou a variante Chromium) está a liderar esta inovação. Infelizmente o WordPress ainda não tem estilizado a maior parte deste tipo de inputs, principalmente para desencorajar o seu uso, por enquanto, pois não é possível ainda garantir que todos os usuários tenham experiência semelhante, devido ao número elevado de versões obsoletas que ainda andam a circular. No entanto deixo aqui uma lista de alguns tipos de input propostos para o HTML5 e que gradualmente poderão vir a ser usados:

text, number, range, email, tel, url, search, color, date, datetime, datetime-local, month, time, week

Felizmente a versão 3.5 do WordPress que provavelmente irá sair em Dezembro já suporta todos estes tipos novos. Esperamos apenas que num futuro próximo os browsers suportem totalmente estes novos tipos.

ABA SUSPENSA DE AJUDA

Vamos agora aprender a adicionar uma aba de ajuda na nossa página. As abas de ajuda são essenciais se queremos que o nosso plugin ou tema tenha sucesso pois é a primeira referência que o usuário tem, por isso é necessário ser conciso e acertivo ao mostrar o seu conteúdo.

Para isso vamos ter que modificar a função test_ui_submenu_page que usámos anteriormente, para colocar uma chamada à action hook load apenas para a 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' );

	// Action hook para chamar a função test_ui_admin_init
	// apenas quando o WordPress estiver a carregar a nossa página
	add_action( "load-{$page}", 'test_ui_admin_init' );

}

E agora vamos definir a nossa função a ser chamada apenas quando visualizamos a página do plugin:

function test_ui_admin_init() {
	// Aqui podemos adicionar tudo o quisermos que apareça ou que corra
	// apenas na nossa página incluindo carregar scripts e css, correr um script php
	// ou adicionar opções e abas de ajuda
}

Esta é a função que fará todo o trabalho de backend para nós. A action hook load é responsável por carregar tudo o que diz respeito a um ecrã, seja este página virtual, de plugin, de tema ou um ficheiro php incluido no diretório wp-admin. É nela que podemos colocar o que quisermos que seja carregado especificamente para a nossa página. São muitos os programadores que infelizmente deixam uma pegada substancialmente forte no WordPress quando deixam que se carregue tudo do seu plugin em qualquer página da administração. Esse método de carregar CSS e scripts ou outro código é errado e não deve ser seguido!

Vamos agora adicionar dentro da função a nossa aba de ajuda, auxiliados pela função get_current_screen():

get_current_screen()->add_help_tab( array(
	'id' => 'primeira_aba',
	'title' => 'Primeira aba de ajuda',
	'content' => 
		'<p>' . 'Um parágrafo com alguma ajuda importante' . '</p>' .
		'<p>' . 'Outro parágrafo!' . '</p>'
	)
);

Et voilá! Se você recarregar a página verá aparecer uma nova tab que diz “Ajuda” e nela uma aba com o conteúdo que definimos. Você poderá criar quantas abas de ajuda você quiser e sentir que valem a pena, repetindo sempre o mesmo código.

CRIANDO METABOXES

As metaboxes são pequenas caixas globalmente usadas nas páginas de administração do WordPress para organizar conteúdo. O fascinante disso é que o usuário pode sempre retirar, mover e voltar a posicionar cada uma destas caixas.

Como não podia deixar de ser, vamos mostrar como adicionar metaboxes e uma área para albergar as recém criadas metaboxes na nossa página. Para isso primeiro, e acompanhando o passo da secção anterior, vamos adicionar as metaboxes que queremos à nossa página através da função add_meta_box:

// Criar metaboxes para a nossa página. Use quantas vezes quiser esta função para criar várias metaboxes.
add_meta_box( 'teste_de_metabox', 'Uma metabox', 'test_ui_metabox_content', 'plugin_test_ui', 'side' );

// Incluir JS scripts e CSS importante para lidarmos com algumas funcionalidades das metaboxes
wp_enqueue_script( 'jquery-ui-sortable' );
wp_enqueue_script( 'postbox' );
wp_enqueue_script( 'post' );

Lembra-se do que escrevi na secção anterior sobre a action hook load? É nessa função que vamos colocar este código de modo a estar apenas disponível na página do plugin. A função add_meta_box tem como parâmetros um ID para a metabox, o título da metabox, a função que renderizará o conteúdo dentro da metabox, o ID onde mostrar e em que sitio mostrar. Estes dois últimos parâmetros devem ser os mesmos da função do_meta_boxes que iremos ver em seguida.

function test_ui_metabox_content() {
	?>
	<p>Este é o conteúdo da metabox.</p>
	<?php
}

O código acima é a função que mostra o conteúdo da metabox e deve ser colocado também no nosso plugin. Agora só nos falta colocar o sitio para que apareçam as metaboxes. Isso é feito, como já referido em cima, através da função do_meta_boxes englobado em duas <div> com classes específicas:

<!-- Espaço para as metaboxes -->
<div class="metabox-holder">
	<div class="postbox-container">
		<div class="meta-box-sortables ui-sortable">
			<?php do_meta_boxes( 'plugin_test_ui', 'side', null ); ?>
		</div>
	</div>
</div>

Este código pode ser colocado no corpo do conteúdo da metabox. Agora as metaboxes irão aparecer na sua página.

No proximo artigo da série, parte 4, iremos falar sobre como usar o sistema de opções e a API de Settings do WordPress. A parte 5 será dedicada apenas à construção das tabelas como vemos no ecrã de listagem de posts para mostrar conteúdo que vamos buscar de duas fontes, do banco de dados e de uma API externa.

Até para a semana!