[WORDPRESS系列]常用函数

wpautop
简介

将文本中的两个换行符转换成 HTML 段落 （<p>...</p>），其余的换行转换成 <br />

WordPress 使用这个函数对日志内容和摘要进行格式化处理。

用法

<?php wpautop( $foo, $br ); ?>

参考：http://blog.wpjam.com/function_reference/wpautop/

post相关函数

the_category()
the_category() 是用来调用日志的在的所有类别的 PHP 函数

_e();
Displays the returned translated text from translate().
为了使文字内容支持多语言，格式化输出

在 WordPress 中 __ 函数和 _e 函数被用来识别 php 文件中被标示的、需要被翻译成其它语言或本地化的字符串。这两个函数都接收字符串作为参数，例如：

__('Categories')
_e('Categories')

两个函数间的唯一功能性区别在于：

_e 函数回显(echo)返回的字符串，而 __ 函数只是返回字符串。如果需要为函数提供字符串，可使用 __ 函数。而如果希望将字符串作为 XHTML 的一部分输出，则需要使用 _e 函数。

两个函数都在 WordPress 中的 l10n.php 中定义，从定义中很容易看出区别。

function _e($text, $domain = 'default') {
    echo translate($text, $domain);
}

function __($text, $domain = 'default') {
    return translate($text, $domain);
}

have_posts();

the_post();

the_title();

the_content();

the_author();

comments_popup_link();

<?php comments_popup_link(‘No Comments »’, ‘1 Comment »’, ‘% Comments »’); ?> 

当弹出留言的功能激活的话，comments_popup_link() 调用一个弹出的留言窗口，如果没有激活，comments_popup_link() 则只是简单的显示留言列表。No Comments » 是在没有留言的时候显示的。1 Comment » 是用于当刚好只有1条留言时候。% Comments &187; 是用于当有多于一条留言的时候。比如：8 Comments »。百分号 % 用来显示数字。» 是用来显示一个双层箭头 »。

edit_post_link

<?php edit_post_link(‘Edit’, ‘ | ‘, ”); ?>

– 这个只有当我们以管理员或者作者身份登录的的时候才可见。 edit_post_link() 只是简单显示一个可以用来编辑当前日志的编辑链接，这样就可以让我们不必去管理界面搜寻该日志就能直接编辑。edit_post_link() 有三个参数。第一个是用来确定哪个词你将用在编辑链接的链接标题。如果你使用 Edit post，那么将显示 Edit post 而不是 Edit。第二个参数是用来显示在链接前面的字符，在这里是竖线 |，代码就是&124;。第三个参数是用于显示在编辑链接后面的字符，在这里没有使用。登录 WordPress 之后，再返回到首页就可以看到“Edit”的链接和一条竖线。

the_id
返回每篇日志的 ID。

posts_nav_link

<?php posts_nav_link('in between','befor','after'); ?>

日志导航链接.后一页或者前一页的链接。默认情况下，如果没有超过10篇日志的话，是不会显示导航链接，如果没有超过10篇日志，依然想看到导航链接，登录到管理界面，在 设置 > 阅读 页面，把它设置为比所有日志少一篇。如，有6篇日志，就设置为5。

第1个参数是显示在后一页和前一页链接的中间自定义内容。第2个参数第一个页面的自定义内容。第3个参数是下一页的自定义内容

wp_list_cats
调用分类链接列表 过期了。用wp_list_categories代替

<?php wp_list_cats("sort_column=name&optioncount=1&hiberarchical=0"); ?>

sort_column=name – 把分类按字符顺序排列
optioncount=1 – 显示每个分类含有的日志数
hierarchical=0 – 不按照层式结构显示子分类，这就解释了为什么子分类链接是列在列表中第一级。
& – 每次增加另一个参数的时候，需在它之前要输入 & 用来把和现有的参数区分开。如 & – 在 sort_column 和 optioncount之间。

wp_list_pages

