Cómo crear Shortcodes en WordPress con PHP

Hay posts que realmente disfruto a tope escribiéndolos. Éste es uno de esos porque trata un tema muy, pero que muy útil: aprender a añadir a WordPress tus propias funcionalidades.

Imagen de Pixabay - © jamesmarkosborne

Quizás la razón más importante para usar WordPress.org es que se puede extender y modificar hasta extremos inimaginables.

Seguramente ya seas muy consciente de la flexibilidad que ofrece esta plataforma gracias a la casi infinita cantidad de plugins y de temas de WordPress para personalizarlo a tu gusto.

Sin embargo, aun así, cuando tienes una necesidad muy específica, muchas veces no encuentras el plugin que la implementa exactamente como tú necesitas.

Muchas veces son cosas muy simples. Un ejemplo típico son los elementos gráficos conocidos como widgets que representan una información de una manera determinada. Por ejemplo: una cajita con un resumen de las características de un producto o servicio.

Para este tipo de cosas sencillas es la para lo que se han inventado los shortcodes y aquí te voy a enseñar cómo los puedes programar.

Lo que es muy importante es el hecho de que para aprovechar los shortcodes, lo suyo es que uses WordPress.org (que implica hosting propio).

En WordPress.com, de modo muy parecido a cómo ocurre con los temas, estás muy limitado: sólo dispones de un conjunto limitado de shortcodes que vienen de fábrica y que no puedes ampliar, salvo que contrates el plan más caro, que es mucho más caro que un hosting básico o mediado.

¿Qué son los “shortcodes” exactamente?

Los shortcodes de WordPress son unos códigos especiales muy simples que se marcan con corchetes de esta manera:

[código] o [código param1="valor1", param2="valor2"]

Los shortcodes funcionan de un modo muy parecido a las “macros” que quizás conozcas, por ejemplo, de las aplicaciones del paquete Office.

Es decir, ejecutan funciones determinadas, a veces prefabricadas, a veces implementadas por el propio usuario. En Office se implementan con las así llamadas herramientas de VBA, las siglas de “Visual Basic for Applications”, un lenguaje de programación propio de Microsoft.

En nuestro caso, los shortcodes también se programan, pero en el lenguaje de programación PHP que es el lenguaje en el que está hecho también WordPress y hay dos maneras: una sencilla pero limitada (sólo con HTML y JavaScript) y otra más avanzada que es programándolos en el lado servidor con PHP.

Aquí vamos a ver la manera más avanzada para lo cual lógicamente has de tener, al menos, unos conocimientos básicos de PHP.

Si nos es así, te dejo aquí un vídeo para que veas “de qué va” esto del PHP por si te planteas aprenderlo:

Pero OJO: este vídeo no sirve como curso completo de PHP. Lo he elegido porque te da una visión muy completa en muy poco tiempo de lo que es este lenguaje de programación, pero está demasiado condensado para que sirva realmente como un curso completo.

Por tanto, si te animas a aprender PHP, te recomiendo, o bien, que escojas un libro de PHP entre los mejor valorados en Amazon o elijas alguno de los cursos gratuitos que puedes encontrar en YouTube.

Para aprender en YouTube te recomiendo especialmente el material publicado en los canales de Falcon Masters y de Fazt Tech.

Y dentro de este aprendizaje te recomiendo también cuidar especialmente la elección de tu entorno de desarrollo, la aplicación con la que escribes el código fuente.

Mi opción preferida (la que uso) es PhpStorm, una opción de pago. Pero también hay opciones gratuitas muy interesantes como, por ejemplo, Visual Studio Code.

Y si quieres ir haciendo unos pinitos rápidos antes de entrar en serio en la programación, te recomiendo que uses al menos, un editor de código sencillo como, por ejemplo, Notepad++, que, además, es totalmente gratuito.

Cómo programar un shortcode para WordPress en PHP

Dicho todo esto, veamos entonces ahora cómo programar un shortcode en PHP, dentro de las pautas que nos marca el API (Application Programming Interface) de WordPress.

Los shortcodes se componen del código que lo implementa (una función PHP) y una llamada a otra función (add_short_code) que realiza el registro del shortcode en WordPress (que es que lo activa realmente).

