Cómo crear una página de configuración en WordPress

Si está creando un complemento de WordPress, es posible que se pregunte cómo crear una página de configuración para él. ¿WordPress ofrece algún tipo de mecanismo “estándar” para esto? ¿Hay nuevas herramientas o marcos con los que crear páginas de configuración modernas? ¿Es una buena idea crear una página de configuración? Bueno, hoy vamos a hablar de todo esto y voy a responder a sus preguntas.

Decisiones, no Opciones

WordPress es una plataforma que tiene como objetivo democratizar la web. Esta afirmación, que suena muy bien pero a la vez es muy abstracta, es una forma de decir “queremos que cualquiera pueda usar WordPress”. Y, créalo o no, las páginas de configuración pueden ser, y de hecho en muchos casos son, una barrera para eso. ¿No me crees? Bueno, el propio WordPress lo dice:

Al tomar decisiones, estos son los usuarios que consideramos primero. Un gran ejemplo de esta consideración son las opciones de software. Cada vez que le das una opción a un usuario, le estás pidiendo que tome una decisión. Cuando a un usuario no le importa o no entiende la opción, esto finalmente lo lleva a la frustración. Como desarrolladores, a veces sentimos que brindar opciones para todo es algo bueno, nunca hay demasiadas opciones, ¿verdad? En última instancia, estas opciones terminan siendo técnicas, opciones en las que el usuario final promedio no tiene ningún interés. Es nuestro deber como desarrolladores tomar decisiones de diseño inteligentes y evitar poner el peso de las opciones técnicas en nuestros usuarios finales.

Filosofía de WordPress

Por lo tanto, antes de crear una página de configuración, piense detenidamente en las opciones que desea brindar a sus usuarios, por qué desea que tengan acceso a esas opciones y si es necesario o útil hacerlo.

Filtros como alternativa

Aunque sé que se supone que no debo ofrecer demasiadas opciones a mis usuarios, debo confesar que, como desarrollador, no siempre es fácil para mí tomar una decisión en lugar de ofrecer una opción. Hay momentos en los que quiero que mis usuarios tengan la posibilidad de elegir , aunque soy consciente de que las opciones que expongo son complejas. Entonces, ¿qué hago en estos casos? ¿Sigo la recomendación de WordPress y limito mis usuarios avanzados?

Afortunadamente, WordPress ofrece una solución perfecta a este dilema: los filtros . Cuando diseñe un complemento y desee que sus usuarios (avanzados) puedan ajustar su comportamiento, no cree una página de configuración ni nada por el estilo. En su lugar, haga que su complemento sea personalizable a través del mecanismo de filtrado de WordPress.

Si usa filtros, la mayoría de sus usuarios disfrutarán de un comportamiento predeterminado ("decisiones", ¿recuerdan?), porque usarán el complemento con los valores predeterminados establecidos en sus filtros, mientras que los usuarios avanzados tendrán la capacidad de modificar estos decisiones a través de ganchos (y así también tienes “opciones”). ¡Lo mejor de ambos mundos!

Configuración de WordPress

Bien, ahora que somos conscientes de la importancia de tomar decisiones para nuestros usuarios y hemos visto cómo eludir esta limitación (si es necesario) a través de filtros, es hora de ver cómo podemos crear una página de configuración en WordPress. Porque, sí: hay momentos en los que realmente necesitamos dar a nuestros usuarios la opción de tomar decisiones de acuerdo con sus preferencias.

API de configuración en WordPress

La API de configuración se agregó en la versión 2.7 de WordPress. Este es un conjunto de funciones que estandarizan la creación de páginas de configuración, lo que le permite definir qué opciones están disponibles, cuál será la interfaz de usuario para editar cada una de esas opciones (esencialmente, campos en un formulario), y cómo validar, guardar y recuperar sus valores.

Creo que la mejor manera de aprender es a través de ejemplos, así que vamos a crear nuestra primera página de configuración usando la API de configuración paso a paso.

Creación de una nueva página de configuración

Lo primero que debe hacer para crear una página de configuración es (¡sorpresa, sorpresa!) crear una página para mostrar la configuración. Para hacer esto, simplemente use la función add_options_page durante la acción admin_menu y registre 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' );

Como puedes ver lo único que hacemos con esta función es dar de alta una nueva página que aparecerá en 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. , y os encendido. El último argumento, nelio_render_settings_page , es el nombre de la función que se encargará de renderizar 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 configuración en sí es relativamente fácil de crear. Simplemente necesitamos agregar un form cuyo contenido será generado semiautomáticamente por WordPress. Por un lado, invocamos la función settings_fields , que básicamente agrega un nonce en el formulario para hacerlo “seguro”. A continuación, le pedimos a WordPress que presente todas las configuraciones que hemos creado para nuestro complemento usando la función do_settings_sections . Y, por último, simplemente añadimos el botón Enviar el formulario.

Configuración real en nuestra página de configuración

A continuación, debemos registrar cada una de las opciones que formarán parte de nuestra página de configuración. Para ello, utilizaremos dos funciones: register_setting , que nos permite indicar el nombre con el que guardaremos la configuración en la base de datos, y add_settings_field , que añade cada opción 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' );

El fragmento de código anterior tiene un par de cosas que merecen especial atención. Por un lado, fíjate que la función register_setting tiene como tercer argumento: nelio_validate_example_plugin_settings . Este es el nombre de la función de devolución de llamada que se llamará para validar los valores que el usuario ha seleccionado (recuerde que siempre debe validar y desinfectar los campos de su formulario). Esta función es algo como esto:

 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 enviado de $input y lo desinfectamos en $output para que sepamos con certeza que, sea lo que sea que terminemos guardando en la base de datos, es válido y correcto.

La segunda cosa en la que quería centrarme es en el hecho de que cada uno de los campos que definimos también incluye una referencia de función que le dice a WordPress cómo se debe representar cada campo. Por ejemplo, las devoluciones de llamada de los campos en nuestro ejemplo podrían ser algo como esto:

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

En esencia, todo lo que hacen estas devoluciones de llamada es recuperar el valor actual del campo que se supone que deben representar (con get_option ) y generar el HTML que permitirá al usuario establecer un valor u otro (en este ejemplo, un campo de input de escriba text o number ).

¿Cuál es el resultado final, usted pregunta? Esta:

Pensamientos finales

Como puede ver, crear una página de configuración es relativamente simple. Personalmente, no soy muy aficionado a todo el proceso, ya que es bastante repetitivo y tenemos que escribir una y otra vez el mismo código repetitivo... pero no obstante es fácil.

Sin embargo, para simplificar aún más este proceso, existen algunos generadores de códigos en línea con los que, a través de una interfaz de usuario simple, puede definir los diferentes campos que desea en su página de configuración. Un par de ejemplos son:

• API de configuración de WP
• Generador de página de opciones de WordPress

Y, por supuesto, siempre existe la posibilidad de crear una página de configuración usando tecnologías como React… pero esta es una historia para otra época, ¿no crees?

Imagen destacada de Rima Kruciene en Unsplash.