Este artigo é a segunda 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 desta série.

Depois de abordado o básico sobre integração, criando a nossa primeira página, nesta segunda parte iremos falar de cada um dos elementos UI que podemos usar nas nossas páginas do WordPress.

Na primeira parte criámos uma plugin parapodemros criar a nossa página e testar as configurações e os elementos gráficos. Definimos o cabeçalho e um link para a nova página que fica por baixo das acções do plugin, e colocámos algumas coisas na nossa nova página. Tudo isso ficou assim:

<?php
/*
Plugin Name: Escola WP Teste UI
Version: 1.0
Author: Escola WP
Author URI: http://www.escolawp.com/
*/

// Inserir o link por baixo das acções do plugin
add_filter( 'plugin_action_links', 'my_plugin_settings_link', 10, 2 );
function my_plugin_settings_link( $links, $file ) {
    if ( $file == 'plugin-test-ui/plugin-test-ui.php' )
        $links['settings'] = sprintf( '<a href="%s"> %s </a>', admin_url( 'options-general.php?page=plugin-test-ui' ), __( 'Settings', 'plugin-test-ui' ) );
    return $links;

}

// Adicionar uma acção no menu da adminsitração
add_action( 'admin_menu', 'test_ui_submenu_page' );

function test_ui_submenu_page() {
    // Adicionar um submenu para a página do plugin onde iremos criar controladores
    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' ); 
}

// 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() {
    echo '<div class="wrap">';
    echo '<h3>Teste UI</h3>';
    echo '</div>';

}

Peguemos no exemplo acima e vamos tentar entender que elementos são necessários para que a nossa página fique consistente com todas as outras do WordPress. Primeiro que tudo, todas as páginas devem começar e acabar com uma div com a class wrap:

<div class="wrap">
   <!-- Coisas aqui -->
</div>

Esta classe define o espaço da tela que será usado como container e sem ele, a maior parte dos elementos do WordPress não mostram com o CSS nativo.

TÍTULOS DAS PÁGINAS

