简码API

0条评论

简码API

简码API

简码API(应用程序接口)是WordPress 2.5的新功能。简码API是一个简单的函数集,这些函数创建宏代码以供在文章内容中使用。下面是一个普通简码:

[gallery]  

简码API简化了支持属性的简码的创建:

[gallery id="123" size="medium"]  

API进行所有解析,避免为每个简码编写自定义正则表达式。添加帮助函数以设置并获取默认属性。API同时支持封闭简码和自闭(自动封闭)简码。

下面是一个通过属性创建简码的PHP简单实例,为大家提供快速入门通道:

// [bartag foo="foo-value"]
function bartag_func($atts) {
	extract(shortcode_atts(array(
		'foo' => 'no foo',
		'bar' => 'default bar',
	), $atts));

	return "foo = {$foo}";
}
add_shortcode('bartag', 'bartag_func');

以上实例生成一个"[bartag]"简码,该简码支持两个属性:[bartag foo="something" bar="something else"]。这是两个可选属性,若用户未选择,属性使用默认选项。

简码API概述

简码由处理函数编写。简码处理器与WordPress过滤器大致相同:两者都接收参数(属性)并返回结果(简码输出)。

add_shortcode()函数用于记录简码处理器。该函数使用两个参数:简码名称(文章正文中所用的字符串)以及处理函数名称。

简码处理函数可接收一到两个属性:属性数组$atts以及封闭文本$content(根据简码是否可用于封闭形式选择性使用该属性)。例如:

function my_shortcode_handler($atts, $content=null) {  
}  

调用API以记录简码处理器,操作如下:

add_shortcode('my-shortcode', 'my_shortcode_handler');  

显示 the_content时,简码API会对所有有记录的简码(如 "[my-shortcode]")进行解析。如果存在属性和内容,简码还会将这些属性和内容逐一分开并进行解析, 最后将相应的简码处理函数传递给这些属性和内容。简码处理器返回(非响应)的字符串被插入文章正文,取代简码。

以下简码属性:

[my-shortcode foo="bar" baz="bing"]  

将被转换为以下关联数组并传递给处理函数,即$atts参数:

array( 'foo' => 'bar', 'baz' => 'bing')  

数组关键字为属性名称,数组值即相应的属性值。

属性

原始$atts数组中可能包含用户所指定的任意自由属性。API中的shortcode_atts()函数可帮助丢失属性设置默认值,并消除简码不可识别的属性。

shortcode_atts()函数类似于wp_parse_args()函数,但与wp_parse_args()仍有一些主要差异。shortcode_atts()函数的参数为:

shortcode_atts( $defaults_array, $atts );  

两个参数都是必需的。 $defaults_array 是一个关联数组,它规定了所识别出属性的名称和默认值。$atts是传递到简码处理器时的原始属性。 shortcode_atts()将返回一个正规的、包括 $defaults_array中所有关键字的数组, 若$atts数组存在, $atts返回的值将被填入$defaults_array。例如:

$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' )。

在简码处理器重声明默认值以及解析属性时,建议使用代码方式为:

function my_shortcode_handler( $atts, $content = null ) {
   extract( shortcode_atts( array(
      'attr_1' => 'attribute 1 default',
      'attr_2' => 'attribute 2 default',
      // ...etc
      ), $atts ) );
}

这样既可以解析属性,设置默认值,又可以删除所有不支持的属性,将结果存储(使用extract())在以属性关键字 $attr_1, $attr_2命名的本地变量中,等等。 换言之, 默认值数组近似于本地变量声明列表。(在此情况下可安全使用extract()处理各种冲突而无须特别标识,这是因为shortcode_atts()将清除默认数组外所有关键字。)

输出

简码处理函数的返回值将被插入文章内容,代替原有简码宏的位置。记住使用“返回”,而非“响应”——所有“响应”内容都会输出到浏览器而不会出现在页面的相应位置上。

应用 wpautopwptexturize 文章格式(关于2.5.0与2.5.1版本的不同之处,请留意下文中的“注意”)后,简码会被解析。这就意味着,简码HTML输出不能自动使用引用,也不能自动添加p标签以及br标签。如果用户希望预先设定简码输出格式,可以在从简码处理器返回输出结果时直接调用wpautop() 或 wptexturize()。

wpautop辨别简码语句并试图不包装独立成行的p标签以及br标签。若以这种方式使用简码,应确保用相应的block标签包装输出结果,如<p>或 <div>。

注意:在WordPress 2.5.0中,应用文章格式前就会解析简码,因此简码HTML输出有时会被p标签或br标签包裹。WordPress 2.5.1修正了这一缺陷。

封闭简码VS自动封闭简码

以上示例显示的都是自动封闭的代码宏,如 [my-shortcode]。API也支持 [my-shortcode]content[/my-shortcode]等封闭简码。

