Adicionando Funções à sua Framework Para Temas de WordPress

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

No último post dessa série, você adicionou alguns ganchos de ação à sua framework para temas. Nesse tutorial, você criará algumas funções para ativar esses ganchos.

Se você tem usado o código de exemplo, terá seis ganchos em sua framework:

wptp_in_header, aquela que fica no topo, no lado direito do cabeçalho
wptp_before_content, que vem logo antes do loop
wptp_after_content, que vem logo depois do loop
wptp_sidebar, que fica no arquivo sidebar.php
wptp_footer, que fica dentro do elemento footer
wptp_after_footer, que fica após o elemento footer.

Nesse tutorial, mostrarei como adicionar áreas de widget a três desses ganchos e uma função customizada ao último.

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 Áreas de Widget Através de Funções

O primeiro passo é adicionar a função para as áreas de widget. Você talvez lembre que elas foram codificadas, originalmente, nos arquivos relevantes do modelo. Contudo, adicioná-las através de funções permite que os usuários de sua framework possam sobrescrever a função em um momento futuro, seja removendo as áreas de widget ou substituindo por outra coisa.

Criando um Arquivo de Inclusão para a Área de Widget

Já que as áreas de widget são adicionadas através de funções, você não as codificará nos arquivos relevantes do modelo. Você poderia adicioná-las a seu arquivo functions.php, porém, para manter o código administrável/manutenível, criaremos um arquivo de inclusão com o código para as áreas de widget.

Crie um diretório chamado includes dentro da pasta do seu tema e, dentro dele, crie um arquivo widgets.php. Salve esse arquivo.

Agora, abra seu arquivo functions.php e adicione o trecho a seguir antes de suas outras funções:

// inclusão dos widgets
include( TEMPLATEPATH . '/includes/widgets.php' );

Esse trecho traz o conteúdo do arquivo widgets.php para essa posição do arquivo de funções.

Agore, salve seu arquivo de funções.

A Área de Widget no Cabeçalho

Primeiro, adicionaremos a área de widget no cabeçalho. Abra seu arquivo widgets.php e adicione isso:

function wptp_in_header_widget_area() {
    if ( is_active_sidebar( 'in-header-widget-area' ) ) { ?>
  	<aside class="in-header widget-area" role="complementary">
			<?php dynamic_sidebar( 'in-header-widget-area' ); ?>
		</aside>
	<?php }
}
add_action( 'wptp_in_header', 'wptp_in_header_widget_area' );

A função wptp_in_header_widget_area() adiciona o código para a área de widget no lugar correto. Primeiro, ele verifica se a área de widget está populada com widgets, usando if( is_active_sidebar), e então, se estiver preenchido, ele retorna o widget num elemento aside.

A função é ativada através do gancho de ação wptp_in_header, que adicionamos ao arquivo header.php no tutorial passado. Ele substitui o código da área de widget que, antes, estava localizado no arquivo header.php em si.

Fazendo assim, permitimos que você remova a área de widget em um site que use um tema filho do seu tema, bastando usar a função remove_action(), dessa forma:

remove_action( 'wptp_in_header', 'wptp_in_header_widget_area' );

Isso também significa que você pode adicionar funcionalidades extras que podem ser ativadas através do mesmo gancho, então, se quisesse adicionar um botão de ação acima da área de widget, por exemplo, você criaria uma função contendo o código respectivo e a anexaria ao gancho de ação wptp_in_header, com uma prioridade menor que 10, uma vez que essa é a prioridade padrão que será dada à função da área de widget acima. Funções com uma prioridade menor são chamadas primeiro.

function wptp_add_cta() {
    //código para o botão de ação
}
add_action( 'wptp_in_header' , 'wttp_add_cta', 5 );

Você pode aprender mais sobre a função add_action() no WordPress Codex.

Uma Área de Widget na Lateral

O próximo passo é adicionar a área de widget na lateral, usando um trecho de código parecido com o que você já usou em seu arquivo widgets.php:

function wptp_sidebar_widget_area() {
    if ( is_active_sidebar( 'sidebar-widget-area' ) ) { ?>
		<aside class="sidebar widget-area" role="complementary">
			<?php dynamic_sidebar( 'sidebar-widget-area' ); ?>
		</aside>
	<?php }
}
add_action( 'wptp_sidebar', 'wptp_sidebar_widget_area' );

Esse trecho adiciona uma área de widgets à lateral, desde que ela esteja populada, usando as classes relevantes para que possa ser estilizada.

A Área de Widgets do Rodapé

Finalmente, adicionaremos widgets no rodapé. Adicionarei quatro áreas de widgets lá - você pode adicionar menos widgets, se quiser. Minha área de widget usa classes que lançam mão de CSS Orientado a Objetos usado no meu tema.

Novamente, no arquivo widgets.php, adicione o trecho a seguir:

