Adicionando Ganchos de Filtro à Sua Framework para Temas de WordPress

Portuguese (Português) translation by Erick Patrick (you can also view the original English article)

Até agora, você adicionou ganchos de ação à sua framework para temas e também criou algumas funções que são ativadas através desses ganchos. O próximo passo é adicionar alguns filtros, que darão ainda mais flexibilidade a você.

Uma Breve Revisão Sobre Ganchos de Ação e de Filtro

Antes de continuarmos, é interessante darmos uma repassada nas diferenças entre ganchos de ação e de filtro:

Ações são ativadas em pontos específicos do seu código. O gancho de ação em si não contém qualquer código que seja executado, mas provê um local no código que permite você fazer as coisas acontecerem, através de funções ativadas por esses ganchos.
Filtros, por outro lado, permitem que sejam feitas alterações em códigos já escritos no seu tema. Ao invés de virem vazios, um gancho de filtro é envolvido por um código existente, o qual você pode aumentar ou sobrescrever usando a função atrelada ao gancho.

Para mais detalhes, veja esse excelente guia sobre ganchos de ação e de filtro.

Como Criar e Usar um Gancho de Filtro

1	<?php
2	apply_filters( 'my_filter', 'código que será filtrado virá aqui' );
3	?>

Daí, você acessa o gancho do filtro usando a função add_filter() , como a seguir:

<?php
function my_function() {
    // código da função aqui
}
add_filter( 'my_filter', 'my_function' );
?>

O que você adicionar na função substituirá o código filtrável na sua framework, então, será aqui onde você fará suas mudanças ou sobrescritas.

O Que Você Precisará

Para acompanhar esse tutorial, você precisará de:

Um ambiente para desenvolvimento com o WordPress;
Seu próprio tema ou os arquivos do tema criados na Parte 3 dessa série, os quais você pode encontrar no repositório do GitHub que acompanha a série;
Um editor de código

Adicionando Ganchos de Filtro

Nesse tutorial, adicionarei três ganchos de filtro à framework:

No cabeçalho, envolverei os título e descrição do site em um filtro;
No rodapé, adicionarei um filtro à função do cólofon que adicionamos no tutorial passado

Isso significa que, no futuro, ambos poderão ser aprimorados ou sobrescritos por temas filhos ou plugins. Você pode adicionar vários outros filtros ao seu tema de WordPress: em qualquer lugar que adicionar código que tenha chance de mudar posteriormente, você pode usar um filtro que permita mudanças sem a necessidade de criação de um novo arquivo de modelo em um tema filho.

Adicionando um Gancho de Filtro ao Título e Descrição do Site

Comecemos pelos título e descrição do site. Abra o arquivo header.php do tema e busque pelo seguinte trecho:

<div class="site-name half left">
    <!-- nome do site e descrição - nome do site dentro de um elemento div em todas as páginas, exceto na página inicial ou página principal da área do blog, onde está envolto em um elemento h1 -->
  <h1 id="site-title">
		<a href="<?php echo home_url(); ?>" title="<?php echo esc_attr( get_bloginfo( 'name', 'display' ) ); ?>" rel="home"><?php bloginfo( 'name' ); ?></a>
	</h1>
	<h2 id="site-description"><?php bloginfo( 'description' ); ?></h2>
</div>

Ao invés de escrever um filtro para tudo isso, é melhor adicionar um filtro para ambos o título e descrição, assim, você pode aprimorar ou modificar totalmente o retorno de um ou dos dois.

Em cada caso, você substituirá a função bloginfo() com a função get_bloginfo(), e adicionará a função echo antes da função apply_filters(). Comecemos com o título. Edite o código dentro do elemento h1 para que fique assim:

<h1 id="site-title">
    <a href="<?php echo home_url(); ?>" title="<?php echo esc_attr( apply_filters( 'wptutsplus_sitetitle', get_bloginfo( 'name', 'display' ) ) ); ?>" rel="home">
        <?php echo apply_filters( 'wptutsplus_sitetitle', get_bloginfo( 'name' ) ); ?>
    </a>
</h1>

Como pode ver, adicionei a função apply_filters() duas vezes aqui - uma para atributo title do link e outra para o texto que será mostrado. O nome código usado segue abaixo:

1	<?php echo apply_filters( 'wptutsplus_sitetitle', get_bloginfo( 'name' ) ); ?>

Isso cria um filtro chamado wptutsplus_sitetitle, aplicando-o à função get_bloginfo( 'name' ). Por fim, ele é impresso na página.

