Após criar um widget o próximo passo é adicionar algumas opções a ele, tornando-o mais flexível para o usuário final. Utilizando como exemplo o plugin de posts mais quentes, digamos que você tenha definido a quantidade de cinco posts para serem apresentados mas um usuário queira mostrar apenas três. Para essas situações utilizamos a seguinte função:

register_widget_control('Nome do Widget', 'sua_funcao_de_configuracao', 'largura', 'altura')

Formulário de configuração do Widget

Essa função permite configurar as opções de seu widget onde ‘Nome do Widget’ é o nome do widget que deseja configurar (o mesmo que informou em ‘register_sidebar_widget’), ‘sua_funcao_de_configuracao’ é a função que deve ser chamada para configurar o plugin e ‘largura’ e ‘altura’ são opcionais e se referem ao tamanho do formulário de configuração.

A sua função de configuração deve possuir um formulário com os campos de configuração e uma rotina para salvar esses dados no banco. O seu formulário não deve conter as tags ‘form’ nem ‘submit’, pois eles são acrescentados automáticamente pelo WordPress de forma a englobar todos os widgets.

Vamos ver uma forma fácil de implementar essa configuração:

function configurar_posts_mais_quentes()
{
  // Inicializa as variáveis necessárias
  $options = array();

  // Salvando as opções
  if($_POST['salvar_posts_mais_quentes'])
  {
    $opcoes['quantidade'] = (int) $_POST['quantidade_de_posts_mais_quentes'];

    // Valor padrão, caso nada tenha sido informado
    if(empty($opcoes['quantidade'])) $opcoes['quantidade'] = 5;

    update_option('posts_mais_quentes', $opcoes);
  }

  // Carregar as opções desse widget
  $opcoes = get_option('posts_mais_quentes');

  // Formulário
  ?>
    <input type="hidden" name="salvar_posts_mais_quentes" value="1" />

    <p>
      <label for="quantidade_de_posts_mais_quentes">Quantidade:</label>
      <input type="text" name="quantidade_de_posts_mais_quentes" maxlength="2" value="<?php print $opcoes['quantidade']; ?>" class="widefat" />
    </p>
  <?php
}

Explicando… começando na linha 18 ($opcoes = get_option(‘posts_mais_quentes’)) carrega as opções desse widget do banco. Notem que usei a tabela ‘options’ do banco do WordPress para salvar as opções do plugins, como foi explicado no post plugins e banco de dados.

Agora vamos para o início do formulário na linha 22, onde adiciono um campo oculto (<input type=”hidden” name=”salvar_posts_mais_quentes” value=”1″ />) apenas para ter controle quando o formulário for enviado. Também adicionei um campo de texto na linha 26 (<input type=”text” name=”quantidade_de_posts_mais_quentes” maxlength=”2″ value=”<?php print $opcoes['quantidade']; ?>” class=”widefat” />) para que o usuário possa informar a quantidade de posts que devem aparecer em seu widget.

Voltando para a linha 7, analizo se o formulário foi enviado, checando se o campo oculto foi informado, então valido o dado recebido do formulário ($opcoes['quantidade'] = (int) $_POST['quantidade_de_posts_mais_quentes']) e, finalmente, salvo as informações no banco (update_option(‘posts_mais_quentes’, $opcoes)). Notem também que as informações desse widget foram salvas como array, assim é possível armazenar todas as configurações em um único local, poupando quantidade de acesso ao banco e organizando os dados.

Tentei montar esse formulário da forma mais simples possível, além disso coloquei alguns comentários para facilitar o entendimento.

Mas não é só isso, depois de salvar as configurações desse widget ainda falta carregá-las na hora de montar o widget:

function posts_mais_quentes($args)
{
  global $wpdb;

  // Carregar as opções desse widget
  $opcoes = get_option('posts_mais_quentes');

  // Recuperando os posts
  $hot_posts = $wpdb->get_results("SELECT ID, post_title, comment_count FROM {$wpdb->posts} ORDER BY comment_count DESC LIMIT {$opcoes['quantidade']}");

  // Usando o modelo de widgets do tema
  print $args['before_widget'];
  print $args['before_title'] . "Mais Quentes" . $args['after_title'];
  print "<ul>";

  // Listando os posts mais quentes
  foreach($hot_posts as $hot_post)
    print "<li><a href='" . get_permalink($hot_post->ID) . "'>{$hot_post->post_title} ({$hot_post->comment_count})</a></li>";

  print "</ul>";
  print $args['after_widget'];
}

Essa função é a mesma do post anterior com duas pequenas alterações. Uma na linha 6, onde carrego as configurações salvas e na linha 9 onde uso a quantidade de posts informadas pelo usuário para limitar a consulta (LIMIT {$opcoes['quantidade']}).

É isso… crie novas possibilidades para seus widgets, os usuários finais possuem sempre gostos diversos, simplifique a vida deles. Abaixo coloco o código completo desse estudo com uma opção a mais para a escolha do título do widget.

<?php
/*
Plugin Name: Posts mais quentes
Description: Lista posts mais comentados
Version: 0.2
Author: Marcelo Mesquita
Author URI: http://www.marcelomesquita.com/
*/

// Posts Mais Quentes
function posts_mais_quentes($args)
{
  global $wpdb;

  // Carregar as opções desse widget
  $opcoes = get_option('posts_mais_quentes');

  // Valor padrão, caso nada tenha sido informado
  if(empty($opcoes['quantidade'])) $opcoes['quantidade'] = "5";

  // Recuperando os posts
  $hot_posts = $wpdb->get_results("SELECT ID, post_title, comment_count FROM {$wpdb->posts} ORDER BY comment_count DESC LIMIT {$opcoes['quantidade']}");

  // Usando o modelo de widgets do tema
  print $args['before_widget'];
  print $args['before_title'] . $opcoes['titulo'] . $args['after_title'];
  print "<ul>";

  // Listando os posts mais quentes
  foreach($hot_posts as $hot_post)
    print "<li><a href='" . get_permalink($hot_post->ID) . "'>{$hot_post->post_title} ({$hot_post->comment_count})</a></li>";

  print "</ul>";
  print $args['after_widget'];
}

// Configurações dos Posts Mais Quentes
function configurar_posts_mais_quentes()
{
  // Inicializa as variáveis necessárias
  $opcoes = array();

  // Salvando as opções
  if($_POST['salvar_posts_mais_quentes'])
  {
    $opcoes['titulo'] = $_POST['titulo_dos_posts_mais_quentes'];
    $opcoes['quantidade'] = (int) $_POST['quantidade_de_posts_mais_quentes'];

    // Valor padrão, caso nada tenha sido informado
    if(empty($opcoes['quantidade'])) $opcoes['quantidade'] = "5";

    update_option('posts_mais_quentes', $opcoes);
  }

  // Carregar as opções desse widget
  $opcoes = get_option('posts_mais_quentes');

  // Formulário
  ?>
    <input type="hidden" name="salvar_posts_mais_quentes" value="1" />

    <p>
      <label for="titulo_dos_posts_mais_quentes">Título:</label>
      <input type="text" name="titulo_dos_posts_mais_quentes" maxlength="26" value="<?php print $opcoes['titulo']; ?>" class="widefat" />
      <label for="quantidade_de_posts_mais_quentes">Quantidade:</label>
      <input type="text" name="quantidade_de_posts_mais_quentes" maxlength="2" value="<?php print $opcoes['quantidade']; ?>" class="widefat" />
    </p>
  <?php
}

// Ativar o widget
function posts_mais_quentes_widgets()
{
  // Adicionar o widget
  register_sidebar_widget('Posts Mais Quentes', 'posts_mais_quentes');

  // Adicionar o controle ao widget
  register_widget_control('Posts Mais Quentes', 'configurar_posts_mais_quentes');
}

// Carregar o widget
add_action('widgets_init', 'posts_mais_quentes_widgets');
?>

Boa sorte!