personalizador

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.

Método 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.

<?php

$wp_customize->add_panel( 'panel_id', array(
  'priority' => 160,
  'capability' => 'edit_theme_options',
  'theme_supports' => '',
  'title' => 'título',
  'description' => 'descripción,
) );

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:

Title Priority
Site Title & Tagline 20
Colors 40
Header Image 60
Background Image 80
Navigation 100
Widgets (Panel) 110
Static Front Page 120
default 160

Método 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:

<?php

$wp_customize->add_section( 'section_id' , array(
  'title' => 'título',
  'description' => 'descripción',
  'panel' => 'panel_id',
  'priority' => 1,
  'capability' => 'edit_theme_options',
  'active_callback' => '',
  'theme_supports' => '',
));

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)

Método para añadir Settings

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

<?php

$wp_customize->add_setting( 'setting_id', array(
  'type' => 'theme_mod', // or 'option'
  'capability' => 'edit_theme_options',
  'theme_supports' => '',
  'default' => '',
  'transport' => 'refresh', // or postMessage
  'sanitize_callback' => '',
  'sanitize_js_callback' => '',
) );

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

Método para añadir Controls

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

<?php

$wp_customize->add_control( 'setting_id', array(
  'type' => 'text',
  'priority' => 1,
  'section' => 'section_id',
  'label' => 'título',
  'description' => 'descripción',
  'input_attrs' => array(
    'class' => 'my-custom-class',
    'style' => 'border: 1px solid #900',
    'placeholder' => 'placeholder',
  ),
  'active_callback' => 'is_front_page',
  'choices' => array()
) );

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:

<?php

function my_customize_register( $wp_customize ) {
  $wp_customize->add_panel( 'my_custom_options', array(
    'title' => __( 'Mis Opciones', 'textdomain' ),
    'priority' => 160,
    'capability' => 'edit_theme_options',
  ));

  // Section para Google Analytics
  $wp_customize->add_section( 'google_analytics_section' , array(
    'title' => __( 'Google Analytics', 'textdomain' ),
    'panel' => 'my_custom_options',
    'priority' => 1,
    'capability' => 'edit_theme_options',
  ));

  // Section para Redes Sociales
  $wp_customize->add_section( 'social_section' , array(
    'title' => __( 'Redes Sociales', 'textdomain' ),
    'panel' => 'my_custom_options',
    'priority' => 2,
    'capability' => 'edit_theme_options',
  ));

  //Google Analytics
  $wp_customize->add_setting( 'my_google_analytics', array(
    'type' => 'theme_mod',
    'capability' => 'edit_theme_options',
  ));

  $wp_customize->add_control('my_google_analytics', array(
    'label' => __( 'Código de Google Analytics', 'textdomain' ),
    'section' => 'google_analytics_section',
    'priority' => 1,
    'type' => 'textarea',
  ));

  //Redes Sociales: Facebook
  $wp_customize->add_setting( 'my_facebook_url', array(
    'type' => 'option',
    'capability' => 'edit_theme_options',
  ));

  $wp_customize->add_control('my_facebook_url', array(
    'label' => __( 'Facebook URL', 'textdomain' ),
    'section' => 'social_section',
    'priority' => 1,
    'type' => 'text',
  ));

  //Redes Sociales: Twitter
  $wp_customize->add_setting( 'my_twitter_url', array(
    'type' => 'option',
    'capability' => 'edit_theme_options',
  ));

  $wp_customize->add_control('my_twitter_url', array(
    'label' => __( 'Twitter URL', 'textdomain' ),
    'section' => 'social_section',
    'priority' => 2,
    'type' => 'text',
  ));

  //Redes Sociales: Google Plus
  $wp_customize->add_setting( 'my_googleplus_url', array(
    'type' => 'option',
    'capability' => 'edit_theme_options',
  ));

  $wp_customize->add_control('my_googleplus_url', array(
    'label' => __( 'Google Plus URL', 'textdomain' ),
    'section' => 'social_section',
    'priority' => 3,
    'type' => 'text',
  ));
}
add_action( 'customize_register', 'my_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:

<?php

//Add Google Analytics Code
if (get_option('my_google_analytics')) {
  function add_google_analytics_code() {
    echo get_option('my_google_analytics');
  }
  add_action( 'wp_head', 'add_google_analytics_code' );
}

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.

¿Te ha resultado útil esta información? 🍺

Si este post te ha resuelto un problema, invítame a un café o a una cerveza. Con este pequeño gesto me animas a seguir escribiendo.

Comentarios

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

  1. Hola,
    ¿Cómo puedo tener un contenido por defecto en el textarea? , o que el contenido que tenga el componente en el textarea pueda ser traducido
    Gracias

Deja un comentario

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

  • El fin del tratamiento es únicamente la moderación de comentarios para evitar spam
  • La legitimación es tu consentimiento al comentar
  • No se comunicará ningún dato a terceros salvo por obligación legal
  • Tienes derecho al acceso, rectificación y eliminación de los comentarios