Agora, façamos o mesmo com a descrição da página. Dessa vez será um pouco mais simples, já que não há link envolvido. Edite o elemento h2 para que fique assim:

1	<h2 id="site-description">
2	<?php echo apply_filters( 'wptutsplus_sitedescription', get_bloginfo( 'description' ) );?>
3	</h2>

Novamente, isso não afetará o conteúdo apresentado pelo elemento, mas fornecerá um filtro o qual poderá usar para alterá-lo futuramente.

Adicionando um Gancho de Filtro ao Cólofon

Agora, adicionaremos um filtro ao cólofon, que está contido em uma função no arquivo functions.php. Isso permitirá os usuários da minha framework aumentar ou sobrescrever o conteúdo do cólofon.

Primeiramente, abra seu arquivo functions.php e ache o seguinte trecho de código:

function wptp_colophon() { ?>
    <section class="colophon" role="contentinfo">
		<small class="copyright half left">
			&copy; <a href="<?php echo home_url( '/' ) ?>"><?php bloginfo( 'name' ); ?></a> 2014
		</small><!-- #copyright -->

		<small class="credits half right">
			<?php _e( 'Orgulhosamente desenvolvido por', 'tutsplus' ); ?>
            <a href="https://wordpress.org/">WordPress</a>.
		</small><!-- #credits -->
	</section><!--#colophon-->

<?php
}

Agora, remova a linha que retorna o nome do blog dentro do link e envolva cada uma das duas funções em uma função apply_filters(), deixando assim:

function wptp_colophon() { ?>
    <section class="colophon" role="contentinfo">
		<small class="copyright half left">
			&copy<a href="<?php echo apply_filters( 'wptp_colophon_link', home_url( '/' ) ?>">) ?>"><?php echo apply_filters('wptp_colophon_name', get_bloginfo( 'name' ) ); ?></a> 2014
		</small><!-- #copyright -->

		<small class="credits half right">
			<?php _e( 'Orgulhosamente desenvolvido por', 'tutsplus' ); ?>
            <a href="http://wordpress.org/">WordPress</a>.
		</small><!-- #credits -->
	</section><!--#colophon-->

<?php
}

Aqui, criei dois filtros:

echo apply_filters( 'wptp_colophon_link', home_url( '/' ) refere-se ao link para o qual o nome aponta;
echo apply_filters('wptp_colophon_name', get_bloginfo( 'name' ) ) refere-se ao nome em si

Se quisesse alterar algum desses elementos posteriormente, poderia fazê-los criando duas funções simples, dessa forma:

function wptp_amend_colophon_name() {

	$name = 'Rachel McCollin';
	return $name;

}
add_filter( 'wptp_colophon_name', 'wptp_amend_colophon_name' );

function wptp_amend_colophon_link() {

	$link = 'http://rachelmccollin.co.uk';
	return $link;

}
add_filter( 'wptp_colophon_link', 'wptp_amend_colophon_link' );

Cada uma dessas funções retorna conteúdo estático no lugar da função PHP no filtro original, substituindo a url da página inicial e o nome do blog pela url do meu blog e pelo meu nome, respectivamente:

Conclusão

Aqui, adicionei alguns filtros simples que permitirão os usuários da sua framework alterar o retorno das funções, sem a necessidade de criar novos arquivos de modelo. Como vimos, um filtro é diferente de uma ação, já que ele permite você alterar o resultado de algo a partir de um gancho, ao invés de adicionar algo totalmente novo a gancho vazio.

Em alguns casos, talvez perceba que o filtro tornou-se muito complexo, o que forçará você a criar uma nova função ou, em algumas outras vezes, criar um novo arquivo de modelo inteiramente novo. Por exemplo, se quiséssemos fazer mudanças significativas ao cólofon, adicionaríamos uma nova função, wptp_colophon(), ao tema filho - uma vez que a função wptp_colophon() na framework é plugável, a nova função sobrescreveria a existente. Mas, se quiséssemos substituir todo o rodapé, teríamos de criar um arquivo footer.php inteiramente novo.

Filtros podem ser bastante úteis na hora de evitar grandes reescritas - quando você criar os arquivos do modelo da sua framework, considere o que o conteúdo retornado que seus usuários quererão aumentar ou modificar e o envolva em uma função apply_filters().

Seja o primeiro a saber sobre novas traduções–siga @tutsplus_pt no Twitter!