8. Ajustes

WordPress prové una poderosa ‘suite’ de APIs y herramientas que los desarrolladores de plugins pueden emplear para hacer sus interfaces administrativas fáciles de construir, seguras, y consistentes con el diseño del resto del panel de administración.

Dos APIs de interés son la API Ajustes y la API Opciones. La primera, se basa en proveer una manera para que los desarrolladores creen formularios y gestionen los datos. La segunda se centra en gestionar los datos empleando un sistema simple clave/valor.

Los ajustes para temas y plugin se almacenan en la tabla prefijo_options. Las opciones se basan en un sistema estándar clave/valor, donde el valor puede ser una cadena, un entero o una matriz.

Las opciones de ajustes se graban y recuperan mediante la API Ajustes.

 

API Ajustes

La API Ajustes, añadida en WordPress 2.7, permite la administración de páginas contener formularios de ajustes que sean gestionados semi-automáticamente. Te deja definir páginas de ajustes, secciones dentro de las páginas y campos dentro de las secciones.

Se pueden registrar nuevas páginas se ajustes con secciones y campos dentro. Páginas de ajustes existentes pueden ser añadidas registrando nuevas secciones de ajustes o campos dentro de ellas.

Organizar el registro y validación de los campos todavía requiere algún esfuerzo por parte de los desarrolladores que emplean la API Ajustes, pero evita mucha depuración compleja de gestión de opciones subyacentes.

NOTA: Cuando se emplea la API Ajustes, el formulario de artículos wp-admin/options.php que provee bastantes prestaciones estrictas de verificación. Los usuarios necesitarán el permiso manage_options para enviar el formulario.

 

¿Por qué utilizar la API Ajustes?

Un desarrollador puede ignorar esta API y escribir su propia página de ajustes sin ella. Lo que lleva a la pregunta, ¿qué beneficios aporta esta API? A continuación un rápido repaso a algunos de los beneficios.

  • Consistencia visual

Al emplear la API para generar tus elementos de interfaz garantizas que tu página de ajustes se asimilará al resto de los elementos del panel de administración. ¿Has visto alguna vez una página de ajustes de un plugin que pareciera diseñado por un niño de 5 años? Puedes apostar que el desarrollador no utilizó la API. Entonces, un argumento de peso es que tu interface parezca como si perteneciera a, y gracias al equipo de diseñadores de WordPress, parezca increíble.

  • Robustez

Desde que la API forma parte del núcleo de WordPress, cualquier actualización automáticamente considerará la página de ajustes de tu plugin. Si tú creas tu propia interface, las actualizaciones del núcleo de WordPress pueden deteriorar tus personalizaciones. Hay también una amplia audiencia testeando y manteniendo el código de la API, luego tiende a ser más estable.

  • Ahorro de trabajo

Por supuesto el beneficio más inmediato es que la API de WordPress realiza mucho trabajo para tí encubierto. Unos pocos ejemplos de cosas que la API Ajustes hace además del increíble aspecto y el diseño integrado:

  • Manejo de envíos de formulario. Permite ue WordPress envíe datos recuperados y almacene tus envíos $_POST.
  • Incluir medidas de seguridad. Obtienes medidas extras de seguridad.
  • Limpieza de datos. Obtenes acceso a los mismos métodos que el resto de WordPress utiliza para asegurar que las cadenas son seguras.

 

Referencia de funciones

Setting Register/Unregister

Add Field/Section

Options Form Rendering

Errors

 

Crear y utilizar opciones

Añadir campos de ajustes

Puedes añadir nuevos campos de ajustes (básicamente, una opción en la tabla options de la base de datos, pero totalmente gestionada por ti) a las páginas de WordPress, utilizando esta función. Tu función de llamada de vuelta sólo necesita mostrar el input HTML apropiado y rellenarlo con el valor antiguo; el guardado se realizará de forma oculta. Puedes crear tus propias secciones en páginas existentes mediante add_settings_section() como se describe más adelante.

NOTA: Debes registrar cualquier opción que utilices mediante add_settings_field() o no se guardará y actualizará automáticamente. Ver más adelante para detalles y un ejemplo.

add_settings_field( $id, $title, $callback, $page, $section = ‘default’, $args = array() )

  • $id – Cadena a utilizar en el atributo ‘id’ de etiquetas.
  • $title – Título del campo.
  • $callback – Función que llena el campo con la entrada deseada como parte del formulario mayor. Nombre e id de la entrada deben ser iguales al $id dado a esta función. La función debe mostrar su salida.
  • $page – El tipo de página de ajustes en la cual mostrar el campo (general, writing, reading, discussion, media, privacy, y permalink).
  • $section – La sección de la página de ajustes en la que mostrar la caja (default o una sección añadida mediante add_settings_section).
  • $args – Argumentos adicionales.

 

Añadir secciones de ajustes

Secciones de ajustes son los grupos de ajustes que ves en la páginas de ajustes de WordPress con cabecera compartida. En tu plugin puedes añadir nuevas secciones a páginas de ajustes existentes en lugar de crear una página nueva entera. Esto hace tu plugin más fácil de mantener, y crea menos páginas nuevas que los usuarios deban aprender. Sólo les tienes que decir que deben cambiar los ajustes en las páginas existentes.

add_settings_section( $id, $title, $callback, $page )

  • $id – Cadena para emplear en el atributo ‘id’ de etiquetas.
  • $title – Título de la sección
  • $callback – Función que llena la sección con el contenido deseado. La función debe mostrar (echo) su valor de salida.
  • $page – El tipo de página de ajustes en la que se mostrará la sección (general, reading, writing, media, etc.).

 

