7. Shortcodes

En aras de la seguridad de tu sitio, WordPress no te permite añadir código PHP en un artículo. Esto previene al usuario de ejecutar código accidentalmente que podría inhabilitar el sitio o que dejara de funcionar correctamente. Pero tú puedes querer permitir a los usuarios incluir contenido dinámico que requiera emplear PHP para realizar una tarea. Para hacerlo, debes emplear los shortcodes.

Un shortcode es parecido a una macro, dónde una simple instrucción puede realizar cierto número de tareas. Brevemente, un shortcode actúa como un atajo que puede utilizarse para representar una galería de imágenes, una lista de artículos, un formulario de contacto, …

 

¿Porqué shortcodes?

Los shortcodes son una manera valiosa de mantener el contenido limpio y semántico, y permite a los usuarios finales modificar la presentación del contenido con código pre-programado.

 

Shortcodes pre-establecidos

Por defecto, WordPress ofrece los siguientes shortcodes:

  • caption
  • gallery
  • audio
  • video
  • playlist
  • embed

Añadir shortcodes

Como mínimo, utilizar la API Shortcode implica registrar tanto un shortcode como una función de llamada de vuelta con add_shortcode(). Está claro que estás permitiendo al usuario final emplear funciones PHP dentro del contenido del artículo, pero de una forma más segura y protegida.

 

Parámetros

Las funciones add_shortcode() pueden recibir hasta tres parámetros:

  • $atts – Una matriz asociativa de atributos, o una cadena vacía si no se aportan atributos.
  • $content – El contenido interior (si el shortcode funciona sobre contenido).
  • $tag – La etiqueta del shortcode actual, útil para funciones compartidas.

 

Buenas prácticas

Las mejores prácticas para el desarrollo de shortcodes son similares a las ‘Buenas prácticas’ vistas en el artículo ‘2. Conceptos básicos de los plugins‘ de esta serie.

  • Devuelve la salida, no la imprimas (echo). Los shortcodes son esencialmente filtros, por lo que enviar salida o alterar variables globales puede generar bugs difíciles de detectar.
  • Prefija los nombres de tus shortcodes, para evitar conflictos con otros elementos.
  • Limpia la entrada y ‘escapea’ la salida.
  • Ofrece a los usuarios documentación clara de los atributos de los shortcodes.

 

Conceptos básicos de los shortcodes

Registrar un shortcode en un Tema

En un tema los shortcodes se registran con WordPress declarándolos y asignándoles una llamada de vuelta:

 

Registrar un shortcode en un Plugin

Para ello, hay que enganchar el registro del shortcode a init.

 

Shortcodes ‘encapsulados’

Si un shortcode se utiliza para encapsular contenido, su función recibirá un segundo parámetro, que contendrá el contenido. Los usuarios pueden escribir los shortcodes en cualquier forma, por lo que es necesario permitir para cualquier caso, asignando un valor por defecto para el segundo parámetro de la función.

function my_shortcode_handler( $atts, $content = null )

is_null( $content ) se puede emplear para distinguir entre los casos en que exista o no contenido.

Cuando el contenido está encapsulado, todo el shortcode, incluyendo el contenido, será reemplazado con la salida de la función. Es responsabilidad de la función proveer el retorno de la salida.

Ejemplo trivial de shortcode encapsulado:

Si se emplea así:

el resultado será

My Caption

Sin embargo,

resultará

My Caption

 

Utilizar shortcodes en otros shortcodes

Para conseguir que se ejecuten shortcodes dentro de otros, la función debe llamar do_shortcode() recursivamente:

 

Trampas

El analizador no se encarga de mezclar formas encapsuladas y no encapsuladas del mismo shortcode como tu querrías. Por ejemplo, si tú tienes:

En lugar de tratar como dos shortcodes separados por el texto “non-enclosed content”, el analizador lo trata como un solo shortcode, dando el resultado: “non-enclosed content [myshortcode] enclosed content”.

Los shortcodes encapsulados soportan los atributos también. Aquí hay un ejemplo de shortcode que soporta un atributo ‘class’:

 

Shortcodes con parámetros

Los shortcodes también pueden tener parámetros de configuración conocidos como atributos. Un shortcode con un par de atributos podría parecerse a esto:

[pull-quote quote=”This is my quote!” attribution=”Will Smith”]

La función para crear este shortcode y usar ambos atributos, sería así:

La función shortcode_atts selecciona valores por defecto, y entonces acepta la variable de entrada $atts. Una matriz de elementos en $atts sobre-escribirá los valores por defecto establecidos en la función shortcode_atts.

Esto significa que si sólo escribimos [pull-quote]

Obtendremos el siguiente bloque HTML:

Y si escribimos el ejemplo inicial:

NOTA IMPORTANTE: Los nombres de los atributos de $atts deben ser COMPLETAMENTE EN MINUSCULAS.

 

Shortcodes mejorados TinyMCE

Es posible analizar shortcodes dentro del editor visual TinyMCE y ejecutarlos en el propio editor.

  • El shortcode “audio” permite insertar un fichero de audio.
  • El shortcode “caption” inserta una imagen en un div y pone una etiqueta debajo de la imagen.
  • El shortcode “gallery” permite insertar varias imágenes a la vez.
  • El shortcode “playlist” te permite adjuntar mas de un fichero de medios (sonido y vídeo) y ejecutarlos.
  • El shortcode “video” es equivalente a “audio” pero con un fichero de video.

 

Deja un comentario

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