La guía de shortcodes: Combina PHP y WordPress

Descubre la API de shortcodes de WordPress y cómo aprovechar su potencial en esta guía completa para potenciar tu sitio web.

Qué es un shortcode

Un shortcode es un bloque de texto entre corchetes que sirve de enlace a un contenido o funcionalidad mayor en WordPress. Esto nos permitirá tener el control desde un único punto aunque se muestre en muchos lugares, facilitando así el mantenimiento de nuestras funcionalidades.

Un par de usos comunes del shortcode de WordPress

1. Contenido repetido: Si vamos a tener un contenido repetido, en muchas ocasiones podremos crear un shortcode desde nuestro archivo functions.php, y luego solo tendremos que colocarlo en las páginas y posts donde queramos.
2. Iframes: Existen casos en los que colocar un Iframe en WordPress puede ser un quebradero de cabeza, ya que podremos colocarlos en un bloque de incrustado y borrarse automáticamente. Esto puede solucionarse retornando el Iframe desde la funcionalidad de creación del Shrtcode.

Cómo añadir un shortcode en WordPress

Para añadir un shortcode en WordPress tendremos que añadir el bloque correspondiente e introducir el texto dentro de los corchetes.

[mi_shortcode]

Por ejemplo, si usamos Gutenberg, encontraremos un bloque llamado shortcode para este fin.

Cómo crear un shortcode

Como con casi todo en WordPress contamos con la posibilidad de crearlo mediante plugins o con código. A continuación te explico ambas técnicas.

Con plugins

Aunque no es el método que prefiero, te dejo algunos plugins con los que podrás trabajar:

• WordPress Shortcodes Plugin — Shortcodes Ultimate
• Snippet Shortcodes
• Shortcoder — Create Shortcodes for Anything

Sin plugins

En realidad, crear un shortcode sin plugins es súper sencillo. Un shortcode cuenta con 3 elementos imprescindibles:

<?php

function webheroe_hola_shortcode(){
    return 'hola';
}
add_shortcode("webheroe_hola", "webheroe_hola_shortcode");

1. Nombre de la función donde se almacena el contenido del shortcode. En el ejemplo anterior webheroe_hola_shortcode
2. La función de WordPress add_shortcode, es la que enlazará el nombre del shortcode (webheroe_hola) con la función del punto 1
3. La llamada al shortcode. La llamada se realiza desde el lugar donde queremos mostrar el contenido del shortcode usando el primer argumento del punto 2 entre corchetes, en este caso caso:
   [webheroe_hola]

Ejemplo real de shortcode en WordPress

Como el mejor modo de entenderlo es mediante un ejemplo real, te explico los pasos donde creo un shortcode en el que se mostrará el tiempo meteorológico obtenido de una API gratuita para fines no comerciales: Open-Meteo.

1. Llamada a API

function webheroe_meteo_shortcode() {
    $response = wp_remote_get( 'https://api.open-meteo.com/v1/forecast?latitude=36.72&longitude=-4.42&hourly=rain' );


    $decoded = json_decode( $response['body'] );


    echo '<pre>';
    var_dump( $decoded );
    echo '</pre>';
}
add_shortcode( 'webheroe_meteo', 'webheroe_meteo_shortcode' );

Como podemos ver en este código, se ha usado una función nativa de WordPress (wp_remote_get) para realizar la llamada a la API, en la que se ha facilitado la localización geográfica de Málaga, así como la información que queremos obtener, la temperatura máxima.

Tras esto hemos decodificado el código Json devuelto. También he hecho un var_dump para pintar en pantalla la respuesta, esto me facilitará crear la estructura HTML en los siguientes pasos.

2. Localizamos valor que queremos mostrar

Tras revisar lo que se ha mostrado en pantalla he llegado a la conclusión de que el valor que queremos obtener se encuentra en:

    $output = '
        <div id="webheroe-meteo">
            <p>En Málaga estamos con ' . esc_html( $temp ) . 'º de temperatura máxima</p>
        </div>
    ';

4. La función completa