La pinta que tiene un shortcode es como sigue (el patrón de shortcode más simple que existe):

// La función que implementa el shortcode. En este caso, 
// simplemente retorno simplemente crea una cadena, 
// “¡Hola Mundo!”, y la devuelve a la llamada al shortcode 
// la cual la recogerá para añadirla al contenido de 
// la página web.

function holaMundo() {
  return '<h1>¡Hola mundo!</h1>';
}

// Registra el shortcode: asocia el nombre del shortcode
// ‘hola’ a la ejecución de la función ‘holaMundo’ que 
// hemos creado arriba para que la llame.
add_shortcode('hola', 'holaMundo');

Como ves, el código PHP que hemos creado es muy simple, pero es que no tiene más. Éste es el “esqueleto” que vas a usar para cualquier shortcode, lo único que cambia es el contenido de la función que lógicamente puede ser mucho más complejo para shortcodes más sofisticados.

De hecho, aquí en este web tenemos un montón de shortcodes de este estilo, muy simples, para hacernos pequeños "widgets" a medida como, por ejemplo, nuestro banner de hostings recomendados:

Lo único que diferencia el shortcode que ha generado este banner es que el HTML que lo compone salta a la vista que lógicamente es un poquito más elaborado, pero nada más. Por lo demás, es lo mismo.

Lo bueno es que, si mañana cambian las cifras de los descuentos o hay alguna acción especial como el Black Friday, por ejemplo, es tan simple como retocar un momento el código y automáticamente el banner quedará actualizado en todas las páginas que lo usan (que son muchas...).

Para los que, como yo, preferís programar orientado a objetos en WordPress, dejo el mismo ejemplo de arriba en una variante orientada a objetos:

class EjemploHolaMundo {
  public function __construct() {
    // El primer ‘holaMundo’ es el shortcode como tal,
    // el segundo es el nombre del método de la clase 
    // que llamamos.
    add_shortcode('holaMundo', array($this, 'holaMundo'));
  }

  public function holaMundo($atts = null) {
    return '<h1>¡Hola mundo!</h1>';
  }
}

new EjemploHolaMundo();

Ojo: en este caso, para que se añada el shortcode es necesario instanciar un objeto de esta clase, para que se ejecute su constructor y con ello la parte del código que registra el shortcode.

Es importante comentar que en este simple ejemplo no estoy usando la posibilidad de pasar parámetros y tampoco estoy abordando el formato de shortcode que permite encerrar un contenido.

Estos detalles los puedes encontrar en la guía oficial de programación de shortcodes. Este post es simplemente una introducción a la programación de shortcodes para que entiendas los fundamentos de cómo funciona esto.

Integrar nuestro código PHP con WordPress

Antes de empezar, una advertencia: aunque nos vamos a limitar a crear shortcodes muy simples, añadirlos luego a una web WordPress no deja de ser tocar las “tripas” de tu web WordPress, hay un riesgo importante de que con un error en nuestro código acabemos tirando la web entera.

De hecho, al hablar de programar sé consciente de que nos estamos metiendo en el terreno de los profesionales de la programación en PHP y HTML. Es decir, como si metes las manos en el motor de tu coche.

Por tanto, hay que tomar una serie de medidas de precaución:

1. Todo lo que hagas, hacerlo con atención y cuidado.
2. Probar el código primero en una réplica de la web o una instalación de “laboratorio”. Para esto puedes crear también una instalación en local de WordPress tal como se explica en el tutorial de un poco más abajo. Una vez que hayas comprobado que el código va bien, ya lo puedes usar en la web real.
3. Activar el modo de depuración de WordPress. Esto generará un fichero de depuración en el que se vuelcan los errores en la ruta de “/wp-content/debug.log” de tu web.

Y aquí el tutorial de cómo crear una instalación local de WordPress:

Vistas estas precauciones, ya nos podemos poner manos a la obra para integrar nuestro código en WordPress. Para ello hay básicamente tres vías:

• Integrar el shortcode en el fichero php de tu tema activo que se encuentra en el directorio “wp-content/themes/[nombre de tu tema]”.
• Vía un plugin para añadir código a medida a WordPress. Más fácil para los principiantes ya que te oculta algunas de las cosas que tienes que hacer si programas como lo harían los profesionales. Está muy bien para cosas sencillas, pero para cosas avanzadas te resultará limitante.
• Con un plugin propio.

