Settings, de Runa Kruciene

Si estás creando un plugin para WordPress, es posible que te preguntes cómo crear una página de ajustes para el mismo. ¿Ofrece WordPress algún tipo de mecanismo «estándar» para ello? ¿Existen nuevas herramientas o frameworks con los que crear páginas de ajustes modernas? ¿Es una buena idea crear una página de ajustes? Pues hoy vamos a hablar de todo ello y voy a responder tus dudas.

Opciones, no. Decisiones.

WordPress es una plataforma que pretende democratizar la web. Esta afirmación, que suena muy bonita pero a la vez resulta muy abstracta, es una forma de decir «queremos que cualquier persona pueda usar WordPress». Y, lo creas o no, las páginas de ajustes pueden ser, y de hecho en muchos casos son, una barrera para ello. Pero, ojo, que esto no lo digo yo; lo dice el propio WordPress:

Cuando tomamos decisiones son los usuarios a los que primero tenemos en cuenta. Un gran ejemplo de esta consideración son las opciones de software. Cada vez que le das a un usuario una opción, le estás pidiendo que tome una decisión. Cuando a un usuario no le importa y no comprende la opción, esto al final lleva a la frustración. Como desarrolladores, a veces creemos que proporcionar opciones para todo es algo bueno, y nunca se pueden tener demasiadas opciones, ¿verdad? Al final, estas opciones terminan siendo técnicas, opciones que para el usuario final promedio no tienen interés. Nuestro deber como desarrolladores es tomar decisiones de diseño inteligentes y evitar poner el peso de las decisiones técnicas en nuestros usuarios finales.

Filosofía de WordPress

Así que, ya sabes, antes de crear una página de ajustes, piensa «muy mucho» qué opciones de configuración quieres dar a tus usuarios, por qué quieres darles la posibilidad de cambiar ciertos parámetros y si realmente es necesario o útil que puedan configurar esos parámetros.

Los filtros como alternativa

Tengo que confesar que, como desarrollador, no siempre me es fácil decidir por mis usuarios. Hay veces en las que quiero que mis usuarios tengan la capacidad de escoger, aunque soy consciente de que las opciones que debo mostrar son complicadas y decidir una opción u otra no está al alcance de todos. Entonces, ¿qué hago? ¿Sigo la recomendación de WordPress y limito a mis usuarios avanzados?

Por suerte, WordPress ofrece la posibilidad de implementar una solución perfecta a este dilema: los filtros. Cuando diseñes un plugin y quieras que tus usuarios (avanzados) puedan poder tunear su comportamiento, no crees una página de ajustes ni nada por el estilo. En lugar de ello, haz que tu plugin sea personalizable a través del mecanismo filtros de WordPress.

Usando filtros, la mayoría de tus usuarios disfrutarán de un comportamiento por defecto («decisiones», ¿recuerdas?), porque estarán usando el plugin con los valores por defecto que hay en tus filtros, mientras que los usuarios avanzados tendrán la posibilidad de modificar dichas decisiones a través de hooks («opciones»). ¡Lo mejor de ambos mundos!

Ajustes en WordPress

Vale, ahora que ya somos conscientes de la importancia de tomar decisiones por nuestros usuarios y de haber visto cómo saltarnos esta limitación a través de filtros, llega el momento de ver cómo podemos crear una página de ajustes en WordPress. Porque sí, hay veces en las que realmente necesitamos darle la opción al usuario de tomar decisiones según sus preferencias.

API de ajustes en WordPress

La API de ajustes se añadió en la versión 2.7 de WordPress. Se trata de un conjunto de funciones que estandarizan la creación de páginas de ajustes, permitiendo definir qué opciones hay disponibles, cuál será la interfaz de usuario para editar cada una de esas opciones (en esencia, campos en un formulario) y cómo validar, guardar y recuperar los valores que ha definido el usuario.

Creo que la mejor forma de aprender es a través de ejemplos, así que dejémonos de teoría y veamos cómo usar la API de ajustes paso a paso.