function wptp_footer_widget_area() { ?>

    <aside class="fatfooter" role="complementary">

		<?php
		// a primeira área de widgets
		if ( is_active_sidebar( 'first-footer-widget-area' ) ) { ?>
			<aside class="first quarter left widget-area">
				<?php dynamic_sidebar( 'first-footer-widget-area' ); ?>
			</aside><!-- .first .widget-area -->
		<?php }

		// a segunda área de widgets
		if ( is_active_sidebar( 'second-footer-widget-area' ) ) { ?>
			<aside class="second quarter widget-area">
				<?php dynamic_sidebar( 'second-footer-widget-area' ); ?>
			</aside><!-- .first .widget-area -->
		<?php }

		// a terceira área de widgets
		if ( is_active_sidebar( 'third-footer-widget-area' ) ) { ?>
			<aside class="third quarter widget-area">
				<?php dynamic_sidebar( 'third-footer-widget-area' ); ?>
			</aside><!-- .first .widget-area -->
		<?php }

		// a quarta área de widgets
		if ( is_active_sidebar( 'fourth-footer-widget-area' ) ) { ?>
			<aside class="fourth right quarter widget-area">
				<?php dynamic_sidebar( 'fourth-footer-widget-area' ); ?>
			</aside><!-- .first .widget-area -->
		<?php } ?>

	</aside>

<?php
}
add_action( 'wptp_footer', 'wptp_footer_widget_area' );

Isso adicionará quatro áreas de widgets dentro de um elemento aside com a classe fatfooter - em meu tema, isso é usado para estilização, signficando que um plano de fundo integral pode ser aplicado ao elemento footer, enquanto o elemento aside.fatfooter pode ser centralizado na tela.

Tendo adicionado widgets à minha área de widgets, você pode ver como ela está agora:

Adicionando uma função ao Cólofon

Assim como áreas de widgets, adicionarei uma função ao meu tema que insere um texto no cólofon. Ele será ativado através do gancho wptp_after_footer, assim, ele ficará bem no final da tela.

Como isso não é um widget, adicionarei o código no meu arquivo functions.php:

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="http://wordpress.org/">WordPress</a>.
			</a>
		</small><!-- #credits -->
	</section><!--#colophon-->

<?php
}

Isso adiciona um elemento section com o código para o cólofon. Agora, você pode ver o cólofon em meu site:

Como pode ver, o texto padrão para o link dos direitos de autorais (copyright) é o título do site. Se eu quiser sobrescreve-lo em um tema filho, posso fazê-lo, facilmente, criando uma nova função atrelada ao gancho de ação wptp_after_footer e removendo a ação original usando remove_action():

remove_action( 'wptp_after_footer', 'wptp_colophon' );

Alternativamente, poderia tornar minha função original em uma função plugável, que significa que ela não fica ativada quando outra função com o mesmo nome já foi encontrada pelo WordPress (em um tema filho, por exemplo). Eu faria isso envolvendo a função em um código condicional, dessa forma:

if ( ! function_exists( 'wptp_colophon' ) ) {
    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( 'Proudly powered by', 'tutsplus' ); ?> <a href="http://wordpress.org/">WordPress</a>.
				</a>
			</small><!-- #credits -->
		</section><!--#colophon-->

	<?php
	}

}
add_action( 'wptp_after_footer', 'wptp_colophon' );

Se eu adicionar uma função wptp_colophon ao meu tema, o WordPress a executará ao invés da do tema pai. Bem legal, hein?

Note que, nesse caso, uma solução melhor para lidar com o texto de direitos autorais seria envolver o cógigo em um gancho de filtro. Cobriremos mais sobre ele em uma parte futura dessa série.

Conclusão

Sua Framework para Temas de WordPress, agora, tem algumas funções. Nesse tutorial, mostramos como usar ganchos de ação que você criou em artigos anteriores para ativar funções adicionadas ao arquivo functions.php ou em um arquivo de inclusão criado para seu tema.

No primeiro artigo dessa série, mencionei que uma framework para temas madura é muito mais que um tema pai: é um ecosistema. Isso significa que você usará muitos ganchos de ação em seu tema para ativar funções em plugins escritos, especificamente, para sites usando a framework, ou em um tema filho dela.

Várias das mais populares frameworks para temas de WordPress fazem isso e não há razão para não fazê-lo também. Por exemplo, talvez você crie um plugin para adicionar laterais adicionais a um site e, então, ativá-las através de um gancho chamado wptp_sidebar.

Isso poderia ser muito útil se o plugin for usado em mais de um site, de forma que você pode replicar tal funcionalidades em temas filhos relevantes. Já fiz isso várias vezes, quando o site precisou de laterais para listar páginas na mesma parte da hierarquia de uma página - é um código genérico bastante útil em mais de um site.

Na próxima parte dessa série, você aprenderá como adicionar ganchos de filtro à sua framework.

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