Veamos las diferencias y por cuál decidirnos.

Integrar el shortcode en functions.php

Que vaya por delante: esta vía la descarto totalmente porque es una chapuza. Pero hay que mencionarla porque es la vía que te sugieren en muchos contenidos.

Este es un fichero estándar que debe estar presente en todos los temas de WordPress y que se incluye y se ejecuta cada vez que se carga una página en un momento adecuado para incluir funciones PHP personalizadas. Esto lo ha hecho muy popular para meter aquí código personalizado.

De hecho, sirve para incluir cualquier cosa que se quiera hacer, no solamente shortcodes.

¿Por entonces digo que es una chapuza?

Sobre todo, por dos razones:

1. Porque las actualizaciones de los temas machacan este fichero. Así que, con cada actualización perderías tus modificaciones.
2. El código fuente hay que estructurarlo muy bien desde el principio (con una buena estructura de ficheros y carpetas), si no, con el tiempo, vas a tener un “código espagueti” imposible de corregir ante errores y de evolucionar.

Integrar shortcodes con el plugin Code Snippets

Una alternativa mucho mejor que añadir el código “a pelo” a functions.php es utilizar el plugin Code Snippets.

Este plugin mantiene un repositorio de fragmentos (“snippets”) de código. Para ello incluye un pequeño editar de código para programarlos y una lista con todos ellos desde la cual los puedes gestionar.

Es una solución que ya considero bastante buena y que diría va a valer para el 95% o más de los usuarios que solamente van a hacer cosas relativamente sencillas.

Aquí puedes ver el código de arriba en el editor de este plugin:

Es una solución más fácil a la programación en WordPress ya que te oculta algunas de las cosas que tienes que hacer si programas como lo harían los profesionales.

Está muy bien para cosas sencillas porque ya soluciona el problema relacionado con las actualizaciones de los temas, pero sólo tienes un espacio único para el código en el editor y eso para proyectos grandes resultará un problema.

Integrar shortcodes creando un plugin propio

La vía más profesional, ausente de limitaciones es la de programar tu propio plugin.

La programación de plugins para cosas sencillas es realmente muy simple. Realmente lo único añadir para el ejemplo son tres cosas:

1. Usar un fichero PHP principal con formato [nombre-plugin].php en el directorio raíz
2. Comprimir el plugin con un formato .zip para poder añadirlo vía el escritorio de WordPress (por la vía de fichero local, es decir, no desde el repositorio de WordPress.org).
3. Crear una cabecera para el fichero principal como la del ejemplo siguiente:

Como decía, para el ejemplo sería muy simple: bastaría con un único fichero, por ejemplo: hola-mundo.php, en el que iría la cabecera de arriba seguida del código. Es decir, esto:

<?php

/*
Plugin Name: [El nombre de tu plugin]
Plugin URI: [URL del plugin (si la va a tener), si no, pon tu web]
Description: [Una breve descripción del plugin]
Version: [La versión del plugin]
Author: [Autor del plugin]
Author URI: [URL del autor del plugin]
License: [El tipo de licencia, si la quieres poner. Por ejemplo: LGPL]
*/

// La función que implementa el shortcode. En este caso, simplemente 
// retorna una cadena “¡Hola Mundo!” y la devuelve a la llamada al 
// shortcode la cual la recogerá para añadirla al contenido de la 
// página web.

function holaMundo() {
  return '<h1>¡Hola mundo! </h1>';
}

// Registra el shortcode: asocia el nombre del shortcode ‘hola’
// a la ejecución de la función ‘holaMundo’ que hemos creado arriba
// para que la llame.
add_shortcode('hola', 'holaMundo');

De todos modos, para que sepas defenderte también con implementaciones más sofisticadas, con más código, en las que tengas que usar quizás también ficheros de imágenes, JavaScript o CSS, etc., te dejo este post de Raiola Networks en el que te explican mucho más a fondo cómo crear plugins.

¿Qué hacer si tengo problemas?

Desgraciadamente, al tocar código podemos meter mucho la pata y provocar incluso errores muy severos como la famosa “pantalla blanca de la muerte”.

Pero también es verdad que para eso ya hemos tomado medidas de precaución para que los problemas se queden en el entorno de pruebas.

Además, alguna vez te puede ocurrir que sean plugins que te hayas descargado los que te estén dando problemas, así que aprender cómo se depuran errores de código en WordPress es en todo caso algo extremadamente útil que te recomiendo encarecidamente.

De todos modos, quiero concienciarte de que la depuración ya es entrar en terrenos algo avanzados. Es algo que ya requiere una cierta soltura y dominio.

Por ese motivo, si con las indicaciones de aquí no consigues dar con el origen del error, si tienes un buen soporte para tu hosting, ellos te deberían ayudar si lo necesitas. Y si no es así, ya tienes una buena razón para cambiar a alguno de los hostings que recomendamos aquí 😉

Cómo depurar errores con el log de WordPress

En primer lugar, como ya decía arriba, hasta que no estés seguro de que tu código funciona bien, activa siempre el modo de depuración de WordPress que consiste básicamente en incluir estas líneas en el fichero wp-config.php que se encuentra en el directorio raíz de tu web WordPress:

define('WP_DEBUG', false);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);

De este modo se generará un fichero de depuración en el que se vuelcan los errores en la ruta de “/wp-content/debug.log”. En este fichero verás líneas con fecha y hora con trazas de error de este estilo:

[10-May-2021 12:22:31 UTC] PHP Fatal error:  Uncaught Error: Call to undefined method BWPAMToolkit::addSShortcode() in /home/c2cero/public_html/c2cerodes/wp-content/plugins/bwp-amtoolkit/bwp-amtoolkit.php:189
Stack trace:
#0 /home/c2cero/public_html/c2cerodes/wp-content/plugins/bwp-foundation/src/core/options/abstract-plugin.php(139): BWPAMToolkit->lateInit()
#1 /home/c2cero/public_html/c2cerodes/wp-includes/class-wp-hook.php(292): AbstractBWPFPlugin->preLateInit('')
#2 /home/c2cero/public_html/c2cerodes/wp-includes/class-wp-hook.php(316): WP_Hook->apply_filters(NULL, Array)
#3 /home/c2cero/public_html/c2cerodes/wp-includes/plugin.php(484): WP_Hook->do_action(Array)
#4 /home/c2cero/public_html/c2cerodes/wp-settings.php(560): do_action('init')
#5 /home/c2cero/public_html/c2cerodes/wp-config.php(142): require_once('/home/c2cero/pu...')
#6 /home/c2cero/public_html/c2cerodes/wp-load.php(37): require_once('/home/c2cero/pu...')
#7 /home/c2cero/public_html/c2cerodes/wp-blog-header.php(13): require_once('/home/c2cero/pu...')
#8 /home/c2cero/public_html/c2cerode in /home/c2cero/public_html/c2cerodes/wp-content/plugins/bwp-amtoolkit/bwp-amtoolkit.php on line 189

Se sale del ámbito de este post entrar en todos los detalles de la depuración en PHP y en WordPress. Aquí simplemente quiero que te fijes en que estas trazas te desvelan el fichero y el número de línea exacto donde se ha producido el error.

Si lo haces, verás que arriba del todo nos dice que el error se ha producido en la línea 189 del fichero bwp-amtoolkit.php. Tan sólo con eso suele ser una información bastante precisa para poder dar rápidamente con el problema.

En este caso, además, canta mucho porque el error es un error de sintaxis: la traza nos dice que el método “addSShortcode()” de la clase “BWPAMToolkit” es un método que no existe. Si te vuelves a fijar canta que la llamada está mal, hay una “S” duplicada, ha de ser “addShortcode()”, con una sola “S”. Así que el error era algo tan simple como eso…

Cómo arreglar problemas si estás usando Code Snippets

En el caso de usar Code Snippets, los pasos de arriba te valdrán exactamente igual, pero en el caso de que no seas capaz de solucionar el problema por esa vía, puedes hacer también lo siguiente (aunque es más a lo bruto y menos eficaz en ese sentido):

1. Haz siempre una copia de tu código (lo puedes exportar desde el propio plugin si quieres o haces un simple copiar y pegar en otro editor como Notepad++, por ejemplo) hasta que no lo tengas estable.
2. Desactivas el shortcode en Code Snippets.
3. Si aun así persiste el problema o si incluso llegas a tener problemas para poder entrar en el panel de administración de WordPress (esto ya es algo muy extremo), borras el plugin de code snippets del directorio de plugins (wp-content/plugins/code-snippets).
4. Una vez borrado, WordPress estará operativo otra vez (aunque tus shortcodes en este momento no estarán operativos).
5. Instalas de nuevo el plugin, restauras la copia normal que te decía arriba que hicieses antes de añadir un nuevo shortcode al plugin (la que viene en formato *.xml) y compruebas que todo ha vuelto a la normalidad.
6. Repasas el código del shortcode nuevo para ver dónde puede estar el error y lo corriges (normalmente será algún gazapo en la edición o al copiar & pegar). También puede pasar el nombre de la función del shortcode se repita y cause los problemas.
7. Vuelta a empezar con el shortcode corregido.

3 Ejemplos prácticos de shortcodes

Para que te hagas una idea un poco más concreta de lo que estamos hablando, nada mejor que unos ejemplos.

Así que he preparado unos cuantos ejemplos de shortcodes prácticos que te puedes descargar en la sección de descargas del blog. Los detalles sobre cómo usarlos vienen documentados un poco más abajo en este post y con cada una de las descargas.

1. Insertar un fichero cualquiera en tu blog

Este es tan simple como útil: lee el contenido de un fichero pasado como parámetro y lo inserta en el lugar del shortcode, de modo que puedes integrar el código HTML o JavaScript que quieras en el lugar del shortcode.

<?php
/**
* Creado por Hosting a Tope
* Fecha: 10/05/2021
* Versión: 1.0
* Licencia: Creative Commons Atribución
*/

/**
 * Lee un fichero y lo incrusta tal cual en el lugar del shortcode. 
 * Se asume que existen una carpeta "wp-custom/includes/" en el 
 * directorio de instalación de WordPress en el cual se va a poner 
 * los ficheros utilizados con este shortcode. 
 *
 * Uso: [includeHTML filename="[nombre-fichero]"]
 *
 * Parámetros:
 * 1. filename (obligatorio): El nombre del fichero. Los nombre de los 
 *    ficheros tienen que encontrarse en el directorio que se personaliza 
 *    abajo (o en subdirectorios de éste).
 */
function includeHtml($atts = null) {
    // Extraer el parámetro y darle un valor por defecto (cadena vacía) 
    // en caso de que el usuario no lo haya utilizado
    shortcode_atts(array(
        'filename' => ''
    ), $atts);

    // Edita la cadena "wp-custom/includes/" para cambiar el 
    // directorio raíz para los ficheros a incluir
    if (!empty($atts['filename'])) {
        $path = ABSPATH . "wp-custom/includes/" . $atts['filename'];
        // Cargamos el contenido del fichero en una variable
        $content = file_get_contents($path);
        return $content;
    } else {
        return "<h3>Error: falta el parámetro en [includeHTML].</h3>";
    }
}
add_shortcode('includeHTML', 'includeHTML');

Esto es prácticamente el shortcode trivial de “¡Hola mundo!” extendido simplemente con la capacidad de tomar el contenido de un fichero de modo que puedes tener múltiples “widgets” personalizados por ti.

2. Crear un botón con enlace

El siguiente ejemplo es un poquito más ambicioso y crea un enlace con apariencia de botón que tiene incluso la capacidad de cambiar de color cuando pasas con el ratón por encima.

De hecho, es una versión simplificada del botón que estás viendo precisamente aquí para la descarga del código. Es un shortcode de botón que usamos aquí en esta web, creado por mí y que en nuestro caso añade algunas cosas más como la posibilidad de registrar los clics recibidos.

<?php
/**
 * Creado por Hosting a Tope
 * Fecha: 10/05/2021
 * Versión: 1.0
 * Licencia: Creative Commons Atribución
 */

