Uso de filtros personalizados con códigos cortos

Una vez que comprenda la API de Shortcode y cómo funcionan los filtros, es fácil implementarlos en WordPress.

Y cuando puede mezclar los dos, puede hacer mucho más de lo habitual que cuando funcionan de forma independiente.

Específicamente, puede filtrar los datos que se encuentran en el resultado del shortcode, y esto puede ser especialmente útil para otros desarrolladores. Si está familiarizado con la implementación de filtros personalizados, hacerlo dentro del contexto de un código corto no es muy diferente.

Pero si nunca antes ha usado la API de shortcode o la funcionalidad, todavía es fácil de hacer.

Filtros personalizados con códigos cortos

Para esta publicación, usaremos un ejemplo relativamente artificial. Es decir, el shortcode resultará en algo estático. La razón es que facilita la demostración en una publicación y la implementación en su código.

El código corto

Para implementar un shortcode, necesitas dos cosas:

1. un nombre personalizado para el shortcode,
2. una función que se usa para colocar información en cualquier lugar donde se use el shortcode.

<?php

namespace Acme;

add_shortcode('a_simple_example', __NAMESPACE__. 'aSimpleExample');
/**
 * Replaces [a_simple_example] short code with the text "This is the result of an example shortcode."
 * whenever the shortcode is placed in a post or page.
 */
function aSimpleExample()
{
  return 'This is the result of an example shortcode.';
}

Nota en el código de arriba; He prefijado la función con. __NAMESPACE__Esto se debe a que la función reside dentro de un espacio de nombres personalizado (que puede ver en la parte superior del archivo).

Sin este prefijo, no se llamará a la función. Si opta por no usar espacios de nombres, puede renunciar tanto al prefijo como a las barras inclinadas iniciales del nombre de su función.

Tenga en cuenta que revisaremos esta función tan pronto como tengamos el filtro en su lugar.

El filtro

Agregar un filtro personalizado es similar a agregar un shortcode. Necesitas:

1. un nombre de filtro personalizado,
2. una función que se usa para filtrar la información entrante (y los filtros generalmente deben aceptar al menos un parámetro que es, por supuesto, los datos a filtrar):

Para mantener la coherencia con el ejemplo anterior, digamos que solo queremos reemplazar algunas palabras en el código abreviado :

<?php

namespace Acme;

add_filter('custom_shortcode_example', __NAMESPACE__. 'aSimpleShortcodeFilter');
/**
 * Replaces [a simple example] short code with the text "This is the result of an example shortcode."
 * whenever the shortcode is placed in a post or page.
 *
 * @param string $input the input to filter.
 *
 * @return string       the result of the filter running on the input
 */
function aSimpleShortcodeFilter(string $input): string
{
  return str_ireplace(
    'an example shortcode.',
    'a filtered shortcode',
    $input
  );
}

Esto reemplazará el contenido de:

Este es el resultado de un shortcode de ejemplo.

A:

Este es el resultado de un shortcode filtrado.

Pero todavía tenemos que unirlos a los dos.

Revisando el código corto

Para asociar las dos funciones, debemos asegurarnos de que la función del shortcode aplique el filtro al valor que devuelve.

Afortunadamente, implementarlo es simple, especialmente porque tenemos todo lo que necesitamos:

<?php

namespace Acme;

add_shortcode('a_simple_example', __NAMESPACE__. 'aSimpleExample');
/**
 * Replaces [a_simple_example] short code with the text "This is the result of an example shortcode."
 * whenever the shortcode is placed in a post or page.
 */
function aSimpleExample()
{
  return apply_filters('custom_shortcode_example', 'This is the result of an example shortcode.');
}

En un ejemplo más concreto, siempre recomiendo verificar que el resultado del parámetro no esté vacío, que contenga la cadena que estoy buscando o algo similar.

Es decir, a menudo me gusta abrir con una cláusula de guardia. Si la prueba falla, simplemente devuelvo el valor entrante; de lo contrario, filtraré los datos y devolveré el resultado de esa operación.