Function Reference/add filter

来自WordPress中文文档
跳转至: 导航搜索

wordpress.org.cn

Description

Hook a function to a specific filter action.

Usage

%%% <?php add_filter( $tag, $function_to_add, $priority, $accepted_args ); ?> %%%

Parameters

tt$tag/tt
(string) (required) The name of the existing Filter to Hook the $function_to_add argument to. You can find a list of Filter Hooks here.
Default: Nonenoinclude

div class=template-description style=padding: 0 1.5em; border: 1px solid #eeeeee; background-color: #f9f9f9

Notes

This template is for standardizing how parameters look in the Function Reference and in Template Tags. Here is an example of this template being called: prenowiki检查到模板循环:模板:Parameter/nowiki/pre 检查到模板循环:模板:Parameter

The usage of this template is below: prenowiki检查到模板循环:模板:Parameter/nowiki/pre Let's take a closer look at the parameters..

name
The name of the parameter.
datatype
The datatype that should be given for this parameter when called.
  • string
  • integer
  • boolean
  • mixed
description
A short description of the parameter.
importance
Set this parameter to optional if the parameter is optional. Otherwise, do not declare this parameter—it defaults to required.
  • required
  • optional
default
If this parameter is optional, ttdefault/tt is the value that will be used if the parameter is not declared.

wordpress.org.cn /div /noinclude

tt$function_to_add/tt
(callback) (required) The name of the function to be called when the custom Filter is applied.
Default: Nonenoinclude

div class=template-description style=padding: 0 1.5em; border: 1px solid #eeeeee; background-color: #f9f9f9

Notes

This template is for standardizing how parameters look in the Function Reference and in Template Tags. Here is an example of this template being called: prenowiki检查到模板循环:模板:Parameter/nowiki/pre 检查到模板循环:模板:Parameter

The usage of this template is below: prenowiki检查到模板循环:模板:Parameter/nowiki/pre Let's take a closer look at the parameters..

name
The name of the parameter.
datatype
The datatype that should be given for this parameter when called.
  • string
  • integer
  • boolean
  • mixed
description
A short description of the parameter.
importance
Set this parameter to optional if the parameter is optional. Otherwise, do not declare this parameter—it defaults to required.
  • required
  • optional
default
If this parameter is optional, ttdefault/tt is the value that will be used if the parameter is not declared.

wordpress.org.cn /div /noinclude

tt$priority/tt
(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: 10noinclude

div class=template-description style=padding: 0 1.5em; border: 1px solid #eeeeee; background-color: #f9f9f9

Notes

This template is for standardizing how parameters look in the Function Reference and in Template Tags. Here is an example of this template being called: prenowiki检查到模板循环:模板:Parameter/nowiki/pre 检查到模板循环:模板:Parameter

The usage of this template is below: prenowiki检查到模板循环:模板:Parameter/nowiki/pre Let's take a closer look at the parameters..

name
The name of the parameter.
datatype
The datatype that should be given for this parameter when called.
  • string
  • integer
  • boolean
  • mixed
description
A short description of the parameter.
importance
Set this parameter to optional if the parameter is optional. Otherwise, do not declare this parameter—it defaults to required.
  • required
  • optional
default
If this parameter is optional, ttdefault/tt is the value that will be used if the parameter is not declared.

wordpress.org.cn /div /noinclude

tt$accepted_args/tt
(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: 1noinclude

div class=template-description style=padding: 0 1.5em; border: 1px solid #eeeeee; background-color: #f9f9f9

Notes

This template is for standardizing how parameters look in the Function Reference and in Template Tags. Here is an example of this template being called: prenowiki检查到模板循环:模板:Parameter/nowiki/pre 检查到模板循环:模板:Parameter

The usage of this template is below: prenowiki检查到模板循环:模板:Parameter/nowiki/pre Let's take a closer look at the parameters..

name
The name of the parameter.
datatype
The datatype that should be given for this parameter when called.
  • string
  • integer
  • boolean
  • mixed
description
A short description of the parameter.
importance
Set this parameter to optional if the parameter is optional. Otherwise, do not declare this parameter—it defaults to required.
  • required
  • optional
default
If this parameter is optional, ttdefault/tt is the value that will be used if the parameter is not declared.

wordpress.org.cn /div /noinclude

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>';
}

Notes

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 ''. $title. '';}) ?> %%%

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

Source File

add_filter() is located in onlyincludecodewp-includes/plugin.php/code/onlyinclude

div class=template-description style=padding: 0 1.5em; border: 1px solid #eeeeee; background-color: #f9f9f9

Template Description

Link to the source code on http://core.trac.wordpress.org/browser/.

Parameters

  1. filename
  2. (option) path to codetag/code (version) or codetrunk/code. This option is only used for a new function.br /Default: codetrunk/code -- trunk is the latest bleeding edge development version of WordPress.

Usage

Link to the stable version: pre检查到模板循环:模板:Trac/pre

Link to trunk: pre检查到模板循环:模板:Trac/pre

/div

wordpress.org.cn.

Related

Filters: has_filters, add_filter, apply_filters, current_filter, merge_filters, remove_filter, remove_all_filters

includeonlydiv style=clear:both; background-color:#F7F7F7; border:1px solid #CCCCCC; color:#000000; padding:7px; margin:0.5em auto 0.5em auto; vertical-align:middle;See also index of Function Reference and index of Template Tags./div/includeonlynoinclude

Description

This Template is used by Codex:Template Messages.

Usage

pre 检查到模板循环:模板:Message /pre

Result

检查到模板循环:模板:Message

/noinclude