Theme Customization API: Cómo añadir nuestras propias opciones en el personalizador de WordPress

El personalizador de WordPress fue añadido en la versión 3.4, y te permite de una forma visual hacer y ver cómo quedan los cambios que realices en sus opciones.

Por defecto puedes cambiar el título y descripción del blog, el Site Icon, gestionar los menús, los widgets, y últimamente los desarrolladores de temas están dándole mucha importancia a esta característica añadiendo multitud de opciones de configuración del tema.

En la próxima versión, la WordPress 4.5, se van a incorporar mejoras dentro del personalizador, lo que nos da una idea de la importancia que está tomando de cara al futuro.

WordPress pone a disposición de los desarrolladores la Theme Customization API, es decir, una API para poder integrar nuestras propias opciones en nuestros desarrollos a medida tanto de temas como de plugins. Vamos a ver en un ejemplo cómo añadir una opción dentro del personalizador para incluir nuestro código de google analytics y enlaces a nuestras redes sociales.

Lo primero de todo es saber que las opciones del personalizador están disponibles por defecto sólo para usuarios administradores, aunque permite habilitarlas para usuarios de roles inferiores.

La API está orientada a objetos. Existen 4 tipos principales de objetos para el personalizador: Panels, Sections, Settings y Controls. Los Settings son las variables que utilizamos para guardar datos y los Controls son su representación gráfica. Podemos tener tantos Settings como queramos y agruparlos dentro de una misma Section para una correcta organización. Y los Panels son para agrupar Sections dentro de un mismo elemento.

tipos de objetos personalizador
Cada objeto de los anteriormente mencionados dispone de una clase PHP propia para añadir, modificar o borrar. Nos serviremos del hook customize_register para trabajar con ellos.

 

Clase para añadir Panels

Los Panels nos permiten agrupar “Sections”. Fueron introducidos en la versión 4.0 y no son obligatorios, es sólo una funcionalidad más que nos permite tener mejor organizadas nuestras opciones dentro del personalizador.

add_panel admite dos parámetros. El primero es el ID del panel y el segundo un array de opciones donde donde:

  • title: Titulo visible de nuestro Panel
  • description: Descripción de nuestro Panel (opcional)
  • priority: Orden en el que aparecerá nuestro Panel dentro del Personalizador
  • capability: Donde establecemos los permisos para editar esta opción
  • theme_supports: Nos permite ocultar esta opción si el tema soporta alguna característica específica (post-formats, post-thumbnails, custom-background, custom-header, automatic-fedd-links, html5, title-tag, editor-style, widgets, menus)

 

En cuanto a las prioridades, por defecto estas son las que existen:

TitlePriority
Site Title & Tagline20
Colors40
Header Image60
Background Image80
Navigation100
Widgets (Panel)110
Static Front Page120
default160

 

Clase para añadir Sections

Recordamos que las Sections son los elementos gráficos que agrupan nuestras opciones. Para añadirlos lo haremos con add_section:

Como podemos ver, debemos pasar a add_section dos argumentos. El primero es el identificador único para nuestra Section, y el segundo un array de variables donde:

  • title: Título visible de nuestra Section
  • description: Descripción de nuestra Section (opcional)
  • panel: Si nuestra Section va dentro de un Panel, indicaremos el ID del panel.
  • priority: Orden en el que aparecerá nuestra Section dentro del Panel al que pertenece y si no pertenece a ningún panel, orden dentro del personalizador.
  • capability: Donde establecemos los permisos para editar esta opción
  • active_callback: Éste argumento opcional nos permite mostrar u ocultar nuestra Section en función de la página en la que estemos.
  • theme_supports: Nos permite ocultar esta opción si el tema soporta alguna característica específica (post-formats, post-thumbnails, custom-background, custom-header, automatic-fedd-links, html5, title-tag, editor-style, widgets, menus)

 

Clase para añadir Settings

Los Settings son las opciones que guardaremos en base de datos.

add_setting acepta dos parámetros. El primero es el ID de nuestro Setting, y el segundo un array de valores donde:

  • type: Nos permite especificar el tipo: theme_mod u option
  • capability: Donde establecemos los permisos para editar esta opción
  • theme_supports: Nos permite ocultar esta opción si el tema soporta alguna característica específica (post-formats, post-thumbnails, custom-background, custom-header, automatic-fedd-links, html5, title-tag, editor-style, widgets, menus)
  • default: Nos permite establecer un valor por defecto para nuestra opción
  • transport: Si usamos JavaScript para la previsualización de nuestras opciones deberemos marcarla como postMessage.
  • sanitize_callback: Nos permite establecer el nombre de una función para sanitizar el valor del setting
  • sanitize_js_callback: Igual que la anterior pero si usamos JavaScript para la previsualización de nuestras opciones

 

Clase para añadir Controls

Los controls nos permiten establecer el tipo de dato de nuestras Settings, entre otras cosas:

add_control acepta dos parámetros. El primero es el ID del Setting al que está asociado y el segundo un array de valores donde:

  • type: Nos permite establecer el tipo de entrada: text, email, number, textarea, radio, checkbox, select…
  • priority: Prioridad dentro del Section
  • section: Section_id al que pertenece
  • label: Título
  • description: Descripción
  • input_attrs: array que nos permite definir una clase, estilo y placeholder de nuestro campo de entrada
  • active_callback: Éste argumento opcional nos permite mostrar u ocultar nuestra Section en función de la página en la que estemos
  • choices: array de valores que puede tener por ejemplo un campo de entrada de tipo select

 

En el ejemplo que he propuesto usaré un panel “Mis opciones” para agrupar mis sections “Google Analytics” y “Redes Sociales”. Dentro de la Sección Google Analytics dispondremos de un text area para introducir el código, y dentro de la sección Redes Sociales colocaremos 3 inputs para introducir las URLs de Facebook, Twitter y Google+. Añadiremos en el functions.php una función para crear estos elementos, y la anclaremos al action customize_register:

Ahora en el back-end de nuestro WordPress podremos dirigirnos a Apariencia => Personalizar y veremos nuestro panel “Mis Opciones”

Para mostrar automáticamente nuestro código de Google Analytics en el head de nuestro sitio, también dentro del functions.php agregaremos estas líneas:

Y para recuperar cualquiera de las URLs de redes sociales que hemos configurado para montar nuestra botonera por ejemplo en el header o footer, bastará con llamar a la función get_option() e indicar el ID de la opción que deseamos obtener desde el template correspondiente.

Si te ha gustado, valora este artículo para mejorar la calidad del blog o compártelo en Redes Sociales…
1 Star2 Stars3 Stars4 Stars5 Stars (4 votos, valoración 4,50 sobre 5) Loading...

Web Hosting