用简码宏关闭内容时,处理函数会接收另一个包含内容的参数。用户可能会用另一种方式来编写简码,因此程序需要能够同时允许大小写字母,通过设置处理函数的第二个参数默认值,可以实现这一功能:

function my_shortcode_handler( $atts, $content = null )  

is_null($content)可分辨自动封闭标签和封闭标签。

文章内容关闭后,函数输出结果将取代含有内容的完整简码宏。处理函数需要提供原始内容字符串的缺失情况以及加密情况,并在结果中加入缺失或加密的字符串。

以下是加密简码的简单示例:

function caption_shortcode( $atts, $content = null ) {
   return '<span class="caption">' . $content . '</span>';
}
add_shortcode('caption', 'caption_shortcode');  

使用以下方式时:

[caption]My Caption[/caption]  

输出结果则是:

<span class="caption">My Caption</span>  

$content没有缺失也没有加密,因此用户可以加入原始HTML:

[caption]<a href="http://example.com/">My Caption</a>[/caption]  

这将生成:

<span class="caption"><a href="http://example.com/">My Caption</a></span>  

这可能是有意识行为,也可能不是——若简码不允许在结果中输出原始HTML,可在返回结果前用缺失或过滤函数进行处理。

简码解析器不支持嵌套简码。这表示,如果简码处理器的$content参数含有其他简码,将不解析简码:

[caption]Caption: [my-shortcode][/caption]  

这会生成:

<span class="caption">Caption: [my-shortcode]</span>  

若封闭简码希望允许输出结果出现其他简码,处理函数可递归调用do_shortcode():

function caption_shortcode( $atts, $content = null ) {
   return '<span class="caption">' . do_shortcode($content) . '</span>';
}

以上代码可保证封闭内容中的 "[my-shortcode]"宏被解析,且输出结果被标题span关闭:

<span class="caption">Caption: The result of my-shortcode's handler function</span>  

封闭简码支持属性的方式与自动封闭简码相同。以下是可支持“class”属性的caption_shortcode()示例:

function caption_shortcode( $atts, $content = null ) {
   extract( shortcode_atts( array(
      'class' => 'caption',
      ), $atts ) );
 
   return '<span class="' . attribtue_escape($caption) . '">' . $content . '</span>';
}
[caption class="headline"]My Caption[/caption]  
<span class="headline">My Caption</span>  

其他功能简介

  • 解析器支持xhtml样式的封闭简码,如"[my-shortcode /]"等,该功能可选
  • 简码宏可能为属性值使用单个或双个引用,若属性值中没有空格,可以完全不使用引用。 [my-shortcode foo='123' bar=456] 等于 [my-shortcode foo="123" bar="456"]。
  • 考虑到原有简码的兼容性,属性名称会被忽略。若某属性没有名称,系统会将$atts数组中的一个位置数值型关键字作为属性名称。例如,[my-shortcode 123]会生成$atts = array( 0 => 123 )。位置属性与有名称的属性可能混杂在一起,若属性值中含有空格或其它明显字符,可以使用引用。
  • 简码API有测试实例。测试中包括错误情况示例和异常语句,可在http://svn.automattic.com/wordpress-tests/wp-testcase/test_shortcode.php试用测试实例。

函数引用

以下简码API函数可用:

function add_shortcode($tag, $func)  

记录新的简码处理函数。$tag是用户所编写的简码字符串(无括号),如"my-shortcode"。$func是处理函数的函数名称。

在一个已知简码中只能存在一个处理函数。用$tag名称再次调用add_shortcode()会改写原有处理函数。

function remove_shortcode($tag)  

删除已有简码的记录。$tag是用在add_shortcode()中的简码名称。

function remove_all_shortcodes()  

删除所有简码的记录:

function shortcode_atts($pairs, $atts)  

为了$pairs所指定的默认值,对属性原始数组$atts进行操作。 结果包括$pairs中每个关键字,并混合了$atts的返回值。任何存在于$atts但不存在于$pairs的关键字都将被忽略。

function do_shortcode($content)  

解析 $content字符串中所有已知简码宏。返回含有原始内容的字符串,并用处理函数的输出结果代替简码宏。

记录do_shortcode()时,将它作为 一个优先级为11的'the_content'默认过滤器。

局限

当简码处理函数递归调用do_shortcode()时,简码解析器才可正确处理嵌套简码宏:

[tag-a]
   [tab-b]
      [tag-c]
   [/tag-b]
[/tag-a]

递归调用的同时,如果使用简码宏来关闭另一个宏,解析器将不能成功解析:

[tag-a]
   [tag-a]
   [/tag-a]
[/tag-a]

这就是do_shortcode()所使用的上下文无关的正则表达式解析器的局限性——运行速度快,但不能计算嵌套级别,因此解析器不能正确匹配所有开放标签与相应的关闭标签。

外部资源