Acciones y Filtros en Wordpress: ¿Cual es la Diferencia?

Spanish (Español) translation by Roberto Reta (you can also view the original English article)

Los hooks para las acciones y filtros son una parte fundametal de las variadas APIs de WordPress Sin ellas, estas limitada en cuanto a lo que puedes hacer en tus temas y (especialmente) en tus plugins.

Pero a veces puede ser fácil confundir los dos, especialmente en los casos en que WordPress tiene un hook de acción y un hook de filtro con el mismo nombre.

En este articulo definire a los hooks de acciones y filtros y describire la diferencia entre ambos, y demostrare como usarlos en tus temas y plugins. Tambien dare algunos ejempllos de cuando puedes utilizar cada uno

Cuando añades un hook de acción y hooks de filtro a tu código (o estás enlazando las funciones a ellos), ayuda a entender cómo son llamadas las acciones y los filtros de WordPress y lo que ocurre en qué orden. No cubrire eso en detalle aqui ya que tenemos otro tutorial que hace ese trabajo.

Definiciones y Diferencias

Empezemos con algunas definiciones Definire los hooks de acciones y de filtros tambien, para que puedas verla la diferencia entre todos.

Funciones

Las funciones son la primer cosa con la mayor parte de la gente trabaja cuando estan aprendiendo desarrollo WordPress; si haz añadido codigo al archivo functions.php, entonces haz escrito una funcion.

Las funciones especifican como se hara algo. Programas una funcion para consultar datos, para imprimir contenido , o para hacer muchas otras tareas. Puedes llamar(ejecutar) funciones directamente desde los archivos de la plantilla de tu tema, o puedes enlazar con un hook de accionm o de filtro Las funciones tambien pueden incluir etiquetas de plantilla como etiquetas condicionales, para especificar cuando la funcion se debe aplicar.

Te Mostrare las diferentes maneras de ejecutar funciones despues en este articulo.

Hooks de accion

Los hooks de accion o acciones son disparadas cuando algo pasa, como que se cargue la pagina, un usuario esta iniciando sesion, o una accion personalizada que definiras en tu tema o plugin.

Puedes agregar tu propio hook de acción usando la funcion do_action(), la cual demostrare en en breve. Cualquier funcion que enlazas a una accion entonces correra en este punto del codigo.

Hooks de Filtro

Los hooks de filtro, o filtros, controlan como algo sucede o cambia algo que ya se esta mostrando. Puedes usar un filtro para mostrar metadata en un formato especifico, o para sobreescribir el texto que esta mostrando el plugin, o para prevenir algo que se muestre.

Añades filtros en tu codigo usando la funcion apply_filters(), la cual demostrare en breve. Como la palabra en ingles 'apply' indica , tu puedes aplicar filtros a tu codigo existente, asi como una accion que creas usando do_action() esta vacia hasta que enlazas funciones a este.

Usando Funciones, Acciones y Filtros.

Veamos algunos ejemplos que demuestran como usar cada una de las funciones, acciones y filtros. Primero, veremos como usar funciones directamente en tu codigo sin enlazarlos a un hook.

Llamando Funciones Directamente

Aqui hay un ejemplo de una funcion que es llamada directamente en un archivo de plantilla. En los sitios de mis clientes añado un colofon en el footer, lo cual incluye informacion del copyright. Aqui esta la funcion:

if ( ! function_exists( 'compass_colophon' ) ) {
function compass_colophon() { ?>
    <section class="colophon" role="contentinfo">
  	<small class="copyright left">
			<?php echo compass_copyright(); ?>
			<a href="<?php echo home_url( '/' ) ?>" title="<?php echo esc_attr( get_bloginfo( 'name', 'display' ) ); ?>" rel="home">
			<?php bloginfo( 'name' ); ?>
			</a>
		</small><!-- #copyright -->

		<small class="credits right">
				Powered by <a href="https://wordpress.org/">WordPress</a> and designed by <a href="http://compass-design.co.uk">Compass Design</a>.
			</a>
		</small><!-- #credits -->
	</section><!--#colophon-->
	<?php }
}