<?php wp_list_pages("depth=3&title_li=<h2>Pages</h2>");  ?>

title_li 是一个用来定制化页面链接列表的标题的参数。<h2>Pages</h2> 是 title_li 这个参数的值
为了限制显示列表的层数，增加了 depth 这个参数，并把它设置为 3：

wp_get_archives
存档链接列表

<?php wp_get_archives("type=monthly"); ?>

type参数表示按月归档

get_links_list

<?php get_links_list(); ?>

过期了。用wp_list_bookmarks()代替
友情链接列表

wp_list_bookmarks
这个函数也是为Blogroll服务的，比以前的函数 get_links_list() 和 get_links() 更加强大，它有很多参数，参数和参数之前用"&"分隔

wp_list_bookmarks 函数的默认参数是：

'orderby' => 'name'
'order' => 'ASC'
'limit' => -1
'category' => ''
'category_name' => ''
'hide_invisible' => 1
'show_updated' => 0
'echo' => 1
'categorize' => 1
'title_li' => __('Bookmarks')
'title_before' => '<h2>'
'title_after' => '</h2>'
'category_orderby' => 'name'
'category_order' => 'ASC'
'class' => 'linkcat'
'category_before' => '<li id="%id" class="%class">'
'category_after' => '</li>'

参考http://www.slyar.com/blog/wp-list-bookmarks.html

WordPress 3.5 发布的时候，为了更加简洁易用，WordPress 就把一些不太常用的代码从核心代码中取消或者禁用，比如全新安装的 WordPress 博客在后台就没有链接管理器。但是如果你还是有很多朋友，需要交换链接，怎么办呢？WordPress 提供接口：

add_filter( 'pre_option_link_manager_enabled', '__return_true' );
将上面的代码复制到当前主题的 functions.php 文件即可。
添加后在后台的菜单栏会出现“链接”菜单选项。
在模板添加显示

<?php wp_list_bookmarks('orderby=name&limit=10'); ?>

wp_specialchars
2.8版本开始过期。用esc_html代替
Escaping for HTML blocks.

$html = esc_html( '<a href="http://www.example.com/">A link</a>' );

输出

<a href="http://www.example.com/">A link</a>

<?php echo esc_html($s, 1); ?>

(1|param|param)
Return param or value (also can be: null, void...).
(2|datatype|datatype)
Datatype of return value.
(3|description|description)
Description of return value.

wp_register
wp_register() 这个函数能产生一组 <li> 和 </li> 标签，如果你没有登陆，它显示注册（Register）链接，如果登录了，它显示的是 站点管理（Site Admin）的链接。

wp_loginout()
不会产生列表元素标签，所以需要我们手工输入列表元素标签，当你没有登录的时候，得到的是 登录（Login） 的链接，当已经登录的时候，得到的是登出（Logout）链接。

get_header
WordPress 主题系统特别用来导入 header.php 文件的函数，而不用使用 PHP 的函数：<?php include (TEMPLATEPATH . ‘/header.php’); ?>.

get_sidebar

<?php get_sidebar(); ?>

获取sidebar.php模板内容

get_footer
获取footer.php模板内容

the_excerpt
只显示摘要而不是全文的日志。
为什么你想这么做呢？ — 防止 Google 以为重复内容惩罚你的博客，如果一个存档页面和首页显示相同的内容，那就是重复的内容。

如果是私人的博客呢？那么就没有必要去区分首页和存档页面。但这并不是说摘要对私人博客没有用。

同样 — 默认你的类别页面将使用 archive.php 显示内容，如果你没有 archive.php 文件，类别页面将使用 index.php 显示内容。

如果你想类别页面和首页和存档页面看起来不一样，那么创佳一个 category.php 文件并定制化它。

link_pages
用于显示页面的分页链接。

<?php link_pages('<p><strong>Pages:</strong>', '</p>', 'number'); ?>

<!-nextpage->
在编辑文章时若需要分页，必须在文本状态下加入<!--nextpage-->可实现分页效果 并在page.php或者archive.php,single.php添加