function webheroe_meteo_shortcode(){
    $response = wp_remote_get( 'https://api.open-meteo.com/v1/forecast?latitude=36.72&longitude=-4.42&hourly=&daily=temperature_2m_max&timezone=auto' );
    $decoded = json_decode( $response['body'] );
    $temp       = $decoded->daily->temperature_2m_max[0];
   
    $output = '
        <div id="webheroe-meteo">
            <p>En Málaga estamos con ' . esc_html( $temp ) . 'º de temperatura máxima</p>
        </div>
    ';


    return $output;
}
add_shortcode( 'webheroe_meteo', 'webheroe_meteo_shortcode' );

5. Definir dónde mostrar nuestro shortcode

Ahora solo tendremos que declarar el shortcode en el lugar donde queramos mostrar nuestro bloque de contenido. Por ejemplo, podemos seleccionar un bloque de shortcode en Gutenberg (O en cualquier maquetador).

Recordemos que la llamada al shortcode se hace mediante el primer argumento en corchetes de la función de enlace add_shortcode, en este ejemplo entonces sería [webheroe_meteo].

Los atributos en los shortcodes

Nuestros shortcodes también pueden aceptar atributos, muy comunes cuando, por ejemplo, desarrollamos en WooCommerce. Los atributos son variaciones que podemos añadir dependiendo del lugar donde queramos colocar nuestro shortcode.

Siguiendo el ejemplo del tiempo meteorológico, si contamos con una web que tiene una página por cada capital, y queremos mostrar el tiempo de esa ciudad concreta, podríamos crear un atributo que fuese ciudad, otro que fuese latitud y otro que fuese longitud. Quedaría entonces algo que así:

function webheroe_meteo_shortcode($atts){
    $attr = shortcode_atts( array(
            'ciudad'    => 'Málaga',
            'latitud'    => '36.72',
            'longitud' => '4.42'
        ), $atts );


    $response = wp_remote_get( 'https://api.open-meteo.com/v1/forecast?latitude=' . $attr['latitud'] . '&longitude=' . $attr['longitud'] . '&hourly=&daily=temperature_2m_max&timezone=auto' );
    $decoded = json_decode( $response['body'] );
    $temp      = $decoded->daily->temperature_2m_max[0];
   
    $output = '
        <div id="webheroe-meteo">
            <p>En ' . $attr["ciudad"] . ' estamos con ' . esc_html( $temp ) . 'º de temperatura máxima</p>
        </div>
    ';


    return $output;
}
add_shortcode( 'webheroe_meteo', 'webheroe_meteo_shortcode' );

Por defecto, este shortcode mostraría el tiempo de la ciudad de Málaga, pero si queremos mostrar el de la ciudad de Santa Cruz de Tenerife tendríamos que añadir un shortcode con atributos del siguiente modo:

[webheroe_meteo ciudad="Santa Cruz de Tenerife" latitud="28.46" longitud="-16.25"]

Con este ejemplo podréis imaginaros todo lo que se podría hacer con CRON WordPress y con sus transients.

Cómo combinar PHP y los shortcodes de WordPress

WordPress nos facilita una función para que podamos llamar un shortcode directamente desde PHP, hablamos de do_shortcode(). Con esta función tan solo tendremos que hacer un echo de esta función con el shortcode (también en corchetes) como único argumento.

echo do_shortcode( '[webheroe_meteo]' );

Esto es súper útil si queremos mostrar un shortcode en alguna plantilla definida por WordPress o por nosotros. Por ejemplo en el archivo footer.php, header.php, single.php, my_page_template.php, etc…

Shortcodes nativos

Por defecto contamos con una serie de shortcodes muy interesantes:

• [caption]: Para incrustar imágenes
• [gallery]: Para crear una galería de imágenes seleccionadas por ID
• [video]: Para incrustar archivos de video mediante atributo src
• [playlist]: Para incrustar una lista de reproducción de audio o video seleccionados por IDs
• [audio]: Para incrustar archivos de audio mediante atributo src
• [embed]: Para incrustaciones. Muy útil si, por ejemplo, queremos mostrar un artículo en un bloque

Shortcode entre etiquetas