Esta funcion es conectable como plugin como lo uso en un tema padre; si yo entonces creo una nueva función con el mismo nombre en mi tema hijo, este sobreescribiria esta función. Nota que la funcion incluye otra función, compass_colophon(), llamandolo directamente en el codigo.

Esta funcion esta en el archivo functions.php de mi tema padre. Puedo llamarlo directamente en el archivo footer.php de mi tema asi:

1	compass_colophon();

Esto muestra el codigo en la funcion en el punto de mi tema donde yo lo llamo. Tambien puedes pasar parametros a tus funciones, las cuales entonces son usadas dentro de la función.

Como se los mostrare en breve, esta función puede tambien ser enlazada a una acción o a un filtro.

Enlazando Funciones y Acciones

En lugar de llamar a esa función de colofón directamente, voy a tener más flexibilidad si enlazo un hook.

Creando Hooks de Acción

En vez de llamar a la funcion compass_colophon() en mi archivo footer, puedo añadir un hook de acción en ese punto del archivo footer.php, añadiendo esto:

1	do_action( 'compass_in_footer' );

La funcion do_action() tiene un parametro obligatorio, que es el nombre de la acción. También opcionalmente puedes añadir argumentos a esta.

Enlazando funciones a acciones

Entonces ahora en vez de llamar a mi funcion de colofón, necesito enlazarla a mi nuevo hook de acción. En mi archivo functions.php, agrego esto con mi función:

1	add_action( 'compass_in_footer', 'compass_colophon' );

Esto enlaza mi función a la acción compass_in_footer, lo cual significa que el codigo dentro de mi función se ejecutara en el punto del codigo donde la accion ha sido puesta. El primer parametro es el nombre del hook de acción, y el segundo es el nombre de mi función.

Una ventaja de hacerlo de esta manera es que puedes enlazar mas de una funcion de la misma accion, y puedes fijar la prioridad para que ellos se ejecuten en el orden que los quieres.

Entonces digamos que tengo otra funcion que quiero enlazar a mi hook compass_in_footer, llamada compass_smallprint(),la cual contiene un poco mas de codigo:

if ( ! function_exists( compass_smallprint() ) ) {
    function compass_smallprint() {
		// contents of function here
	}
}
add_action( 'compass_in_footer', 'compass_smallprint', 20 );

Puedes ver aqui que he añadido un tecer parametro a mi funcion add_action(), la cual es la prioridad. La prioridad por default es 10, la cual sera aplicada si dejas esto en blanco. Entonces porque no he declarado una prioridad para mi función compass_colophon(), poner 20 a la función compass_smallprint() hara que esa función corra despues de la funcion compass_colophon().

Desenlazando Funciones de Acciones

A veces quieres parar una función de correrse, y no puedes sobreescribirla porque no es enlazable. Si la función ha sido enlazada a un hook de acción, entonces puedes hacer esto con la funcion remove_action().

Entonces si quiero prevenir que la función compass_smallprint() se ejecute , la desenlazo de la acción compass_in footer asi:

1	remove_action( 'compass_in_footer', 'compass_smallprint', 20 );

La función remove_action() tiene tres parametros: el nombre del hook de acción, el nombre de la función, y la prioridad con cual la función fue originalmente enlazada a la acción. Debes incluir la prioridad para que esto funcione.

Tambien puedes desenlazar todas las funciones de una acción si quieres prevenir que todas ellas sean ejecutadas. Ten cuidado al hacer esto , ya que puede haber funciones de las que no te das cuenta de ser enlazadas a tu acción

Para hacer esto usa la función remove_all_actions

1	remove_all_actions( 'compass_in_footer' );

