Como criar uma página de configurações no WordPress

Se você está criando um plugin do WordPress, pode estar se perguntando como criar uma página de configurações para ele. O WordPress oferece algum tipo de mecanismo “padrão” para isso? Existem novas ferramentas ou estruturas para criar páginas de configurações modernas? É uma boa ideia criar uma página de configurações? Bem, hoje vamos falar sobre tudo isso e vou responder suas perguntas.

Decisões, não Opções

WordPress é uma plataforma que visa democratizar a web. Esta declaração, que soa muito bem, mas ao mesmo tempo é muito abstrata, é uma maneira de dizer “queremos que qualquer pessoa possa usar o WordPress”. E, acredite ou não, as páginas de configurações podem ser, e de fato em muitos casos são, uma barreira para isso. Não acredite em mim? Bem, o próprio WordPress diz:

Ao tomar decisões, esses são os usuários que consideramos primeiro. Um ótimo exemplo dessa consideração são as opções de software. Toda vez que você dá uma opção a um usuário, você está pedindo que ele tome uma decisão. Quando um usuário não se importa ou não entende a opção, isso acaba levando à frustração. Como desenvolvedores, às vezes sentimos que fornecer opções para tudo é uma coisa boa, você nunca pode ter muitas opções, certo? Em última análise, essas escolhas acabam sendo técnicas, escolhas nas quais o usuário final médio não tem interesse. É nosso dever como desenvolvedores tomar decisões de design inteligentes e evitar colocar o peso das escolhas técnicas em nossos usuários finais.

Filosofia do WordPress

Portanto, antes de criar uma página de configurações, pense cuidadosamente nas opções que deseja oferecer aos usuários, por que deseja que eles tenham acesso a essas opções e se é necessário ou útil fazê-lo.

Filtros como alternativa

Mesmo sabendo que não devo oferecer muitas opções aos meus usuários, tenho que confessar que, como desenvolvedor, nem sempre é fácil para mim tomar uma decisão em vez de oferecer uma opção. Há momentos em que quero que meus usuários tenham a capacidade de escolher , embora eu saiba que as opções que estou expondo são complexas. Então o que eu faço nesses casos? Eu sigo a recomendação do WordPress e limito meus usuários avançados?

Felizmente, o WordPress oferece uma solução perfeita para esse dilema: filtros . Quando você projeta um plug-in e deseja que seus usuários (avançados) possam ajustar seu comportamento, não crie uma página de configurações ou algo assim. Em vez disso, torne seu plugin personalizável através do mecanismo de filtragem do WordPress.

Se você usar filtros, a maioria de seus usuários terá um comportamento padrão (“decisões”, lembra?), porque eles usarão o plug-in com os valores padrão definidos em seus filtros, enquanto os usuários avançados terão a capacidade de modificá-los decisões através de ganchos (e assim você também tem “opções”). O melhor de dois mundos!

Configurações do WordPress

Ok, agora que estamos cientes da importância de tomar decisões para nossos usuários e vimos como contornar essa limitação (se necessário) através de filtros, é hora de ver como podemos criar uma página de configurações no WordPress. Porque, sim: há momentos em que realmente precisamos dar aos nossos usuários a opção de tomar decisões de acordo com suas preferências.

API de configurações no WordPress

A API de configurações foi adicionada no WordPress versão 2.7. Trata-se de um conjunto de funções que padronizam a criação de páginas de configurações, permitindo definir quais opções estão disponíveis, qual será a interface do usuário para editar cada uma dessas opções (basicamente, campos em um formulário), e como validar, salvar , e recuperar seus valores.

Acho que a melhor maneira de aprender é através de exemplos, então vamos criar nossa primeira página de configurações usando a API de configurações passo a passo.

Criando uma nova página de configurações

A primeira coisa que você precisa fazer para criar uma página de configurações é (surpresa, surpresa!) criar uma página para exibir as configurações. Para isso, basta usar a função add_options_page durante a ação admin_menu e registrar a página:

 function nelio_add_settings_page() { add_options_page( 'Nelio Plugin Settings', 'Nelio', 'manage_options', 'nelio-example-plugin', 'nelio_render_settings_page' ); } add_action( 'admin_menu', 'nelio_add_settings_page' );