/**
 * Dibuja un botón con enlace. El botón usa la clase "bwp-link-button" 
 * lo que permite personalizar su apariencia en el menú de 
 * "_CSS adicional" dentro de la personalización estándar del tema 
 * (menú Apariencia/Personalizar en el escritorio de WordPress).
 *
 * Un ejemplo de hojas de estilo que crea un botón verde con texto blanco, 
 * en posición centrada y que cambiar de color al pasar el ratón 
 * sería éste:
 *
 * .bwp-link-button {
 *   margin: 20px auto;
 *   text-align: center;
 *   font-weight: 700;
 * }
 *
 * .bwp-link-button a {
 *   display: inline-block;
 *   margin: 5px auto;
 *   font-weight: 700;
 *   font-size: 1.1em;
 *   border-radius: 5px;
 *   background-color: green;
 *   padding: 8px 25px;
 *   color: #fff;
 * }
 *
 * .bwp-link-button a:hover {
 *   background-color: limegreen;
 * }
 *
 * Un ejemplo de uso sería éste: 
 *
 * [linkButton text="Ir a YouTube" link="https://youtube.com"]
 *
 * @param null $atts    
 * Admite los parámetros obligatorios "link" (URL completa 
 * o relativa del enlace), "text" (texto para el botón) y los 
 * parámetros opcionales "id" y "target" para poder añadir los 
 * atributos HTML correspondientes al enlace si fuese útil.
 *
 * @return string   El HTML del botón.
 * @throws Exception
 */
function showLinkButton($atts = null) {

    // Extraer los parámetros y darles un valor por defecto 
    // (cadena vacía) en caso de que el usuario no los haya 
    // usado expresamente.
    $atts = shortcode_atts(array(
        'link' => '',
        'text' => '',
        'id' => '',
        'target' => '_blank'
    ), $atts);

    // Validar los parámetros
    if (empty($atts['link'])) {
        throw new Exception("No se ha especificado el parámetro obligatorio [link].");
    }
    if (empty($atts['text'])) {
        throw new Exception("No se ha especificado el parámetro obligatorio [text].");
    }

    // Crear los atributos HTML
    if (!empty($atts['id'])) {
        $atts['id'] = ' id="'.$atts['id'].'"';
    }
    $atts['target'] = ' target="'.$atts['target'].'"';

    return
        '<div class="bwp-link-button">
            <a '.$atts['id'].$atts['target'].' href="'.$atts['link'].'" >'.$atts['text'].'</a>
        </div>';
}
add_shortcode('linkButton', 'showLinkButton');

Aunque es una versión simplificada de nuestro botón, ya te puede ser muy útil para todo tipo de usos.

3. Tabla de Pros/contras

Rematamos los ejemplos con uno ya un poco más sofisticado y que he “empaquetado”, además, como un plugin para que veas cómo funciona y lo fácil que es realmente crear un plugin.

Este plugin crea una tabla comparativa con el siguiente aspecto:

En cuanto al diseño estético, me he inspirado fuertemente en el plugin de Mighty Classic Pros & Cons, aunque el código con el que está programada y la filosofía de uso son totalmente diferentes.

En el caso del plugin original, los contenidos se editan cada vez desde el editor que se inserta. Eso en mi caso no es lo deseable porque necesito repetir la misma tabla comparativa en diferentes páginas.

Por eso, este plugin usa ficheros .txt con un formato que permite especificar el contenido, que se guarda y se reutiliza múltiples veces lo cual se adapta mucho mejor a mis necesidades.

Por otra parte, este plugin no se instala desde el repositorio de plugins de wordpress.org. Viene como un fichero en formato .zip y se instala desde el escritorio de WordPress tal como se explica en este post.

En este caso, como ya es cierta cantidad de código, no lo mostramos entero aquí, sino que te remite directamente a la descarga del mismo para que ya lo ojees tranquilamente:

Como el desarrollo de plugins es un tema ya un poco más avanzado, te dejo aquí también el enlace al Manual oficial de WordPress para crear plugins.

Un último comentario y pequeño reto para ti: siendo realmente fácil la creación plugins básicos, ¿por qué no te atreves con convertir los dos ejemplos anteriores en un plugin?

Prácticamente, lo único que tienes que hacer es crear un nuevo fichero PHP, crear la cabecera anterior siguiente el formato que ya has podido ver arriba, añadir el código, comprimirlo como fichero .zip y poco más…

Así que ya tienes un entretenimiento para divertirte un rato si te gusta trastear con estas cosas. ¡Que lo disfrutes! 😉