Añadir un numero de prioridad como el segundo parametro solo remueve las funciones que estan enlazadas al hook de acción con la prioridad que has especificado, lo cual te da mas control.

Enlazando Funciones a Filtros

Tambien tienes la opción de enlazar funciones a un hook de funciones. Haces esto cuando quieres alterar o sobreescribir codigo que ya existe. Cuando creas un hook del filtro (utilizando la función apply_filters()), envuelva todo el código en tu tema o plugin, el cual luego se altera por cualquier filtro enlazado al hook.

Esto puede ser util si tienes opciones en tu tema o plugin que quieras sobreescribir una opcion por default, o si estas creando un tema padre que puede tener elementos sobreescritos de un tema hijo.

Creando Hooks de Filtro

La función appley_filters() tiene tres parametros : el nombre del hook de filtro, el valor que quieres filtrar(ejem. el valor por default), y variables opcionales las cuales pasaraas a las funciones enlazadas al filtro.

Puedes agregar un filtro en tus archivos de plantilla de tu tema o dentro de una función que esta enlazada por medio de un hook de acción Veamos ambas opciones.

Regresando a mi funcion compass_colophon(), convierto esto a un filtro añadiendo su contenido a mi archivo footer.php dentro de la función apply_filters() asi:

echo apply_filters( 'compass_colophon', '
    <section class="colophon" role="contentinfo">
		<small class="copyright left">
			<?php echo compass_copyright(); ?>
			<a href="<?php echo home_url( '/' ) ?>" title="<?php echo esc_attr( get_bloginfo( 'name', 'display' ) ); ?>" rel="home">
			<?php bloginfo( 'name' ); ?>
			</a>
		</small><!-- #copyright -->

		<small class="credits right">
				Powered by <a href="http://wordpress.org/">WordPress</a> and designed by <a href="http://compass-design.co.uk">Compass Design</a>.
			</a>
		</small><!-- #credits -->
	</section><!--#colophon-->'
);

Esto imprime el codigo que he establecido como el segundo parametro de mi función apply_filters().

Sin embargo, prefiero no añadir esto directamente a mi archivo de plantilla de mi tema, entonces añadire el filtro a la función que estoy enlazando con un hook de acción.

Entonces añado en mi acción compass_in_footer a mi archivo footer.php usando la función do_action() como les demostre arriba, y entonces creo una funcion en mi archivo functions.php que es enlazada a la acción y contiene un filtro:

if ( ! function_exists( 'compass_colophon' ) ) {
function compass_colophon() {
    echo apply_filters( 'compass_colophon_filter', '
		<section class="colophon" role="contentinfo">
			<small class="copyright left">
				<?php echo compass_copyright(); ?>
				<a href="<?php echo home_url( '/' ) ?>" title="<?php echo esc_attr( get_bloginfo( 'name', 'display' ) ); ?>" rel="home">
				<?php bloginfo( 'name' ); ?>
				</a>
			</small><!-- #copyright -->
	
			<small class="credits right">
					Powered by <a href="http://wordpress.org/">WordPress</a> and designed by <a href="http://compass-design.co.uk">Compass Design</a>.
				</a>
			</small><!-- #credits -->
		</section><!--#colophon-->'
	);
}
add_action( 'compass_in_footer', 'compass_colophon' );

Esto significa que puedo ahora sobreescribir el contenido por default en una de tres maneras:

mediante la creación de una nueva función llamada compass_colophon() en mi tema hijo, que reemplaza la función en mi tema padre que es conectable
Desenganchando la función compass_colophon() desde el gancho de acción compass_in_footer y escribiendo una nueva función que pongo en su lugar
mediante la creación de una nueva función que luego enganche el gancho del filtro compass_colophon_filter, que reemplaza el valor en mi función apply_filters()

En la vida real no necesitarás muchas opciones, por lo que es más probable que apliques filtros a parte de los contenidos en tu función.

Por lo que podría crear dos filtros, uno para la sección de derechos de autor y otra para los créditos:

if ( ! function_exists( 'compass_colophon' ) ) {
function compass_colophon() {
    
	echo '<section class="colophon" role="contentinfo">';
		
		echo apply_filters( 'compass_copyright_filter', '
			<small class="copyright left">
				<?php echo compass_copyright(); ?>
				<a href="<?php echo home_url( '/' ) ?>" title="<?php echo esc_attr( get_bloginfo( 'name', 'display' ) ); ?>" rel="home">
				<?php bloginfo( 'name' ); ?>
				</a>
			</small><!-- #copyright -->'
		);
		
		echo apply_filters( 'compass_copyright_filter', '
			<small class="credits right">
					Powered by <a href="http://wordpress.org/">WordPress</a> and designed by <a href="http://compass-design.co.uk">Compass Design</a>.
				</a>
			</small><!-- #credits -->'
		);
	echo '</section><!--#colophon-->';
}
add_action( 'compass_in_footer', 'compass_colophon' );

Entonces tampoco podría sobreescribir toda mi función de compass_colophon desenganchándola o escribiendo una nueva en el tema de hijo, o podría crear una función enganchada al gancho de filtro compass_copyright_filter o compass_credits_filter, para sobreescribir cada elemento individualmente.

Enganchando Funciones a Filtros

Para enganchar una función a un gancho del filtro, utiliza la función add_filter(), que tiene dos parámetros: el nombre del gancho y el nombre de la función.

Así que para cambiar los créditos, debería escribir esta función:

function new_credits() { ?>
    <small class="credits right">
		Powered by <a href="http://wordpress.org/">WordPress</a> and designed by <a href="http://rachelmccollin.co.uk">Rachel McCollin</a>.
			</a>
	</small><!-- #credits -->
<?php }
add_filter( 'compass_credits_filter', 'new_credits' );

Esto invalida el valor establecido en mi gancho de filtro compass_credits_filter original con el contenido de mi función new_credits(), pero mantiene todo lo demás en la función compass_colophon().

También puedes especificar prioridades al enganchar funciones a los filtros, de exactamente la misma manera como con ganchos de acción. Las funciones con menor prioridad se ejecutarán primero.

Desenganchar Funciones de Filtros

Como con los ganchos de la acción, también puedes quitar funciones de filtros. Para ello, utiliza la función remove_filter(), que tiene tres parámetros: el nombre del gancho de filtro, el nombre de la función y la prioridad, que es obligatoria si una prioridad se define cuando la función originalmente fue enganchada al filtro.

Para quitar mi función new_credits(), uso esto:

1	remove_filter( 'compass_credits_filter', 'new_credits' );

La salida de código entonces volverá al valor que especifiqué en mi función apply_filters() original. Así que si quería eliminar la función new_credits() y que no aparezca en su lugar, tendría que añadir una nueva función. Luego desconecto la primera función y engancho mi nueva función así:

function no_credits() {
    return;
}
remove_filter( 'compass_credits_filter', 'new_credits' );
add_filter( 'compass_credits_filter', 'no_credits' );

Resumen

Entender la diferencia entre ganchos de acción y de filtro y ser capaz de usar ambos correctamente impulsará tu desarrollo de temas y plugins. De hecho, sin necesidad de utilizar ganchos de al menos un tipo, no puedes escribir plugins, como la única manera de activar el código en tus plugins es a través de los ganchos de acción y ganchos de filtro a los que está enganchado.

Esta guía le ha mostraron cómo agregar la misma funcionalidad mediante una función, un gancho de acción y uno o más ganchos de filtro, junto con técnicas para quitar las funciones de los ganchos y notar cuando es más útil cada técnica.

Así como enganchar funciones a tu propia acción y ganchos de filtro que crees, puedes engancharlos a las acciones y a los filtros proporcionados por WordPress, como la acción de wp_head o el filtro body_class.