Seguidamente vamos criar um título e para isso é necessário remover a tag <h3> que colocámso anteriormente (apenas o fizemos antes para podermos analisar melhor ao pormenor os títulos neste capítulo.

Sprite dos ícones da administração

Os títulos são todos criados em h2 mas se queremos posicionar um ícone ou outros botões de acções ao lado, teremos que seguir várias regras. Como a nossa página é uma página de opções, vamos usar o ícone nativo de opções. Vamos então fazê-lo:

<div id="icon-options-general" class="icon32">
  <br>
</div>
<h2>Plugin de Teste UI</h2>

Usando uma div com o id icon-options-general, obtemos um ícone para este formato. Existem outros ids que podemos usar, para cada um dos ícones à escolha: icon-index, icon-edit, icon-upload, icon-edit-pages, icon-edit-comments, icon-themes, icon-plugins, icon-users e icon-tools.

Agora, depois de adicionado o ícone vamos criamos dois links fictícios ao lado do titulo. Para isso, usa-se a class add-new-h2 para cada um dos links que irão estar dentro da ta h2:

<h2>
	Plugin de Teste UI
	<a href="#" class="add-new-h2">Um link</a>
	<a href="#" class="add-new-h2">Outro link</a>
</h2>

Com isto obtemos um visual do cabeçalho da página consistente, parecido com o que temos visto nas outras páginas.

CORPO DA PÁGINA E FORMULÁRIO PRIMÁRIO

Como em todas as páginas de configurações, vamos precisar de criar um formulário para albergar todos os inputs, textareas e outros controladores para que estes sejam salvos nas opções do WordPress. NEsta parte apenas nos vamos preocupar com a criação dos elementos gráficos, sem nos preocuparmos ainda com a API de Settings do WordPress.

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

   <!-- Aqui vão os inputs -->

</form>

Esta é a estrutura principal da criação de formulários. Iremos tratar do resto mais à frente, quando tivermos oportunidade. Tudo o que vier a seguir estará dentro disto.

BOTÕES E LINKS

Botões e links no WordPress podem ser controlados facilmente através de classes. Temos os botões normais ou secundários e os botões principais ou primários. Eles devem ser usados em dois tipos de funcionalidades. Os principais quando há a necessidade de se ter um botão ou, quando há mais botões, para a acção por defeito. Os botões secundários devem ser usados noutras ocasiões.

Existem ainda um caso de acção que deve ser vista como excepção aqui: o caso de remover ou enviar para o lixo. Este não deve, por norma, ser um botão mas sim um link a vermelho.

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

	<!-- Aqui vão os inputs -->   
	<p class="submitbox">

		<input class="button button-primary" type="submit" name="botao1" value="Acção Principal" />
		<input class="button button-secundary" type="button" name="botao2" value="Acção Secundária" />
		<a href="#" class="submitdelete">Remover qualquer coisa</a>

	</p>

</form>

No código acima criámos os botões principais e secundários escrevendo diretamente o HTML dos seus inputs, porém, imaginemos que a comunidade decide por uma ou mais razões tornar as classes button-primarybutton-secundary obsoletas e criar novas, você terá que estar constantemente atento a esse tipo de pormenor, no entanto é um trabalho muito chato. É por isso que existem duas funções que fazem esse trabalho por nós: get_submit_button() submit_button(). Assim, reescrevendo o nosso código temos o seguinte:

<p class="submitbox">

	<?php submit_button( __( 'Acção Principal' ), 'primary', 'botao1', false ); ?>
	<?php submit_button( __( 'Acção Secundária' ), 'secondary', 'botao2', false ); ?>
	<?php submit_button( __( 'Remover qualquer coisa' ), 'delete', 'botao3', false ); ?>

</p>

AVISOS NO CABEÇALHO

Criar avisos no WordPress é muito simples, no entanto não deve ser programado directamente nas páginas de administração mas sim mostrados apenas quando é realmente necessário e exclusivamente nas páginas a que dizem respeito. Caso um aviso seja de cariz global, como por exemplo, de um erro geral ou algo que deve ser resolvido assim que possível ou que iniba que uma ou mais funcionalidades funcionem correctamente, então deve ser mostrado sempre.

O processo de criação e controlo destes avisos é muito simples. Você deve, por questões de performance, guardar na base de dados uma option sempre que detectar alguma anomalia que necessite de aviso e, assim que ela for resolvida, remover essa option. A função irá detectar se essa option existe e, se existir, exibe os avisos.

// Apresenta avisos
add_action( 'admin_notices', 'test_ui_admin_notices' );

function test_ui_admin_notices() {

	// Se a option não existir retorna a função sem fazer nada
	if ( 1 != get_option( 'test_ui_plugin_avisos', 1 ) )
		return;

	// Remover este if se os avisos devem aparecer em todas as páginas
	if ( 'settings_page_plugin-test-ui' == get_current_screen()->id ) {
		printf( '<div class="updated"><p>%s</p></div>', esc_html__( 'Aviso informativo ou de ugência média.' ) );
		printf( '<div class="error"><p>%s</p></div>', esc_html__( 'Aviso de perigo, urgência alta, que deve ser considerado o mais rápido possível.' ) );

	}

}

Para saber o ID da sua página (para poder usar na avaliação condicional) faça um var_dump() à propriedade id do objecto resultante da função get_current_screen():

var_dump( get_current_screen()->id );

DOWNLOAD DO FICHEIRO DO ARTIGO

Você poderá fazer o download do ficheiro do artigo através do ZIP.

Este foi o segundo artigo desta série. Neste momento você sabe tudo sobre elementos UI. No próximo artigo iremos falar de como criar tabelas através da API de tabelas do WordPress (iguais àquelas que listam os posts) e falaremos também um pouco sobre a estrutura de ficheiros CSS que o WordPress usa na administração e como modificá-la através da adição de novos ficheiros CSS e javascript para a nossa página.

Até para a semana!