Skip to content

add_action add_filter

dezembro 21, 2011

Hooks: Actions e Filters

Classes e Funções usadas: 

Categoria: Codex | Nenhum comentário

Um importante recurso a ser explorado para o desenvolvimento de soluções no WordPress é a utilização dosHooks que o sistema disponibiliza. Os Hooks são certas funções e identificadores que servem como ganchos (dada sua nomenclatura) para execução de instruções personalizadas. Significa dizer que através do uso dos hooks é possível informar ao sistema quando e como ele deve chamar determinada função.

Existem dois tipos de ganchos oferecidos pelo WordPress: Actions e Filters. As Actions, são ações executadas em determinados momentos pelo sistema; são atividades executadas mediante o disparar de um evento, como por exemplo o publicar de um post.

Os Filters, são os filtros da informação; através de suas aplicações o desenvolvedor consegue modificar ou como o próprio nome diz, filtrar os dados enviados pelo usuário ou resgatados do banco de dados antes que estes sejam exibidos ou armazenados.

Motivos para utilização dos Hooks

Em alguns casos quando se faz necessário alterar o modo de funcionamento do WordPress, é comum desenvolvedores realizarem tais alterações diretamente no código-fonte do CMS. No entanto essa prática é pouco recomendada, pois assim que o sistema for atualizado é bem provável que as alterações se percam e tenham que ser realizadas novamente. Usar os ganchos do WordPress é um jeito seguro de alterar o comportamento e as atividades executadas pela ferramenta.

A própria programação do sistema é realizada em grande parte com base nos Hooks. Veja por exemplo a utilização das Include Tags que se baseiam nesse princípio, assim como a incorporação de scripts ao WordPress que ocorre em razão do uso de ganchos.

Actions – Eventos do WordPress

Para adicionar ações ao WordPress é preciso fazer uso da função add_action via programação PHP com os seguintes parâmetros:

add_action ( 'nome_do_gancho', 'sua_funcao', [prioridade], [argumentos_aceitos] );
  • Nome do gancho – Um evento fornecido pelo sistema (veja a Referência de ações no Codex), a ele será incorporada sua função;
  • Sua função – Ao disparar do referido evento, a função aqui atribuída será executada;
  • Prioridade – Determina a ordem de execução das funções associadas ao gancho, por padrão seu valor é 10. Números menores são executados primeiro, e em caso de valores iguais respeita-se a ordem de adição das funções;
  • Argumentos aceitos – Número inteiro que determina a quantidade de argumentos a serem passados para a função, possui valor 1 como padrão.

Estilo personalizado para a tela de login

Em um exemplo de aplicação, é possível editar a tela de login do seu template incorporando uma folha de estilo específica na página de entrada do sistema mediante o uso de:

function add_login_style() {
	wp_enqueue_style( 'login' );
}
add_action( 'login_head', 'add_login_style' );

Os parâmetros Prioridade e Argumentos aceitos são opcionais, caso não os informe, os valores padrões serão adotados para a ação criada.

Filters – Filtrando informação

De maneira semelhante a incorporação de ações ao sistema, para se incluir um filtro a ele é preciso fazer uso da função add_filter e seus respectivos parâmetros:

add_filter ( 'nome_do_gancho', 'sua_funcao', [prioridade], [argumentos_aceitos] );

Uma grande diferença na função a ser utilizada é que ela deverá possuir um valor de retorno ou de impressão usando os recursos return ou echo do PHP, por exemplo. Assim como para as Actions, os valores Prioridade eArgumentos aceitos da função que adiciona os Filters, são opcionais.

Alterando a exibição do conteúdo

Para demonstrar a utilização dos filtros, o exemplo abaixo irá suprimir todas as tags HTML do conteúdo dos posts resgatados antes de exibí-los para o visitante:

function content_only_text( $content ) {
	return strip_tags( $content );
}
add_filter( 'the_content', 'content_only_text' );

Fonte: http://www.guiawp.com.br/codex/hooks-actions-filters/

=================================================

=================================================

=================================================

Michael Fields

Hi Betsy, I hope this explains everything!

So, are filters a subset of actions?

They are basically the same function applied to different contexts. If you take a peek into the core, you will see that add_action is actually a wrapper function for add_filter:

function add_action($tag, $function_to_add, $priority = 10, $accepted_args = 1) { return add_filter($tag, $function_to_add, $priority, $accepted_args); }

it seems I could use an action to change the text of the post for instance, instead of a filter?

Actually, you would use a filter for this situation. Let’s pretend that WordPress is a Mexican restaurant and we have ordered a taco as illustrated by the following code…

<?php $taco = 'chicken'; ?>

Basically, we have no choice… we will always be served a chicken taco. However, the same expression could be stated using the apply_filters() function. It is like ordering a taco and having the server ask you “well what kind of taco would you like?”

<?php $taco = apply_filters( 'get_taco', 'chicken' ); ?>

The above code gives us access to the type of taco that we would like to have served. We can create a function which hooks into WordPress an changes the default value of$taco.

<?php add_filter( 'get_taco', 'my_special_order' ); function my_special_order( $content ) { return 'shredded beef'; } ?>

By adding the above code to you theme’s functions.php file or to a custom plugin, you are able to change the value of the variable $taco to whatever you like. Notice that the function “my_special_order” accepts one value. In this situation the value of$content is equal to the value of the second argument passed to the apply_filters() function. In this example it would be “chicken”.

<?php add_filter( 'get_taco', 'my_special_order' ); function my_special_order( $content ) { return $content . ' and avocado'; } ?>

The above code appends a string to the end of “chicken” resulting in a value of “chicken and avocado”.

what would be a good example of correctly using filters while actions would be inappropriate for the situation?

Basically, there usually is no choice for a plugin or theme developer as to which method they can use. The WordPress core is filled with calls to apply_filters() anddo_action(). If I need to change the value of a piece of data, I will search through the core until I locate the file where that data is defined and see if it is possible to filter it’s value.

If I need to do something at a certain time, I will look for calls to the do_action() hook. A simple example would be if I wanted to print custom css to the head of the document. I could easily add the following code to my theme’s functions.php file:

<?php add_action( 'wp_head', 'print_my_custom_scripts' ); function print_my_custom_scripts(){ print '<style type="text/css">.red{color:#f00;}</style>'; } ?>

Notice how this time, the function did not return a value – it did something -> it printed text to the browser.

Filters change data while actions allow us to do stuff.

when should I use an action and when a filter?

You would want to use an action where you need to do something at a certain point in time… add options to the database or print css or javascript.

You should use a filter where you would want to alter the value of some data that WordPress has passed through the apply_filters() function.

do the ‘hooks’ for actions and filters overlap? -can I add a either a filter or an action to the same hook?

Actually, both filters and actions are hooks. That being said, the answer is “no”.

http://wordpress.org/support/topic/fliters-vs-actions-from-a-newbe

Anúncios
No comments yet

Deixe um comentário

Preencha os seus dados abaixo ou clique em um ícone para log in:

Logotipo do WordPress.com

Você está comentando utilizando sua conta WordPress.com. Sair / Alterar )

Imagem do Twitter

Você está comentando utilizando sua conta Twitter. Sair / Alterar )

Foto do Facebook

Você está comentando utilizando sua conta Facebook. Sair / Alterar )

Foto do Google+

Você está comentando utilizando sua conta Google+. Sair / Alterar )

Conectando a %s

%d blogueiros gostam disto: