Guía de los shortcodes de WordPress

Qué son los shortcodes de WordPress

Los shortcodes son etiquetas especiales entre corchetes que el motor de WordPress sustituye automáticamente por contenido dinámico. Por ejemplo, [gallery] muestra una galería de imágenes, [video] incrusta un vídeo y [contact-form] muestra un formulario de contacto. Los shortcodes permiten a los usuarios sin conocimientos técnicos insertar contenido complejo en entradas y páginas simplemente escribiendo un código corto.

Los shortcodes integrados de WordPress cubren las necesidades básicas, pero la verdadera potencia proviene de la posibilidad de crear tus propios shortcodes. Los desarrolladores de plugins los utilizan para añadir funcionalidades como formularios, tablas de precios, carruseles y botones, mientras que los desarrolladores de temas usan shortcodes para elementos de diseño que se repiten. Entender el sistema de shortcodes es una habilidad importante para todo usuario y desarrollador de WordPress.

Shortcodes integrados de WordPress

WordPress incluye varios shortcodes integrados que cubren las necesidades multimedia básicas. Estos shortcodes funcionan de inmediato, sin necesidad de plugins adicionales, y admiten varios parámetros para personalizar la salida.

Lista de shortcodes integrados

• [caption] - añade un pie de foto debajo de la imagen con un marco estilizado
• [gallery] - muestra una galería de imágenes desde la biblioteca de medios con opciones de columnas y tamaño
• [audio] - incrusta un reproductor de audio con controles de reproducción
• [video] - incrusta un reproductor de vídeo con soporte para los formatos MP4, WebM y Ogg
• [playlist] - crea una lista de reproducción de audio o vídeo a partir de varios archivos
• [embed] - incrusta contenido de servicios externos mediante el protocolo oEmbed

El shortcode gallery en detalle

El shortcode gallery es el shortcode integrado que más se utiliza, porque permite crear galerías de imágenes rápidamente. Admite parámetros como ids para imágenes específicas, columns para el número de columnas, size para el tamaño de la imagen, orderby para la ordenación y link para determinar a dónde lleva el clic en la imagen. Por ejemplo, [gallery ids="1,2,3" columns="3" size="medium"] muestra tres imágenes concretas en tres columnas de tamaño mediano.

Creación de shortcodes personalizados

Crear tus propios shortcodes en el entorno de desarrollo de WordPress es sorprendentemente sencillo. Se utiliza la función add_shortcode(), que recibe dos argumentos: el nombre del shortcode y la función de retorno (callback) que devuelve el HTML que se mostrará. Añades esta función al functions.php de tu tema o a un plugin personalizado.

Estructura básica

La función de retorno recibe hasta tres parámetros: $atts (matriz de atributos que pasa el usuario), $content (contenido entre la etiqueta de apertura y la de cierre) y $tag (nombre del propio shortcode). La función debe devolver una cadena con HTML y nunca debe usar echo, porque eso rompería el orden de visualización en la página. Este es un error habitual de principiante que provoca que el contenido del shortcode aparezca en la parte superior de la página en lugar de en el lugar donde se insertó el shortcode.

Ejemplo de shortcode sencillo

Imagina que quieres un shortcode que muestre una cita destacada con el nombre del autor. En functions.php definirías una función que reciba atributos (autor, color) y contenido (texto de la cita) y devuelva un bloque HTML estilizado. El usuario escribiría en el editor [quote author="Miguel de Cervantes"]En un lugar de la Mancha...[/quote] y WordPress lo sustituiría por una cita con formato y con el nombre del autor debajo del texto.

Parámetros de los shortcodes

Los parámetros (atributos) hacen flexibles a los shortcodes, porque permiten a los usuarios personalizar la salida sin cambiar el código. Utiliza la función shortcode_atts() para definir valores predeterminados y combinarlos con los valores que ha pasado el usuario. Esto garantiza que el shortcode funcione incluso cuando el usuario no especifica todos los parámetros.

Tipos de parámetros