Añadir la página de ajustes

Lo primero que debes hacer para crear una página de ajustes es, ¡sorpresa!, crear una página donde se muestren los ajustes. Para ello, simplemente usa la función add_options_page durante la acción admin_menu y registra la 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' );

Tal y como puedes ver, lo único que hacemos con esta función es registrar una nueva página que aparecerá bajo el menú de Ajustes de WordPress, con su título, el nombre en el menú, los permisos que debe tener el usuario para poder acceder a ella, etc. El último parámetro que he puesto en la llamada, nelio_render_settings_page, es el nombre de la función que se encargará de pintar el contenido de dicha 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
}

La página de ajustes en si es relativamente sencilla de crear. Simplemente necesitamos añadir un formulario form cuyo contenido se generará de forma semi-automática por WordPress. Por un lado, invocamos la función settings_fields que básicamente sirve para meter un nonce en el formulario y hacerlo «seguro». A continuación, le pedimos a WordPress que pinte todas las opciones que hemos creado para nuestro plugin usando la función do_settings_sections. Y finalmente añadimos el botón para Guardar el formulario.

Opciones en nuestra página de ajustes

A continuación debemos registrar cada una de las opciones que formarán parte de nuestra página de ajustes. Para ello, usaremos dos funciones: register_setting, la cual nos permite indicar el nombre con el que guardaremos los ajustes en la base de datos, y add_settings_field para añadir cada uno de los campos:

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' );

En el fragmento de código anterior hay un par de puntos que merecen especial atención. Por un lado, fíjate que la función register_setting tiene como tercer parámetro la cadena de texto nelio_validate_example_plugin_settings. Esto se trata del nombre de la función de callback que se llamará para validar los valores que ha seleccionado el usuario (recuerda que siempre hay que validar y sanear los campos de los formularios que recibimos). Esta función es algo de este estilo:

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;
}

donde recuperamos cada campo de $input que nos interesa y lo saneamos para garantizar que, aquello que guardamos en la base de datos, es del tipo que nos conviene.

Por otro lado, cada uno de los campos que definimos incluye también una función específica que le dice a WordPress cómo debe pintarse dicho campo en la interfaz de usuario. Por ejemplo, los callbacks de los diferentes campos que hemos definido en nuestro ejemplo podrían ser tal que así:

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'] )
  );
}

donde vemos cómo, en esencia, lo único que hacemos es recuperar el valor actual de cada uno de los campos (con get_option) y pintamos el HTML con el elemento que permite modificar el valor al usuario (en nuestros ejemplos, un campo input de tipo text o number, por ejemplo).

Todo esto da como resultado algo tal que así:

Página de ajustes
Página de ajustes de ejemplo.

Reflexión final

Como ves, crear una página de ajustes es relativamente sencillo. En mi opinión, se trata de un proceso un poco repetitivo y aburrido, porque todos los campos son más o menos parecidos y al final acabas escribiendo el mismo código una vez, y otra, y otra.

Para simplificar aún más este proceso, existen generadores de código online en los que, a través de una sencilla interfaz de usuario, puedes definir los diferentes campos que quieres en tu página de ajustes y ellos ya te generarán todo el código que hemos estado viendo:

WP Settings API
El generador de código WP Settings API te permite crear fácilmente el esqueleto de tu página de ajustes.

Un par de ejemplos son:

Y, por supuesto, existe la posibilidad de crear una página de ajustes usando tecnologías como React… pero eso es algo que mejor dejamos para otro día, ¿no crees?

Imagen destacada de Rima Kruciene en Unsplash.

Deja una respuesta

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *

He leído y acepto la política de privacidad de Nelio Software

Tus datos personales se almacenarán en SiteGround y serán usados por Nelio Software con el único objetivo de publicar tu comentario aquí. Con el envío de este comentario, nos das el consentimiento expreso para ello. Escríbenos para acceder, rectificar, limitar o eliminar tus datos personales.