<?php link_pages('<p><strong>Pages:</strong>', '</p>', 'number'); ?>

或者

<?php wp_link_pages(); ?>

推荐用<?php wp_link_pages(); ?>，因为会根据当前语言显示，如中文。

参考资料：http://codex.wordpress.org/Styling_Page-Links
http://wzbs.org/paging-a-long-article/

previous_post_link
next_post_link
上一篇文章和下一篇文章导航

<div class="navigation"><?php previous_post_link('%link') ?> <?php next_post_link('%link') ?></div>

默认情况下，链接有个箭头(«)显示
Displays link with left angular quote («) followed by the post title of the previous post (chronological post date order).
« Previous Post Title
<?php previous_post_link(); ?>
参考：http://codex.wordpress.org.cn/Previous_post_link

没有快速的方式在 comments.php 建立评论模板

comments_template
该函数加载评论模板，并显示在单篇文章和页面中。

<?php comments_template( $file, $separate_comments ); ?>

参数

$file

（字符串）（可选）将要加载的文件

默认值：/comments.php

$separate_comments

（布尔型）（可选）是否按评论类型分隔评论

默认值：false

示例

使用其它评论模板

有时你可能希望在主题的不同部分显示不同评论效果。那么你需要新建一个替换文件（如short-comments.php）并按以下方式调用该文件：

<?php comments_template( '/short-comments.php' ); ?>
注释

使用全局变量：（数组）当前文章评论对象的$comment列表
用法：$wpdb
用法：$id
用法：$post
用法：若文章没有评论，$withcomments将不会尝试获取评论
历史记录

始见于1.5.0版本
源文件

comments_template()位于wp-includes/general-template.php中。

comment_author_link
说明

该标签显示带有链接的评论作者名，链接指向评论作者所提供的URL。该标签必须用在WordPress主循环（loop）或评论循环中。

用法

<?php comment_author_link(); ?>

示例

<p>Comment by: <?php comment_author_link(); ?></p> 
参数

该标签无参数。

is_home
is_single()
is_home() 则是判断首页的条件标签，is_single() 则是判断文章页的条件标签
条件判断函数用来检测、判断使用。 如在博客首页中大量使用。 is_home属于Boolean函数, 返回值为：TRUE 或 FALSE.

wp_cache_get
wp_cache_set
通过 cache key 和 group 获取缓存的内容。

<?php wp_cache_get( $key, $group = '', $force = false, &$found = null ); ?>

参数

$key
(int|string) (required) 数据在缓存中的名字
Default: 无

$group
(string) (optional) 数据在缓存中的组名。
Default: 'default'

$force
(bool) (optional) 是否强制使用持久缓存更新本地缓存。
Default:false

$found
(bool) (optional) 是否在缓存中找到 key，可以用于消除返回 false 的歧义。目前 memecache 不支持，这个参数。
Default:false

返回值

(bool|mixed)
如果没有缓存或者缓存的数据过期，返回 false，否则返回数据。

注解

使用到 wp_object_cache 对象缓存的类
WP_Object_Cache::get()
参考 http://blog.wpjam.com/function_reference/wp_cache_get/

wp_enqueue_script
这是action。。。
使用 wp_enqueue_script() 可以安全地将 javascript 脚本加入到 WordPress 创建的页面中。一般来说，将没有被内置的代码进行添加，并在 WordPress 运行时进行加载
参考：http://codex.wordpress.org/zh-cn:%E5%87%BD%E6%95%B0%E5%8F%82%E8%80%83/wp_enqueue_script

single_post_title
single_post_title 函数，在 WordPress 中也是一个用于显示文章标题的函数，该函数主要用在文章单页中，并且没有进行过太多的封装。算是对 wp_query 这个类的活用了。

最近和标题干上了，所以把基本上所有 WordPress 中 关于文章标题的函数都想搜刮出来，因为实现方式众多，所以最终只打算将几个经过封装过的函数拿出来分析备忘一下，分别是get_the_title、the_title和 wp_title 以及本文 single_post_title 函数。

