WordPress.org

Ready to get started?Download WordPress

Codex

Function Reference/it:add filter

Contents

Descrizione

Aggancia una funzione ad un specifico filtro.

I filtri sono degli agganci lanciati da Wordpress per modificare qualsiasi forma di testo prima di aggiungerlo al database o prima di stamparlo sullo schermo. Plugins can specify that one or more of its PHP functions is executed to modify specific types of text at these times, using the Filter API. See the Plugin_API/Filter_Reference for a list of filter hooks.

Utilizzo

 <?php add_filter$tag$funzione$priorità$argomenti ); ?> 

Parametri

$tag
(string) (required) Il nome del filtro con cui agganciare la $funzione
Default: None
$funzione
(callback) (required) Il nome della funzione da chiamare quando il filtro viene applicato. Nota: Only string-formatted syntaxes listed in the PHP documentation for the 'callback' type are valid.
Default: None
$priorità
(integer) (optional) Used to specify the order in which the functions associated with a particular action are executed. Lower numbers correspond with earlier execution, and functions with the same priority are executed in the order in which they were added to the action.
Default: 10
$accepted_args
(integer) (optional) The number of arguments the function(s) accept(s). In WordPress 1.5.1 and newer hooked functions can take extra arguments that are set when the matching do_action() or apply_filters() call is run.
Default: 1

Return

The function returns true whether the attempted function hook fails or not. There is no test that the function exists nor whether the $function_to_add is even a string. It is up to you to take care and this is done for optimization purposes, so everything is as quick as possible.

Example

The filter img_caption_shortcode is applied in media.php using the following call:

// Allow plugins/themes to override the default caption template.
$output = apply_filters('img_caption_shortcode', '', $attr, $content);
if ( $output != '' )
	return $output;

The target filter function will be called with three arguments:

  • '' <= This is normally the value the filter will be modifying
  • $attr
  • $content

In order for the filter function to actually receive the full argument list, the call to add_filter() must be modified to specify there are 3 arguments on the parameter list.

add_filter('img_caption_shortcode', 'my_img_caption_shortcode_filter',10,3);

/**
 * Filter to replace the [caption] shortcode text with HTML5 compliant code
 *
 * @return text HTML content describing embedded figure
 **/
function my_img_caption_shortcode_filter($val, $attr, $content = null)
{
	extract(shortcode_atts(array(
		'id'	=> '',
		'align'	=> '',
		'width'	=> '',
		'caption' => ''
	), $attr));
	
	if ( 1 > (int) $width || empty($caption) )
		return $val;

	$capid = '';
	if ( $id ) {
		$id = esc_attr($id);
		$capid = 'id="figcaption_'. $id . '" ';
		$id = 'id="' . $id . '" aria-labelledby="figcaption_' . $id . '" ';
	}

	return '<figure ' . $id . 'class="wp-caption ' . esc_attr($align) . '" style="width: '
	. (10 + (int) $width) . 'px">' . do_shortcode( $content ) . '<figcaption ' . $capid 
	. 'class="wp-caption-text">' . $caption . '</figcaption></figure>';
}

Note

You may need to supply a pointer to the function's namespace for some filter callbacks, e.g.

 <?php add_filter('media_upload_newtab', array(&$this'media_upload_mycallback')); ?> 

Otherwise WordPress looks in its own namespace for the function, which can cause abnormal behaviour.

In WordPress 1.5.1+, hooked functions can take extra arguments that are set when the matching do_action() or apply_filters() call is run. For example, the action comment_id_not_found will pass any functions that hook onto it the ID of the requested comment.

You can also pass the callback paramater as an anonymous function, for example:  <?php add_filter('the_title', function($title) { return '<b>'$title'</b>';}) ?> 

Beware

Anonymous functions [1] were introduced in PHP 5.3.0. Check Hosting WordPress requirements and double check your PHP version before using them.

If your version of PHP is older than 5.3.0, you can use create_function() [2] instead. But keep in mind that lambda functions created by create_function() are not cached by APC or any other optimizer [3]. So don't use create_function() if callback is supposed to be used more than few times or it has complex logic.

Change Log

  • Since: 0.71

Sorgenti

add_filter() è situato in wp-includes/plugin.php.

Simili

Filters: has_filter(), add_filter(), apply_filters(), current_filter(), merge_filters(), remove_filter(), remove_all_filters()

See also index of Function Reference and index of Template Tags.
This article is marked as in need of editing. You can help Codex by editing it.