Registrar un ajuste

La función register_setting define la opción actual que se guardarán los campos de ajuste.

register_setting( $settings_section, $option_name, $sanitize_callback )

unregister_setting( $option_group, $option_name, $sanitize_callback )

  • $settings_section – Nombre de grupo de ajustes. Suele corresponder al nombre clave de la opción de la lista blanca. Los nombres clave por defecto de las opciones de la lista blanca incluyen “general”, “discussion”, “reading” y otros. Utiliza este grupo cuando muestres una página de opciones.
  • $option_name – El nombe de una opción para sanear y guardar. Utiliza este nombre con funciones como get_option()update_option().
  • $callback – Función de llamada de vuelta que sanea el valor de la opción.

NOTA: register_setting() así como las funciones arriba mencionadas, add_settings_*(), deben ser llamadas desde una función de llamada de vuelta del gancho de acción ‘admin_init’. Ver ejemplo más adelante.

 

Usar tus ajustes

Tener los ajustes está bien y es bueno, pero ello no te ayudara hasta que puedas utilizarlos. Esto se consigue con la función get_option(). La función acepta dos parámetros: el nombre de la opción que tú elijas para recuperar y un valor opcional por defecto para dicha opción.

get_option( ‘wporg_setting_name’, false );

En este ejemplo, estás recuperando un ajuste denominado ‘wporg_setting_name’ y, si no hay nada guardado en este ajuste, get_option devolverá false. Probablemente no quieras recuperar las opciones así directamente, luego tu código podría parecerse más a esto:

$options = get_option( ‘wporg_setting_name’, false );

Ahora que has cargado los valores de las opciones en la variable $options tu puedes utilizar los ajustes en tu código. Aquí hay un ejemplo realístico en el que una página de opciones se utiliza:

En el ejemplo, se crea una página de opciones para un ajuste que es empleado para mostrar u ocultar información ‘meta’ bajo el contenido de un post. El ajuste se registra con register_setting y la función get_option se usa para recuperar el ajuste de la base de datos. Si quisieras añadir otro ajuste a esta página de opciones, debes utilizar el nombre de la sección de ajustes ‘wporg_options’ en tu llamada a register_settings así:

register_setting( ‘wporg_options’, ‘wporg_new_setting’ );

 

Opciones individuales frente a matrices de opciones

Las opciones se pueden guardar en la base de datos como opciones individuales o como matrices de opciones. Cuando se guardan como una opción individual, un valor único se guarda para una única clave dada. En el caso de una matriz de opciones, una clave dada se refiere a una matriz, dentro de la cual puede haber comprimidos un conjunto de pares clave/valor.

Si estás trabajando con una gran cantidad de opciones relacionadas, guardarlas como una matriz puede tener un impacto positivo sobre el rendimiento global. Acceder a los datos como opciones individuales puede resultar en muchas transacciones individuales a la base de datos, y como regla, las transacciones con la base de datos son operaciones ‘caras’ (en términos de tiempo y recursos del servidor). Un número pequeño de estas transacción no tendrá un alto impacto, pero realmente pueden sumar para conjuntos grandes de datos, especialmente cuando se añaden o modifican registros.

Es por ello que guardar datos en matriz es de tremenda utilidad. Cuando guardas o recuperas una matriz de opciones, lo haces en una única transacción, lo cual es ideal.

 

Guardar una matriz de opciones

Guardar una matriz es muy similar a guardar una opción simple.

Primero, crea la matriz:

Entonces, guarda la matriz como cualquier otra opción:

update_option( ‘my_plugin_options’, $array_of_options );

 

Recuperar una matriz de opciones

Aquí también recuperar la matriz de opciones trabaja justo como cualquier otra opción individual:

$array_of_options = get_option( ‘my_plugin_options’ );

Una vez recuperada, puedes seleccionar los valores individuales mediante las claves de la matriz:

 

Página de ajustes personales

A veces quieres crear un página de ajustes personales nueva para tu plugin, en lugar de insertar tus opciones en una página existente.

Para hacerlo, emplearás add_options_page.

 

Crear el Item de menu

El primer paso es crear un nuevo ítem de menú en la administración de WordPress. Mediante el siguiente código, verás un nuevo ítem bajo Settings llamado ‘My Plugin Menu Item’.

  • $page_title – El nombre mostrado en la barra de título del navegador, p.ej., My Plugin Title.
  • $menu_title – El nombre mostrado en el ítem del menú.
  • $capability – El permiso que el usuario necesita para modificar opciones de esta página, p.ej., manage_options.
  • $menu_slug – El slug que el admin de WordPress utiliza para identificar la página.
  • $function – La función de llamada de vuelta que muestra tu función personal de llamada de vuelta.

Esta función de llamada de vuelta aún no existe. Este es tu siguiente paso, que es lo que vas a hacer.

 

Crear la página

A continuación tienes una simple función, con la que podrás ver tu nueva página:

 

Crear las opciones

Hay tres componentes principales en la API de Ajustes: El ajuste, el campo y la sección.

Ahora que has creado tu página personal de opciones, sigue los mismos pasos que en Crear y utilizar opciones para añadir tus nuevos campos, salvo que ahora referenciarás my_options_page para el parámetro $page de la función add_settings_section.

 

Deja un comentario

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