Como você pode ver, a única coisa que fazemos com esta função é registrar uma nova página que aparecerá no menu Configurações do WordPress, com seu título, o nome no menu, as permissões que o usuário deve ter para poder acessá-lo , e os ligado. O último argumento, nelio_render_settings_page , é o nome da função que se encarregará de renderizar a referida página:

 <?php function nelio_render_settings_page() { ?> <h2>Nelio Plugin Settings</h2> <form action="options.php" method="post"> <?php settings_fields( 'nelio_example_plugin_settings' ); do_settings_sections( 'nelio_example_plugin' ); ?> <input type="submit" name="submit" class="button button-primary" value="<?php esc_attr_e( 'Save' ); ?>" /> </form> <?php }

A própria página de configurações é relativamente fácil de criar. Basta adicionar um form cujo conteúdo será gerado de forma semiautomática pelo WordPress. Por um lado, invocamos a função settings_fields , que basicamente adiciona um nonce no formulário para torná-lo “seguro”. Em seguida, pedimos ao WordPress para renderizar todas as configurações que criamos para nosso plugin usando a função do_settings_sections . E, por fim, simplesmente adicionamos o botão Enviar o formulário.

Configurações reais em nossa página de configurações

Em seguida, devemos registrar cada uma das opções que farão parte de nossa página de configurações. Para isso, usaremos duas funções: register_setting , que permite indicar o nome com o qual salvaremos as configurações no banco de dados, e add_settings_field , que adiciona cada opção individual:

 function nelio_register_settings() { register_setting( 'nelio_example_plugin_settings', 'nelio_example_plugin_settings', 'nelio_validate_example_plugin_settings' ); add_settings_section( 'section_one', 'Section One', 'nelio_section_one_text', 'nelio_example_plugin' ); add_settings_field( 'some_text_field', 'Some Text Field', 'nelio_render_some_text_field', 'nelio_example_plugin', 'section_one' ); add_settings_field( 'another_number_field', 'Another Number Field', 'nelio_render_another_number_field', 'nelio_example_plugin', 'section_one' ); } add_action( 'admin_init', 'nelio_register_settings' );

O trecho de código anterior tem algumas coisas que merecem atenção especial. Por um lado, observe que a função register_setting tem como terceiro argumento: nelio_validate_example_plugin_settings . Este é o nome da função callback que será chamada para validar os valores que o usuário selecionou (lembre-se que você sempre tem que validar e higienizar seus campos de formulário). Essa função é algo assim:

 function nelio_validate_example_plugin_settings( $input ) { $output['some_text_field'] = sanitize_text_field( $input['some_text_field'] ); $output['another_number_field'] = absint( $input['another_number_field'] ); // ... return $output; }

onde recuperamos cada campo enviado de $input e o limpamos em $output para que tenhamos certeza de que, seja o que for que acabamos salvando no banco de dados, é válido e correto.

A segunda coisa que eu queria focar em você é o fato de que cada um dos campos que definimos também inclui uma referência de função que informa ao WordPress como cada campo deve ser renderizado. Por exemplo, os retornos de chamada dos campos em nosso exemplo podem ser algo assim:

 function nelio_section_one_text() { echo '<p>This is the first (and only) section in my settings.</p>'; } function nelio_render_some_text_field() { $options = get_option( 'nelio_example_plugin_settings' ); printf( '<input type="text" name="%s" value="%s" />', esc_attr( 'nelio_example_plugin_settings[some_text_field]' ), esc_attr( $options['some_text_field'] ) ); } function nelio_render_another_number_field() { $options = get_option( 'nelio_example_plugin_settings' ); printf( '<input type="number" name="%s" value="%s" />', esc_attr( 'nelio_example_plugin_settings[another_number_field]' ), esc_attr( $options['another_number_field'] ) ); }

Em essência, todos esses retornos de chamada fazem é recuperar o valor atual do campo que devem renderizar (com get_option ) e renderizar o HTML que permitirá ao usuário definir um valor ou outro (neste exemplo, um campo de input de digite text ou number ).

Qual é o resultado final, você está perguntando? Este:

Pensamentos finais

Como você pode ver, criar uma página de configurações é relativamente simples. Pessoalmente, não gosto muito de todo o processo, pois é bastante repetitivo e temos que escrever repetidamente o mesmo código clichê… mas é fácil mesmo assim.

Para simplificar ainda mais este processo, porém, existem alguns geradores de código online com os quais, através de uma interface de usuário simples, você pode definir os diferentes campos que deseja em sua página de configurações. Alguns exemplos são:

• API de configurações do WP
• Gerador de Páginas WordPressOption

E, claro, sempre há a possibilidade de criar uma página de configurações usando tecnologias como React… mas essa é uma história para outra época, não acha?

Imagem em destaque por Rima Kruciene no Unsplash.