🛠 Cómo añadir tu propio shortcode en WordPress: desglose de add_shortcode() [+2 ejemplos]

Creé un fragmento de código, lo añadí a functions.php y WordPress dice «¿haciendo trampa, eh?». ¿Le suena familiar? Los shortcodes, el mecanismo de extensión principal de WordPress, y add_shortcode() lo desbloquea en 15 líneas de código. Pero entre un «Hola mundo» y un escenario real hay algunas trampas: return vs echo, el orden de los parámetros del callback y los conflictos de etiquetas.

Los shortcodes aparecieron en WordPress 2.5 y desde entonces se han convertido en la base del ecosistema: formularios de contacto, galerías, sliders, salida de campos personalizados, todo vive dentro de corchetes. add_shortcode() no ha cambiado en años y puede dominarlo en media hora.

A continuación, un desglose completo de la función con dos ejemplos listos para usar: desde un año que se actualiza automáticamente en el pie de página hasta una lista de usuarios del sitio.

💡 Resumen rápido:

• Sintaxis y parámetros de add_shortcode(), etiqueta y callback
• La regla: siempre return, nunca echo
• El hook init, por qué su shortcode puede no funcionar sin él
• Dos formas de pasar datos: contenido entre etiquetas y atributos
• Código listo para usar: un shortcode para el año automático y una lista de usuarios

Cómo funciona add_shortcode() en WordPress

La función add_shortcode() es el punto de entrada para registrar cualquier shortcode personalizado. Toma dos parámetros obligatorios: una etiqueta única y el nombre de la función callback que devolverá el contenido.

Según la documentación de WordPress, el callback recibe tres argumentos en un orden fijo:

• $attributes, un array de atributos pasados en el shortcode
• $content, el texto entre las etiquetas de apertura y cierre
• $tag, el nombre de la etiqueta con la que se registró el shortcode

Un ejemplo básico, un shortcode que muestra «¡Hola mundo!»:

1
// Shortcode callback function
2
function hello_world_shortcode_callback( $attributes, $content, $tag ) {
3
    return 'Hello World!';
4
}
5
// Shortcode registration
6
function hello_world_shortcode() {
7
    add_shortcode( 'hello-world', 'hello_world_shortcode_callback' );
8
}
9
add_action( 'init', 'hello_world_shortcode' );

El código va en el archivo functions.php de su tema hijo o mediante un plugin de Code Snippets. Después de eso, [hello-world] en el editor de entradas mostrará «¡Hola mundo!».

Por qué return, no echo

Observe el return dentro de la función callback. Si usa echo, la salida ocurre antes de que WordPress construya el resto de la página, «¡Hola mundo!» termina en la parte superior y el contenido circundante se desplaza.

La regla es simple: **un callback de shortcode siempre devuelve un valor mediante ****return**. Nada de echo, print o salida directa de HTML fuera de un búfer.

El hook init es obligatorio

Los desarrolladores de WordPress.org recomiendan enganchar el registro del shortcode a init, no llamar a add_shortcode() directamente en el cuerpo de functions.php. Sin init, es posible que WordPress no haya terminado de inicializar sus mecanismos internos y el shortcode simplemente no se ejecutará.

Sintaxis y parámetros

Firma de la función:

1
add_shortcode( string $tag, callable $callback )

$tag, el nombre del shortcode (sin corchetes). Si dos plugins registran un shortcode con la misma etiqueta, el último anula al anterior. Para evitar conflictos, añada un prefijo único: no [gallery], sino [myplugin_gallery].

$callback, el nombre de la función que devuelve el contenido. Puede pasar una cadena con el nombre de la función, una función anónima o un método de clase (pasando un array [ $object, 'method_name' ]).

Cómo usar shortcodes en el editor

En el editor de WordPress, Gutenberg o Clásico, un shortcode se inserta entre corchetes. Para nuestro ejemplo:

[hello-world]

La forma completa con una etiqueta de cierre también funciona:

[hello-world][/hello-world]

La segunda opción es necesaria cuando se pasa contenido entre las etiquetas (más sobre esto abajo).

Cómo llamar a un shortcode en PHP

En plantillas de tema o plugins, los shortcodes se ejecutan mediante do_shortcode():

1
echo do_shortcode( '[hello-world]' );

La función toma una cadena que contiene un shortcode y devuelve el resultado de su ejecución. Es útil cuando necesita incrustar la salida de un shortcode en la lógica PHP, por ejemplo, en header.php o dentro de un bucle.

Pasar datos a un shortcode: dos formas

Método 1: contenido entre etiquetas

Encierre los datos entre las etiquetas de apertura y cierre:

[hello-world]from John to Mary[/hello-world]

El callback recibe la cadena from John to Mary a través del segundo parámetro $content:

1
// Callback with content substitution between tags
2
function hello_world_shortcode_callback( $attributes, $content, $tag ) {
3
    return 'Hello ' . $content . ' World!';
4
}
5
// Registration
6
function hello_world_shortcode() {
7
    add_shortcode( 'hello-world', 'hello_world_shortcode_callback' );
8
}
9
add_action( 'init', 'hello_world_shortcode' );

Resultado: «Hello from John to Mary World!».

Método 2: atributos

Pase los parámetros directamente en la etiqueta de apertura:

[hello-world from="John" to="Mary"][/hello-world]

En la función callback, los atributos están disponibles a través del primer parámetro $attributes, un array asociativo donde las claves coinciden con los nombres de los atributos:

