[url]http://cn.yflying.com/2010/07/wordpress%E4%B8%AD%E7%9A%84%E7%AE%80%E7%A0%81%E6%9C%BA%E5%88%B6/[/url]
简码API(应用程序接口)是WordPress >=2.5的新功能。简码API是一个简单的函数集,这些函数创建宏代码以供在文章内容中使用。
简码示例
下面示例中的每一行都是一个简码,分别展示了简码的各种不同的形式。
1
2
3
4
5
6
[mycode]
[mycode foo="bar" id="123" color="red" something="data"]
[mycode]Some Content[/mycode]
[mycode]<p><a href="http://example.com/">HTML Content</a></p>[/mycode]
[mycode]Content [another-shotcode] more content[/mycode]
[mycode foo="bar" id="123"]Some Content[/mycode]
简码API/函数
以下简码API函数可用:
add_shortcode($tag, $func),注册新的简码。$tag是用户所编写的简码字符串(无括号),如”my-shortcode”。$func是处理函数的函数名称。在一个已知简码中只能存在一个处理函数。用$tag名称再次调用add_shortcode()会改写原有处理函数。
remove_shortcode($tag),注销该简码。$tag是用在add_shortcode()中的简码名称。
remove_all_shortcodes(),注销所有的简码。
shortcode_atts($pairs, $atts),对简码的属性进行解析,$pairs指定了一组关键字和默认值,$atts是需要进行解析的参数。 结果包括$pairs中每个关键字,并混合了$atts的返回值。任何存在于$atts但不存在于$pairs的关键字都将被忽略。
do_shortcode($content),解析 $content字符串中所有已知简码宏。返回含有原始内容的字符串,并用处理函数的输出结果代替简码宏。do_shortcode()是’the_content’上一个优先级为11的默认过滤器:add_filter(‘the_content’, ‘do_shortcode’, 11); // From shortcodes.php。
简码API对所有简码进行解析,避免为每个简码编写自定义的正则表达式。并且如果存在属性和内容,简码还会将这些属性和内容逐一进行解析, 最后将这些属性和内容传递给相应的简码处理函数。简码处理器返回的字符串被插入文章正文,取代简码。
API同时支持封闭简码和自闭(自动封闭)简码,其他功能还包括:
解析器支持xhtml样式的封闭简码,如”[my-shortcode /]“等,该功能可选。
简码宏可能为属性值使用单个或双个引用,若属性值中没有空格,可以完全不使用引用。 [my-shortcode foo='123' bar=456] 等于 [my-shortcode foo="123" bar="456"]。
考虑到原有简码的兼容性,属性名称会被忽略。若某属性没有名称,系统会将$atts数组中的一个位置数值型关键字作为属性名称。例如,[my-shortcode 123]会生成$atts = array( 0 => 123 )。位置属性与有名称的属性可能混杂在一起,若属性值中含有空格或其它明显字符,可以使用引用。
简码API有测试实例。测试中包括错误情况示例和异常语句,可在此试用测试实例。
动手编写简码
实现一个简码主要包括两个部分:a)实现简码处理函数;b)将简码添加到记录。如下:
1
2
3
4
5
6
7
8
9
function my_shortcode_handler( $atts, $content = null ) {
extract( shortcode_atts( array(
'attr_1' => 'attribute 1 default',
'attr_2' => 'attribute 2 default',
// ...etc
), $atts ) );
return "<h2>Attributes</h2>" . print_r($attr, true) . "<h2>content</h2>" . $content;
}
add_shortcode('my-shortcode', 'my_shortcode_handler');
这样在显示the_content时,会触发”the_content”钩子上的filter,相应此简码处理函数也会被调用。
属性
原始$atts数组中可能包含用户所指定的任意自由属性。API中的shortcode_atts()函数可为丢失属性设置默认值,并消除简码不可识别的属性。shortcode_atts()函数类似于wp_parse_args()函数,但与wp_parse_args()仍有一些主要差异。shortcode_atts()函数的参数为:
1
shortcode_atts( $defaults_array, $atts );
两个参数都是必需的。 $defaults_array 是一个关联数组,它规定了所识别出属性的名称和默认值。$atts是传递到简码处理器时的原始属性。 shortcode_atts()将返回一个正规的、包括 $defaults_array中所有关键字的数组, 若$atts数组存在, $atts返回的值将被填入$defaults_array。例如:
1
2
3
4
$a = shortcode_atts( array(
'title' => 'My Title'
'foo' => 123,
), $atts );
如果$atts 中要包括数组( ‘foo’ => 456, ‘bar’ => ‘something’ ), 原有结果$a将会变为数组( ‘title’ => ‘My Title’, ‘foo’ => 456 )。$atts['foo']的值改写了默认值123。由于未设置$atts['title'],’My Title’ 将被作为默认值。默认数组中没有“bar”选项,因此返回的结果中也没有这个选项。
将属性名称传递到处理函数前,需要将名称转换为小写字母。属性值无需改变。 [my-shortcode FOO="BAR"]将会生成$atts = array( ‘foo’ => ‘BAR’ )。属性结果将存储(使用extract())在以属性关键字 $attr_1, $attr_2命名的本地变量中。 换言之, 默认值数组近似于本地变量声明列表。(在此情况下可安全使用extract()处理各种冲突而无须特别标识,这是因为shortcode_atts()将清除默认数组外所有关键字。)
输出
简码处理函数的返回值将被插入文章内容,代替原有简码宏的位置。
应用 wpautop与wptexturize 文章格式后,简码会被解析。这就意味着,简码HTML输出不能自动使用引用,也不能自动添加p标签以及br标签。如果用户希望预先设定简码输出格式,可以在从简码处理器返回输出结果时直接调用wpautop() 或 wptexturize()。
wpautop辨别简码语句并试图不包装独立成行的p标签以及br标签。若以这种方式使用简码,应确保用相应的block标签包装输出结果。
嵌套处理
简码API默认是不会处理嵌套简码,处于内层的简码会被当作外层简码的普通内容来处理。但是,如果你想是自己的简码支持嵌套,可以通过递归调用do_shortcode()实现,示例如下:
1
2
3
4
5
6
7
8
9
function my_shortcode_handler( $atts, $content = null ) {
extract( shortcode_atts( array(
'attr_1' => 'attribute 1 default',
'attr_2' => 'attribute 2 default',
// ...etc
), $atts ) );
return "<h2>Attributes</h2>" . print_r($attr, true) . "<h2>content</h2>" . do_shortcode($content);
}
add_shortcode('my-shortcode', 'my_shortcode_handler');
局限
当简码处理函数递归调用do_shortcode()时,简码解析器才可正确处理嵌套简码宏:
1
2
3
4
5
[tag-a]
[tab-b]
[tag-c]
[/tag-b]
[/tag-a]
递归调用的同时,如果使用简码宏来关闭另一个宏,解析器将不能成功解析:
1
2
3
4
[tag-a]
[tag-a]
[/tag-a]
[/tag-a]
这就是do_shortcode()所使用的上下文无关的正则表达式解析器的局限性——运行速度快,但不能计算嵌套级别,因此解析器不能正确匹配所有开放标签与相应的关闭标签。
简码API(应用程序接口)是WordPress >=2.5的新功能。简码API是一个简单的函数集,这些函数创建宏代码以供在文章内容中使用。
简码示例
下面示例中的每一行都是一个简码,分别展示了简码的各种不同的形式。
1
2
3
4
5
6
[mycode]
[mycode foo="bar" id="123" color="red" something="data"]
[mycode]Some Content[/mycode]
[mycode]<p><a href="http://example.com/">HTML Content</a></p>[/mycode]
[mycode]Content [another-shotcode] more content[/mycode]
[mycode foo="bar" id="123"]Some Content[/mycode]
简码API/函数
以下简码API函数可用:
add_shortcode($tag, $func),注册新的简码。$tag是用户所编写的简码字符串(无括号),如”my-shortcode”。$func是处理函数的函数名称。在一个已知简码中只能存在一个处理函数。用$tag名称再次调用add_shortcode()会改写原有处理函数。
remove_shortcode($tag),注销该简码。$tag是用在add_shortcode()中的简码名称。
remove_all_shortcodes(),注销所有的简码。
shortcode_atts($pairs, $atts),对简码的属性进行解析,$pairs指定了一组关键字和默认值,$atts是需要进行解析的参数。 结果包括$pairs中每个关键字,并混合了$atts的返回值。任何存在于$atts但不存在于$pairs的关键字都将被忽略。
do_shortcode($content),解析 $content字符串中所有已知简码宏。返回含有原始内容的字符串,并用处理函数的输出结果代替简码宏。do_shortcode()是’the_content’上一个优先级为11的默认过滤器:add_filter(‘the_content’, ‘do_shortcode’, 11); // From shortcodes.php。
简码API对所有简码进行解析,避免为每个简码编写自定义的正则表达式。并且如果存在属性和内容,简码还会将这些属性和内容逐一进行解析, 最后将这些属性和内容传递给相应的简码处理函数。简码处理器返回的字符串被插入文章正文,取代简码。
API同时支持封闭简码和自闭(自动封闭)简码,其他功能还包括:
解析器支持xhtml样式的封闭简码,如”[my-shortcode /]“等,该功能可选。
简码宏可能为属性值使用单个或双个引用,若属性值中没有空格,可以完全不使用引用。 [my-shortcode foo='123' bar=456] 等于 [my-shortcode foo="123" bar="456"]。
考虑到原有简码的兼容性,属性名称会被忽略。若某属性没有名称,系统会将$atts数组中的一个位置数值型关键字作为属性名称。例如,[my-shortcode 123]会生成$atts = array( 0 => 123 )。位置属性与有名称的属性可能混杂在一起,若属性值中含有空格或其它明显字符,可以使用引用。
简码API有测试实例。测试中包括错误情况示例和异常语句,可在此试用测试实例。
动手编写简码
实现一个简码主要包括两个部分:a)实现简码处理函数;b)将简码添加到记录。如下:
1
2
3
4
5
6
7
8
9
function my_shortcode_handler( $atts, $content = null ) {
extract( shortcode_atts( array(
'attr_1' => 'attribute 1 default',
'attr_2' => 'attribute 2 default',
// ...etc
), $atts ) );
return "<h2>Attributes</h2>" . print_r($attr, true) . "<h2>content</h2>" . $content;
}
add_shortcode('my-shortcode', 'my_shortcode_handler');
这样在显示the_content时,会触发”the_content”钩子上的filter,相应此简码处理函数也会被调用。
属性
原始$atts数组中可能包含用户所指定的任意自由属性。API中的shortcode_atts()函数可为丢失属性设置默认值,并消除简码不可识别的属性。shortcode_atts()函数类似于wp_parse_args()函数,但与wp_parse_args()仍有一些主要差异。shortcode_atts()函数的参数为:
1
shortcode_atts( $defaults_array, $atts );
两个参数都是必需的。 $defaults_array 是一个关联数组,它规定了所识别出属性的名称和默认值。$atts是传递到简码处理器时的原始属性。 shortcode_atts()将返回一个正规的、包括 $defaults_array中所有关键字的数组, 若$atts数组存在, $atts返回的值将被填入$defaults_array。例如:
1
2
3
4
$a = shortcode_atts( array(
'title' => 'My Title'
'foo' => 123,
), $atts );
如果$atts 中要包括数组( ‘foo’ => 456, ‘bar’ => ‘something’ ), 原有结果$a将会变为数组( ‘title’ => ‘My Title’, ‘foo’ => 456 )。$atts['foo']的值改写了默认值123。由于未设置$atts['title'],’My Title’ 将被作为默认值。默认数组中没有“bar”选项,因此返回的结果中也没有这个选项。
将属性名称传递到处理函数前,需要将名称转换为小写字母。属性值无需改变。 [my-shortcode FOO="BAR"]将会生成$atts = array( ‘foo’ => ‘BAR’ )。属性结果将存储(使用extract())在以属性关键字 $attr_1, $attr_2命名的本地变量中。 换言之, 默认值数组近似于本地变量声明列表。(在此情况下可安全使用extract()处理各种冲突而无须特别标识,这是因为shortcode_atts()将清除默认数组外所有关键字。)
输出
简码处理函数的返回值将被插入文章内容,代替原有简码宏的位置。
应用 wpautop与wptexturize 文章格式后,简码会被解析。这就意味着,简码HTML输出不能自动使用引用,也不能自动添加p标签以及br标签。如果用户希望预先设定简码输出格式,可以在从简码处理器返回输出结果时直接调用wpautop() 或 wptexturize()。
wpautop辨别简码语句并试图不包装独立成行的p标签以及br标签。若以这种方式使用简码,应确保用相应的block标签包装输出结果。
嵌套处理
简码API默认是不会处理嵌套简码,处于内层的简码会被当作外层简码的普通内容来处理。但是,如果你想是自己的简码支持嵌套,可以通过递归调用do_shortcode()实现,示例如下:
1
2
3
4
5
6
7
8
9
function my_shortcode_handler( $atts, $content = null ) {
extract( shortcode_atts( array(
'attr_1' => 'attribute 1 default',
'attr_2' => 'attribute 2 default',
// ...etc
), $atts ) );
return "<h2>Attributes</h2>" . print_r($attr, true) . "<h2>content</h2>" . do_shortcode($content);
}
add_shortcode('my-shortcode', 'my_shortcode_handler');
局限
当简码处理函数递归调用do_shortcode()时,简码解析器才可正确处理嵌套简码宏:
1
2
3
4
5
[tag-a]
[tab-b]
[tag-c]
[/tag-b]
[/tag-a]
递归调用的同时,如果使用简码宏来关闭另一个宏,解析器将不能成功解析:
1
2
3
4
[tag-a]
[tag-a]
[/tag-a]
[/tag-a]
这就是do_shortcode()所使用的上下文无关的正则表达式解析器的局限性——运行速度快,但不能计算嵌套级别,因此解析器不能正确匹配所有开放标签与相应的关闭标签。