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 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 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, criamos um plugin para podemros 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 ações do plugin, e colocamos 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>';
echo '<h3>Teste UI</h3>';
echo '</div>';

}

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

<div>
<!-- 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

Em seguida, vamos criar um título e para isso é necessário remover a tag <h3> que colocamos anteriormente (apenas o fizemos antes para podermos analisar melhor  os títulos neste capítulo.

 

Os títulos são todos criados em h2, mas se queremos posicionar um ícone ou outros botões de açõ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">
<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 criar dois links fictícios ao lado do título. 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="#">Um link</a>
<a href="#">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, vamos apenas 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 ação por padrão; já os botões secundários devem ser usados em outras ocasiões.

Existem ainda um caso de ação que deve ser vista como exceçã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 em 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>

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

</p>

</form>

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

Avisos no cabeçalho

 

Criar avisos no WordPress é muito simples, no entanto não deve ser programado diretamente 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 uma ou mais funcionalidades, então deve ser mostrado sempre.

O processo de criação e controle 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><p>%s</p></div>', esc_html__( 'Aviso informativo ou de ugência média.' ) );
printf( '<div><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 arquivo do artigo 

Você poderá fazer o download do arquivo do artigo através do ZIP, clicando neste link.

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 arquivos CSS que o WordPress usa na administração e como modificá-la através da adição de novos arquivos CSS e javascript para a nossa página.