WordPress:Template Tags/How to Pass Tag Parameters
介绍
模板标签是PHP函数,你可以将这个函数插入到你的WordPress网页模板,提供动态的博客内容。而且与PHP函数类似,许多模板标签接受实参或者形参。模板标签参数是变数,你可以使用这些变数更改标签的产出或者在某种方式上,更改标签的运行。将参数看做是用户选项或者设置,能使你定义一个模板标签是怎样运行的。
[关于参数,WordPress模板标签有三种不同的"flavors。"如下面所描述的:
没有参数的标签
有些模板标签没有任何选项,你也就没有什么参数可以传递给这些模板标签。
the_author_firstname()就是一个不接受任何参数的模板标签。这个标签指示显示文章作者的名。没有参数的标签在标签函数开始和结束的括号(括号)之间没有任何内容: <?php the_author_firstname(); ?>
PHP函数样式的参数的标签
对于能够接受参数的标签,有的要求是默认PHP 样式。对于这些标签,通过将一个或者几个参数值放到函数的括号或者括弧内部,参数可以传递到标签函数中。
bloginfo()标签接受一个参数(是show参数),这个参数使得标签明白你的博客上显示什么内容:
%%% <?php bloginfo('name'); ?>%%%
wp_title()标签接受两个参数:第一个参数是sep或者叫分隔符参数,第二个叫echo或者叫显示参数:
%%% <?php wp_title(' - ', TRUE); ?> %%%
第一个参数包含在一个单引号中,第二个参数没有包含在单引号中,因为第一个参数是一个string,而第二个参数是一个boolean参数。(请看看参数类型 上关于参数类型以及怎样使用这些不同类型的参数的信息。)
牢记PHP函数样式的参数的要点:
- 有的函数拥有几个参数。
- 几个参数由逗号分开。
- 参数的顺序非常重要!
当向模板标签的函数传递参数的时候,要确定你为所有的参数都规定了参数值直到你想要规定的最后一个参数的参数值,否则的话,标签就不会如你所愿地那样运行。例如,模板标签get_archives()拥有六个参数:
%%% <?php get_archives('type', 'limit', 'format', 'before',
'after', show_post_count); ?> %%%
以你喜欢的方式显示归档列表,假如你只需要更改第三个(format和第五个 (after)参数。要实现更改,你需要确定为第一个参数,第二个,和第四个参数输入了默认值:
%%%<?php get_archives(
, , 'custom', , '
');
?>%%%
注意使用单引号表示empty参数值,在这个例子中,迫使这些特别的参数规定为默认值。要了解当传递一个空参数,如一个参数规定了一个文本字符串的时候,参数的默认值就会被覆盖了,而且不能传递一个空boolean参数值。因此你要查看关于参数默认设置的文件,如果有特别规定,可以将其用作你的参数值(也看看参数类型上关于参数类型的信息)。第六个参数被遗弃了;因为WordPress为任何没有特别规定参数值的参数使用默认值。
要确定仔细地遵循了模板标签的文件说明,并且将你的参数按模板函数要求排列。最后,在模板标签中为所有的参数使用默认值,使用没有特别规定参数值的标签:
%%%<?php get_archives(); ?>%%%
拥有查询字符串样式参数的标签
模板标签的最后一种类型利用了查询字符串样式,向标签传递参数。这些提供了一个便利的标签的'包装函式',这个函式使用了PHP 函数参数样式和一个相关的数值较大的参数。例如,模板标签wp_list_cats()是list_cats()的包装函式,list_cats(),一个拥有十八个参数的标签!
如果你想在list_cats()中设置'删除参数(参数列表上有十七个参数),并且将剩余的参数保持为默认设置,你需要:
<?php list_cats(TRUE, 'All', 'ID', 'asc', '', TRUE, FALSE, FALSE,
TRUE, TRUE, FALSE, '', '', FALSE, '', '', '10,11,12'); ?>
或者你可以使用wp_list_cats():
<?php wp_list_cats('exclude=10,11,12'); ?>
因此查询字符串格式标签是有用的,因为这些标签能够使你更改你需要的参数的参数值,但是不需要提供所有的参数或者近乎所有的参数的参数值。然而,并不是所有的PHP函数样式的模板标签都有一个查询字符串样式的等同物。(同时注意接受query-string样式的参数的名称,通常以'wp_'作为前缀,例如wp_list_cats(),但是你要查看标签的文件,确定标签接受参数的方法。)
标签wp_list_authors()有六个参数,我们在这里设置了其中的三个参数: <?php wp_list_authors('show_fullname=1&feed=rss&optioncount=1'); ?>
首先,所有的参数在一起,都是由单引号或者双引号括起来的。每个参数都输入进了parameter=value格式,但是这些是由一个&(&)分开的。Broken down,上述显示的标签声明:
- 参数 show_fullname (boolean 样式的参数) 等同于1 (true)。
- 和
- 参数feed (string 样式参数)等同于 rss。
- 和
- 参数 optioncount (boolean 样式参数)等同于1 (true)。
(请看看 参数类型关于参数样式以及怎样使用这些参数样式的信息。)
query-string样式的参数不需要以一个特别的顺序输入。真正需要在意的是确保参数名称的拼写是正确的。如果参数名不容易读出,你可以用空格分开参数:
<?php wp_list_authors('show_fullname=1 & feed=rss & optioncount=1'); ?>
你也可以将query-string扩展在几行上(注意将每个参数/参数值放入一个单引号和以一个点号开始一个新行):
<?php wp_list_authors(
'show_fullname=1' .'&feed=rss' .'&optioncount=1' ); ?>
There are a few limitations when using query-string style tags, among which you cannot pass certain characters, such as the ampersand or a quote mark (single or double). In those cases, you can use an associative array:
使用query-string格式标签有一些限制,你不可以传递某些字符,例如&符号和引号(单引号或者双引号)。在这些情况下,你可以使用一个联合的数组:
<?php $params = array( 'type' => 'postbypost',
'limit' => 5, 'format' => 'custom', 'before' => '<li>• ', 'after' => '</li>' ); wp_get_archives($params); ?>
参数的类型
关于WordPress模板标签,你需要了解三种类型的参数:字符串,整数和boolean。每个参数的处理都有所不同,如下面所描述的:
字符串
一个字符串是一行文本,而且通常是一个单独的字符或者几十个单词。一个字符串参数通常是从两个或者多个有效的选项中选择的,就如bloginfo()中的show参数。否则的话,字符串是一个显示的文本,例如wp_title()中的sep参数。
使用PHP 函数参数格式的标签,字符串参数值应该包含在一个单引号(')或者双引号(")之中。如果单引号或者双引号需要部分的字符串,将引号混合使用(如果单引号存在在你的参数值中,使用双引号包裹参数),或者使用PHP escape参数(一个反斜线符号: \),如下所执行的,为the_title()中的before和after参数指定单引号。
<?php the_title('\'', '\''); ?>
整数
整数是一个整数,而且可以有正整数(1,2,3)或者负整数(-1,-2,-3)。整数参数通常用作日期和归档方面的信息,如get_month_link()标签中的年和 月参数,或者用来规定你的博客上的数值信息,如get_permalink()中的id参数。
当传递到PHP函数参数格式标签中的时候,引号内或者引号外的整数值都会得到合适地处理。因此下面的两个例子都是有效的:
<?php get_permalink('100'); ?>
<?php get_permalink(100); ?>
Boolean
Boolean参数提供了一个简单的true/false评价。
例如,the_date()标签有echo参数,将TRUE 或者 FALSE作为参数值;将参数设置为TRUE,能在网页上显示日期,然而FALSE导致标签"返回"日期作为参数值,用于其它的PHP代码。
一个boolean参数可以表示为一个数值:1表示TRUE, 0表示FALSE。对于PHP函数参数样式标签中的一个boolean参数值,这些都是对等值:
- 1 = TRUE = true
- 0 = FALSE = false
然而,不要将boolean参数值放入双引号中。query-string样式标签只使用数字式的boolean参数值(1 or 0)。