Codex tools: Log in
Languages: English • Italiano • Русский • (Add your language)
Contents |
Hooks a function to a specific filter action.
Filters are the hooks that WordPress launches to modify text of various types before adding it to the database or sending it to the browser screen. 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.
<?php add_filter( $tag, $function_to_add, $priority, $accepted_args ); ?>
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.
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:
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>';
}
You can also pass a class method as a callback.
Static class method:
<?php add_filter('media_upload_newtab', array('My_Class', 'media_upload_callback')); ?>
Instance method:
<?php add_filter('media_upload_newtab', array($this, 'media_upload_callback')); ?>
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 the comment ID to each callback.
You can also pass an an anonymous function as a callback. For example:
<?php add_filter('the_title', function($title) { return '<b>'. $title. '</b>';}) ?>
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.
add_filter() is located in wp-includes/plugin.php.
Filters: has_filter(), add_filter(), apply_filters(), current_filter(), merge_filters(), remove_filter(), remove_all_filters()