1
// Callback with reading shortcode attributes
2
function hello_world_shortcode_callback( $attributes, $content, $tag ) {
3
    return 'Hello from ' . $attributes['from'] . ' to ' . $attributes['to'] . '!';
4
}
5
// Registration
6
function hello_world_shortcode() {
7
    add_shortcode( 'hello-world', 'hello_world_shortcode_callback' );
8
}
9
add_action( 'init', 'hello_world_shortcode' );

Salida: «Hello from John to Mary!». Los atributos son mejores para datos estructurados (precio, URL, ID), mientras que el contenido entre etiquetas es mejor para texto arbitrario.

En la práctica, debe añadir inmediatamente shortcode_atts() a los atributos, una función integrada de WordPress que fusiona los atributos pasados con un array de valores predeterminados. Sin ella, acceder a $attributes['from'] lanzará un aviso de PHP si el usuario no especificó el atributo. Con shortcode_atts(), siempre obtiene un array poblado: claves definidas con valores de respaldo, y los atributos desconocidos se filtran automáticamente.

Dos shortcodes listos para usar en WordPress

1. Año actual automático

El shortcode [current-year] inserta el año actual por sí solo, sin necesidad de actualizar la fecha en el pie de página cada enero:

1
// Callback: returns current year via date('Y')
2
function current_year_shortcode_callback( $attributes, $content, $tag ) {
3
    return date( 'Y' );
4
}
5
// Registration of shortcode [current-year]
6
function current_year_shortcode() {
7
    add_shortcode( 'current-year', 'current_year_shortcode_callback' );
8
}
9
add_action( 'init', 'current_year_shortcode' );

Coloque [current-year] en el pie de página o en el texto de la entrada y el año se actualizará automáticamente.

2. Lista de usuarios registrados

El shortcode [users-list] muestra los nombres de todos los usuarios del sitio como una lista con viñetas. Útil en una página de «Equipo» o en informes de administración:

1
// Callback: gets all users and generates HTML list
2
function my_custom_users_list() {
3
    $users = get_users();
4
    $list_html = '<ul>';
5
    foreach ( $users as $user ) {
6
        $list_html .= '<li>' . $user->data->display_name . '</li>';
7
    }
8
    $list_html .= '</ul>';
9
    return $list_html;
10
}
11
// Registration of shortcode [users-list]
12
function register_my_users_list_shortcode() {
13
    add_shortcode( 'users-list', 'my_custom_users_list' );
14
}
15
add_action( 'init', 'register_my_users_list_shortcode' );

get_users() sin argumentos devuelve todos los usuarios. Para limitar la consulta por rol, pase un array: get_users( [ 'role' => 'editor' ] ). El código va en el archivo functions.php del tema activo o en un plugin personalizado.

Vídeo: crear shortcodes en WordPress

Un vídeo corto sobre el tema, registrando un shortcode desde cero, desde escribir la función hasta probarlo en el editor:

⁉️🤔 Preguntas frecuentes

¿Qué sucede si dos plugins registran un shortcode con la misma etiqueta?

WordPress ejecuta el que se cargó en último lugar. El primer shortcode se anula silenciosamente, sin errores. Por eso siempre debe usar un prefijo en sus shortcodes: [acme_gallery] en lugar de [gallery]. Esto elimina conflictos con cualquier otro plugin o tema.

¿Se pueden llamar shortcodes dentro de otros shortcodes?

Sí. Si el callback del primer shortcode devuelve una cadena que contiene la etiqueta del segundo shortcode, WordPress procesa el shortcode anidado automáticamente. Pero no olvide do_shortcode(): si está construyendo contenido manualmente y contiene shortcodes, pase la cadena por do_shortcode() explícitamente. El comportamiento estándar de the_content hace esto por sí solo, pero una llamada directa al callback no.

¿Dónde debe residir el código del shortcode, en el tema o en un plugin?

Los shortcodes personalizados aportan funcionalidad, no apariencia, por lo que es mejor extraerlos en un plugin separado. Cambiar de tema no romperá el sitio: los shortcodes seguirán funcionando. Como mínimo, use un tema hijo si está seguro de que no cambiará el tema padre.

¿Hay restricciones en el nombre de la etiqueta?

El nombre debe consistir en letras latinas, dígitos y guiones. No se permiten espacios, guiones bajos ni caracteres especiales. La longitud recomendada es de hasta 20 caracteres, en minúsculas. Ejemplo: [my-plugin-shortcode].

¿Cómo se depura un shortcode si no muestra nada?

Primer paso, active WP_DEBUG en wp-config.php. Segundo, compruebe que el callback devuelve un valor mediante return, no echo. Tercero, asegúrese de que el hook init está presente. Si no hay errores pero la salida está vacía, añada error_log() dentro del callback y revise los registros del servidor.

Qué recordar sobre los shortcodes de WordPress

Los shortcodes son un mecanismo maduro y estable. add_shortcode() no ha cambiado en años: etiqueta, callback, hook init, return en lugar de echo. Recuerde estas cuatro cosas y cualquier shortcode personalizado funcionará al primer intento.

• Si está mostrando el año en el pie de página, tome el [current-year] listo para usar.
• Si necesita una lista de usuarios, [users-list] con un filtro de rol.
• Si está escribiendo su propio shortcode desde cero, use siempre un prefijo y use siempre init.

Como siguiente paso, investigue cómo empaquetar un shortcode como un plugin independiente y enviarlo al directorio de WordPress.org, es la mejor manera de separar la funcionalidad del tema y elevar su perfil de desarrollador.