函数意义详解
single_post_title 函数显示或返回当前文章的标题。

single_post_title 函数用法、参数详解
参数跟 get_the_title、the_title 中讲的差不多。

<?php single_post_title( $prefix, $display ); ?>
$prefix分隔符
$display是否显示
示例
示例也请参考之前讲过的标题函数，如： wp_title

总结
wp_query 这个类是个好东西，推荐有点能力的童鞋还是好好研究下，这里标题的实现主要还是依靠该类下的一个请求对象的返回函数get_queried_object来实现对象的获取，比较值得研究。

single_post_title 函数声明
该函数声明位于 wp-includ/general-template.php 635 – 646行左右的位置

<?php 
/**
 * Display or retrieve page title for post.
 *
 * This is optimized for single.php template file for displaying the post title.
 *
 * It does not support placing the separator after the title, but by leaving the
 * prefix parameter empty, you can set the title separator manually. The prefix
 * does not automatically place a space between the prefix, so if there should
 * be a space, the parameter value will need to have it at the end.
 *
 * @since 0.71
 *
 * @param string $prefix Optional. What to display before the title.
 * @param bool $display Optional, default is true. Whether to display or retrieve title.
 * @return string|null Title when retrieving, null when displaying or failure.
 */
function single_post_title($prefix = '', $display = true) {
	$_post = get_queried_object();
 
	if ( !isset($_post->post_title) )
		return;
 
	$title = apply_filters('single_post_title', $_post->post_title, $_post);
	if ( $display )
		echo $prefix . $title;
	else
		return $title;
}
 ?>

get_template_part
参考http://pangbu.com/get_template_part/
http://codex.wordpress.org/zh-cn:%E8%B0%83%E7%94%A8%E6%A8%A1%E6%9D%BF%E9%83%A8%E5%88%86/get_template_part
http://jingyan.baidu.com/article/8065f87f8f175d2330249849.html

描述:
加载一个制定的模板到另一个模板里面(不同于包含header,sidebar,footer).
使得一个主题使用子模板来实现代码段重用变得简单

用于在模板中包含指定的模板文件,只需用指定参数slug和name就可以包含文件{slug}-{name}.php,最重要的功能是如果没有这个文件就包含没有{name}的.php文件文件

使用方法:

<?php get_template_part( $slug, $name ) ?>

什么意思呢？我们来看一下具体的示例：
<?php get_template_part( 'content', 'blog' ); ?>
意思是说，如果content-blog.php存在，则调用content-blog.php，否则，就调用content.php

the_posts_pagination
WordPress 4.1新增分页式导航
返回文章列表的前/后导航。

comments_open
这个条件标签用来检测当前文章或者某篇指定ID的文章是否开启评论。这是一个布尔型函数，它的返回值为 TRUE 或者是 FALSE
用法

<?php comments_open( $post_id ); ?>

传入参数
$post_id

（整数型）（可选的）文章ID

默认值：0

返回值
（布尔型）

真则返回True，假则返回false。

get_comments_number

$my_var = get_comments_number( $post_id ); 

返回post的评论数量

comments_template
说明

该函数加载评论模板，并显示在单篇文章和页面中。

用法

<?php comments_template( $file, $separate_comments ); ?>

参数

$file

（字符串）（可选）将要加载的文件

默认值：/comments.php

$separate_comments

（布尔型）（可选）是否按评论类型分隔评论

默认值：false

示例

使用其它评论模板

有时你可能希望在主题的不同部分显示不同评论效果。那么你需要新建一个替换文件（如short-comments.php）并按以下方式调用该文件：

<?php comments_template( '/short-comments.php' ); ?>

注释

使用全局变量：（数组）当前文章评论对象的$comment列表
用法：$wpdb
用法：$id
用法：$post
用法：若文章没有评论，$withcomments将不会尝试获取评论