Usando filtros personalizados com códigos de acesso

Depois de entender a API Shortcode e como os filtros funcionam, é fácil implementá-los no WordPress.

E quando você consegue misturar os dois, pode fazer muito mais do que o normal do que quando eles estão operando independentemente um do outro.

Especificamente, você pode filtrar dados que estão no resultado do shortcode, e isso pode ser especialmente útil para outros desenvolvedores. Se você estiver familiarizado com a implementação de filtros personalizados, fazer isso no contexto de um código curto não é muito diferente.

Mas se você nunca usou a API de shortcode ou a funcionalidade antes, ainda é fácil de fazer.

Filtros personalizados com códigos de acesso

Para este post, usaremos um exemplo relativamente artificial. Ou seja, o shortcode resultará em algo estático. O motivo é que facilita a demonstração em um post e a implementação em seu código.

O código de acesso

Para implementar um shortcode, você precisa de duas coisas:

1. um nome personalizado para o shortcode,
2. uma função que é usada para colocar informações onde quer que o shortcode seja usado.

<?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.';
}

Observe no código acima; Eu prefixei a função com. __NAMESPACE__Isso ocorre porque a função reside em um namespace personalizado (que você pode ver na parte superior do arquivo).

Sem este prefixo, a função não será chamada. Se você optar por não usar namespaces, poderá renunciar ao prefixo e às barras iniciais do nome da função.

Observe que revisitaremos essa função assim que tivermos o filtro instalado.

O filtro

Adicionar um filtro personalizado é semelhante a adicionar um shortcode. Você precisa:

1. um nome de filtro personalizado,
2. uma função que é usada para filtrar as informações recebidas (e os filtros geralmente devem aceitar pelo menos um parâmetro que é, obviamente, os dados a serem filtrados):

Para manter a consistência com o exemplo acima, digamos que queremos apenas substituir algumas palavras no shortcode :

<?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
  );
}

Isso substituirá o conteúdo de:

Este é o resultado de um shortcode de exemplo.

Para:

Este é o resultado de um shortcode filtrado.

Mas ainda temos que amarrar os dois juntos.

Revisitando o Shortcode

Para associar as duas funções, precisamos ter certeza de que a função do shortcode aplica o filtro ao valor que ele retorna.

Felizmente, implementá-lo é simples, especialmente porque temos tudo o que precisamos:

<?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.');
}

Em um exemplo mais concreto, sempre recomendo verificar se o resultado do parâmetro não está vazio, se contém a string que estou procurando ou algo semelhante.

Ou seja, muitas vezes gosto de abrir com uma cláusula de guarda. Se o teste falhar, eu apenas retorno o valor recebido; caso contrário, filtrarei os dados e retornarei qualquer que seja o resultado dessa operação.