La forma clásica de uso del shortcode es la que he explicado más arriba. Pero también existe el método de shortcode “encerrado” o “entre etiquetas”. Para que nos entendamos, sería algo así:

[webheroe_encerrado]El contenido que quiero mostrar[/webheroe_encerrado]

Si queremos hacer algún tipo de filtrado del contenido a mostrar esta técnica es súper útil. Se me ocurre, por ejemplo, crear un shortcode “encerrado” para tener un bloque de contenido con unos estilos concretos. A continuación te muestro un ejemplo para un bloque del tipo cita con unos estilos muy concretos:

function webheroe_encerrado_short($atts, $content, $tags){
    $attr = shortcode_atts(
            array(
                'autor'           => 'Álvaro Torres',
                'color'            => 'white',
                'color_fondo' => 'black'
            ),
           $atts
    );


    $output = '
    <div class="webheroe-quote" style="padding: 15px;background-color: ' . esc_attr( $attr['color_fondo'] ) . ';color: ' . esc_attr( $attr['color'] ) . ';max-width: 500px;margin: 0 auto 25px">
        <blockquote style="font-size: 20px;font-weight: 500">
            ' . esc_html( $content ) . '
        </blockquote>
        <cite style="display: block;margin-right: 5%;text-align: right">' . esc_attr( $attr['autor'] ) . '</cite>
    </div>
    ';


    return $output;
}
add_shortcode( 'webheroe_encerrado', 'webheroe_encerrado_short' );

Para este ejemplo uso una cita del compañero Saúl Sánchez Iglesias que he visto en LinkedIn y me ha parecido muy interesante. El código sería:
[webheroe_encerrado autor="Saúl Sánchez Iglesias" color_fondo="blue"] Lo más urgente y vital de la vida rara vez ocurre a través de un correo electrónico[/webheroe_encerrado]

Y se vería así en la web:

Si has llegado hasta aquí, no debería costarte adivinar que en caso que no hubiésemos colocado el atributo color_fondo, el fondo aparecería de color negro.

Funciones relacionadas con los Shortcodes

• do_shortcode(): Pinta el shortcode facilitado con echo en un archivo PHP
• add_shortcode(): Enlaza el shortcode con la función que devuelve el contenido del shortcode
• remove_shortcode(): Elimina el shortcode seleccionado. Muy útil si queremos inutilizar un shortcode en ciertas páginas sin tener que acceder a ellas y borrarlo uno a uno
• remove_all_shortcodes(): Elimina todos los shortcodes del mismo modo que la función anterior
• shortcode_atts(): Revisa los atributos y los añade en caso de necesitarlo
• strip_shortcodes(): Elimina todas las etiquetas de shortcodes del contenido facilitado
• shortcode_exists(): Función que devuelve un valor booleano. Verifica si existe el shortcode facilitado
• has_shortcode(): Revisa el contenido dado para comprobar si existe el shortcode facilitado como segundo argumento
• get_shortcode_regex(): Obtiene la expresión regular de los shortcodes
• wp_audio_shortcode(): Una combinación del shortcode de audio por defecto y do_shortcode. Se crea un elemento de audio mediante los valores facilitados
• wp_video_shortcode(): Una combinación del shortcode de video por defecto y do_shortcode. Se crea un elemento de vídeo mediante los valores facilitados

Recomendaciones al usar shortcodes

1. Si nuestro shortcode tiene un contenido desorbitado podemos usar ob_start() para almacenar en búfer y retornar mediante ob_get_clean().
2. No usemos CamelCase ni Mayúsculas en la declaración de atributos, ya que al pasarlos por shortcode_atts se procesarán en minúsculas.
3. Siempre debemos usar return para devolver el contenido que queremos mostrar. Si en su lugar usamos echo el contenido seguramente se mostrará arriba del todo del documento.
4. El uso de shortcodes es de lo más útil. Pero habrá veces que sea más práctico crear el bloque en el mismo archivo PHP. Y, en caso de ser necesario, usar un condicional para que solo afecte a lo que queramos.

En WebHeroe nos dedicamos al desarrollo de webs en WordPress, además de ofrecer servicios de marketing digital. Consúltanos y te informaremos.