• Texto - título, color, clase, ID (p. ej., title="Título")
• Numérico - número de columnas, límite de resultados, anchura (p. ej., columns="3")
• Booleano - opciones sí/no (p. ej., show_date="true")
• Lista - IDs separados por comas (p. ej., ids="1,5,12,7")
• Enum - opciones predefinidas (p. ej., size="small|medium|large")

Valida y depura siempre los parámetros que pasa el usuario, porque los shortcodes pueden ser un vector de ataques XSS si la entrada del usuario se incrusta directamente en el HTML. Utiliza las funciones esc_attr(), esc_html() y wp_kses() para limpiar la salida. Convierte los parámetros numéricos a int con intval() y compara los parámetros booleanos con las cadenas true o false.

Shortcodes anidados

WordPress admite anidar shortcodes, lo que significa que puedes colocar un shortcode dentro de otro. Esto resulta útil para crear maquetaciones complejas en las que, por ejemplo, tienes un shortcode para una fila y, dentro de él, un shortcode para columnas. El contenido anidado se procesa llamando a la función do_shortcode() sobre el parámetro $content dentro de tu función de retorno.

Una limitación importante es que no puedes anidar el mismo shortcode dentro de sí mismo, porque el analizador de WordPress no puede distinguir correctamente las etiquetas de apertura y cierre. Si necesitas ese tipo de funcionalidad, crea variantes del shortcode con nombres diferentes, como [row] para la fila y [column] para la columna dentro de la fila. Esta limitación es intencionada y es poco probable que cambie en futuras versiones.

Ejemplo de anidamiento

Un ejemplo clásico es un shortcode de maquetación en el que [row] crea un contenedor flex o grid y [col width="6"] crea una columna de un ancho concreto. El usuario puede escribir [row][col width="4"]Columna izquierda[/col][col width="8"]Columna derecha[/col][/row] y obtener una maquetación de dos columnas. El shortcode row debe llamar a do_shortcode($content) para que WordPress procese los shortcodes col anidados antes de devolver el HTML final.

Shortcodes en el editor de bloques de WordPress

Con la introducción del editor de bloques Gutenberg, los shortcodes recibieron un bloque dedicado llamado Shortcode que acepta cualquier shortcode. Sin embargo, la tendencia en el desarrollo moderno de WordPress se inclina hacia sustituir los shortcodes por bloques personalizados que ofrecen una vista previa visual en el editor en lugar de texto en bruto entre corchetes. Para los proyectos nuevos, plantéate crear bloques en lugar de shortcodes, pero para los sitios existentes los shortcodes siguen estando totalmente soportados y operativos.

Cuándo usar shortcodes y cuándo bloques

• Los shortcodes son mejores para inserciones sencillas (cita, botón, icono)
• Los bloques son mejores para elementos de maquetación complejos con visualización gráfica
• Los shortcodes funcionan en el editor clásico y en el de bloques
• Los bloques funcionan solo en el editor de bloques (Gutenberg)
• Los shortcodes son más rápidos de desarrollar; los bloques requieren conocimientos de JavaScript
• Para la compatibilidad con plugins, los shortcodes son más universales

Consejos prácticos y buenas prácticas

Nombra los shortcodes con el prefijo de tu tema o plugin para evitar conflictos con otros plugins. Por ejemplo, en lugar de [button] usa [beo_button], porque es menos probable que otro plugin utilice el mismo nombre. Añade documentación para cada shortcode que crees, incluyendo la lista de parámetros, los valores predeterminados y ejemplos de uso, porque sin documentación ni siquiera tú recordarás todas las opciones al cabo de unos meses.

Para los shortcodes más complejos que generan una cantidad considerable de HTML, utiliza el almacenamiento en búfer de salida (output buffering) o archivos de plantilla en lugar de la concatenación de cadenas. Esto hace que el código sea más legible y fácil de mantener. Cachea los resultados de los shortcodes que requieren consultas a la base de datos. Utiliza la herramienta de comprobación de velocidad usando la API de Transients, porque los shortcodes se ejecutan en cada carga de página y los shortcodes lentos pueden ralentizar el sitio de forma notable. Prueba siempre los shortcodes en distintos contextos, incluidos los widgets, los extractos y el canal RSS, porque su comportamiento puede variar.