Entender los shortcodes de WordPress: crear, personalizar y usar shortcodes propios en PHP

• ¿Qué son los shortcodes en WordPress?
• ¿Dónde puedes usar códigos cortos de WordPress?
• Crea tu propio shortcode en WordPress
• Crear shortcode con atributos
• Usar shortcode en publicaciones y páginas
• Usar códigos cortos en PHP: Tema, Tema secundario, funciones.php
• Código corto de salida en PHP
• Guardar el contenido del shortcode en una variable
• Búfer de salida para códigos cortos que usan echo en lugar de return
• Personalizar y ampliar códigos cortos
• Ventajas y desventajas de los shortcodes de WordPress
• Seguridad y mejores prácticas para tus propios shortcodes

Si ha estado trabajando con WordPress durante mucho tiempo, difícilmente podrá evitar los códigos cortos. Independientemente de si se trata de un formulario de contacto, una galería, un control deslizante o cuadros especiales para obtener información, estas funciones suelen contener un código corto entre corchetes.

En esta publicación, te mostraré qué son los códigos cortos de WordPress, cómo crear tus propios códigos cortos, cómo usarlos en publicaciones y páginas y cómo puedes usar códigos cortos directamente en PHP en tu tema o tema secundario. También veremos las ventajas y desventajas de los códigos cortos y algunas prácticas recomendadas para que tu código siga siendo mantenible más adelante.

¿Qué son los shortcodes en WordPress?

Los códigos cortos son pequeños marcadores de posición entre corchetes, por ejemplo:

[gallery]
[contact-form-7 id="123"]
[mein_shortcode foo="bar"]

WordPress reconoce dichos códigos cortos al representar el contenido y los reemplaza con código HTML u otro resultado. La lógica real está en las funciones PHP que se registran a través de la API de shortcode.

En resumen:
Los códigos cortos son un atajo para incorporar funciones complejas en publicaciones y páginas de WordPress sin que el editor tenga que escribir PHP.

Ejemplos típicos de códigos cortos de WordPress:

• Formularios de contacto
• Galerías de imágenes y controles deslizantes
• Cuadros de información, botones, acordeones
• listas dinámicas, por ejemplo últimas publicaciones o productos

¿Dónde puedes usar códigos cortos de WordPress?

Los códigos cortos no se limitan solo a publicaciones o páginas. Puedes usarlos en muchos lugares de tu proyecto de WordPress.

Ubicación	Ejemplo	Nota
Publicaciones y páginas (Gutenberg)	Bloque de código corto con [mein_shortcode]	Acerca del «código corto» bloquear Insertar
Editor clásico	Escribir directamente en el contenido	El código corto se reemplaza durante la renderización
Widgets	Widget de texto o HTML con [mein_shortcode]	Dependiendo del tema, los códigos cortos en los widgets deben ser activado
Plantillas PHP	echo do_shortcode('[mein_shortcode]');	Ideal en tema o tema secundario
Creador de páginas/campos personalizados	Muchos creadores procesan códigos cortos automáticamente	Dependiendo del complemento

Esto hace que los códigos cortos sean flexibles y especialmente prácticos cuando deseas reutilizar funciones o integrarlas en diferentes lugares.

Crea tu propio shortcode en WordPress

Puedes crear tus propios códigos cortos usando la función add_shortcode(). Usted asigna un nombre y una función de devolución de llamada que genera la salida.

Un ejemplo muy simple se ve así:

// In die functions.php deines Child Themes oder in ein eigenes Plugin
add_shortcode('my_shortcode', function ($atts) {
    $result = 1 + 1;

    return $result;
});

Algunos puntos importantes:

• El nombre del shortcode aquí es my_shortcode. Puedes llamarlo más tarde con [my_shortcode].
• La función de devolución de llamada debe return y no usar directamente echo.
• Luego puedes guardar el shortcode en una variable más adelante y usarlo de manera flexible.

Crear shortcode con atributos

En la práctica, a menudo deseas pasar parámetros, por ejemplo:

[box color="red" title="Hinweis"]
Mein Box Inhalt
[/box]

Puedes utilizar shortcode_atts() para definir valores predeterminados y procesar atributos de forma limpia:

add_shortcode('my_box', function ($atts, $content = '') {

    $atts = shortcode_atts([
        'color' => 'blue',
        'title' => '',
    ], $atts, 'my_box');

    $color = esc_attr($atts['color']);
    $title = esc_html($atts['title']);

    ob_start();
    ?>
    <div class="my-box my-box-<?php echo $color; ?>">
        <?php if ($title) : ?>
            <h3 class="my-box-title"><?php echo $title; ?></h3>
        <?php endif; ?>
        <div class="my-box-content">
            <?php echo do_shortcode($content); ?>
        </div>
    </div>
    <?php
    return ob_get_clean();
});

Aquí puedes ver cómo:

• Proporcionar atributos con valores predeterminados
• asegure la salida con esc_attr y esc_html
• Utiliza almacenamiento en búfer de salida para bloques HTML más largos (ob_start() y ob_get_clean())

Esto mantiene el código limpio y fácilmente ampliable.

Usar shortcode en publicaciones y páginas

Suponiendo que haya creado el código corto my_box del ejemplo anterior. En una publicación o en una página puedes usarlo así:

[my_box color="green" title="Info"]
Das ist eine grüne Box mit einem Info Titel.
[/my_box]

En el Editor Gutenberg haces esto:

1. Editar publicación o página
2. Haga clic en el símbolo más
3. Buscar “código corto”
4. Insertar bloque de código corto
5. Ingrese el texto del código corto, por ejemplo [my_box color="green"]Inhalt[/my_box]
6. Guardar o publicar publicación

WordPress reemplaza automáticamente el código corto con el código HTML de tu función cuando abres la página.

Usar códigos cortos en PHP: Tema, Tema secundario, funciones.php

A veces desea utilizar códigos cortos directamente en plantillas PHP, por ejemplo en single.php, page.php o una plantilla personalizada.

Para eso está do_shortcode().

Código corto de salida en PHP

Si desea generar un código corto directamente en la plantilla, puede instalarlo así:

echo do_shortcode('[my_box color="red" title="Achtung"]Inhalt aus dem Template[/my_box]');

• do_shortcode() procesa el código corto y devuelve una cadena
• Con echo generas el resultado en la plantilla

Guardar el contenido del shortcode en una variable

También puedes guardar el resultado de un shortcode en una variable y reutilizarlo. Esto es útil, por ejemplo, si necesita el contenido en varios lugares o aún desea editarlo.

De tus notas:

$shortcode_content = do_shortcode('[my_shortcode]');

La salida ahora está en $shortcode_content y puedes generarla más tarde o procesarla más.

Búfer de salida para códigos cortos que usan echo en lugar de return

En realidad, los códigos cortos siempre deberían funcionar con return. En realidad, existen complementos que usan echo directamente dentro del shortcode. En tal caso, puede trabajar con el almacenamiento en búfer de salida:

ob_start();
do_shortcode('[inconvenient_shortcode]');
$shortcode_content2 = ob_get_clean();

• ob_start() inicia el búfer de salida
• todo lo que genera el shortcode termina en el búfer
• con ob_get_clean() obtienes el contenido como una cadena en una variable y vacías el buffer

Así obtienes el contenido en una variable incluso con códigos cortos «inconvenientes».

Personalizar y ampliar códigos cortos

En muchos proyectos no solo desea escribir nuevos códigos cortos, sino también adaptar o ampliar los códigos cortos existentes, por ejemplo:

• agregar clases CSS adicionales
• Cambiar valores predeterminados
• ajustar la estructura HTML

Básicamente tienes dos opciones:

• Crea tu propio shortcode con un nuevo nombre
• Eliminar un shortcode existente y volver a registrarlo

Ejemplo de eliminación de un shortcode:

add_action('init', function () {
    remove_shortcode('old_shortcode');
});

Luego puedes almacenar tu propia implementación con add_shortcode('old_shortcode', 'meine_neue_funktion');. Pero sólo debes hacer esto si sabes exactamente qué impacto tendrá en el contenido existente.

Ventajas y desventajas de los shortcodes de WordPress

Los códigos cortos son útiles, pero no perfectos. Especialmente desde que se introdujo el Editor de bloques, vale la pena echarle un vistazo a las ventajas y desventajas.

Ventaja	Desventaja
Fácil de usar sin conocimientos de programación	El contenido depende en gran medida del tema o los complementos
Se pueden usar funciones complejas con texto breve	Si se desactivado, permanecen fragmentos de código corto como [shortcode] en el contenido
Funciona en publicaciones, páginas, widgets y plantillas PHP	Muchos códigos cortos en el texto pueden hacer que el editor sea confuso
Ideal para bloques de construcción reutilizables	Los códigos cortos están menos preparados para el futuro que los nativos Bloques
Fácil de integrar en sus propios temas y temas secundarios	Los códigos cortos elaborados pueden causar problemas de rendimiento

Para nuevos proyectos vale la pena considerar si un bloque Gutenberg no sería una mejor solución. Pero los códigos cortos siguen siendo útiles, especialmente:

• para funciones auxiliares más pequeñas
• en combinación con temas y complementos existentes
• si desea utilizar funciones tanto en el editor como en las plantillas

Seguridad y mejores prácticas para tus propios shortcodes

Para garantizar que tus códigos cortos de WordPress sigan siendo seguros y eficaces, debes seguir algunas reglas básicas.

1. Utilice nombres y prefijos únicos Es mejor utilizar un prefijo, por ejemplo el nombre de su blog o la abreviatura de su proyecto: add_shortcode('cosci_box', 'cosci_box_shortcode'); Esto reducirá los conflictos con otros temas o complementos.
2. Validar atributos y escapar de salidas
   • Proporcione atributos con valores predeterminados significativos a través de shortcode_atts().
   • Salida segura con esc_html, esc_attr o wp_kses
3. Los códigos cortos deben usar retorno en lugar de eco Si su código corto siempre devuelve una cadena, puede usarlo en publicaciones, páginas, variantes, condiciones y plantillas sin ninguna solución alternativa con el almacenamiento en búfer de salida.
4. Esté atento al rendimiento Si un shortcode realiza consultas complejas a la base de datos o llamadas API externas, esto puede ser un freno si hay muchas ocurrencias en una página. El almacenamiento en caché, los transitorios o la lógica de consulta inteligente ayudan aquí.
5. Es mejor subcontratar códigos cortos a un complemento Si coloca sus propios códigos cortos en un complemento pequeño, sobrevivirán a un cambio de tema. Esto significa que su proyecto sigue siendo más flexible a largo plazo.

Este artículo ha sido traducido con ayuda de IA.