【WP插件入门向】实现博客主页任意标题栏随机显示歌词

插件是WordPress对博客网站进行自定义的重要方式。通过插件Press用户最熟悉的插件之一可能就是《你好多莉》了——系统自带，用作教程来教用户如何使用和开发插件。启用之后就会在后台页面的右上角随机显示Hello Dolly的歌词。

插件本身没什么实质性用途，但我还是本着图一乐的目的启用了。过了一段时间以后产生了这样一个想法：将歌词改成自己想要的，比如vc曲目，Visual C++（划掉）并且在主页展示。

样例

抱着这样的想法我把Hello Dolly下载了下来。在wp的后台插件页面点击“在WordPress.org打开”就能跳转到插件源文件的下载目录。Hello Dolly包含一个PHP文件，代码如下（部分代码已省略，注释经过翻译）：

<?php
/**
 * @package Hello_Dolly
 * @version 1.7.2
 */
/*
Plugin Name: Hello Dolly
Plugin URI: http://wordpress.org/plugins/hello-dolly/
Description:这不仅仅是一个插件，它象征着一代的热情和希望，在Louis Armstrong中最着名的词语：Hello, Dolly。启用后后，您将在每个管理页面的右上方看到Hello，Dolly中随机一个歌词。
Author: Matt Mullenweg
Version: 1.7.2
Author URI: http://ma.tt/
*/

function hello_dolly_get_lyric() {
	/** 此处是Hello Dolly的歌词，用换行分隔。已省略 */
	$lyrics = "Hello, Dolly
";

	//将歌词按行分开
	$lyrics = explode( "\n", $lyrics );

	// 再随便选一行
	return wptexturize( $lyrics[ mt_rand( 0, count( $lyrics ) - 1 ) ] );
}

// 这段输出选中的歌词行，我们一会儿再放置。
function hello_dolly() {
	$chosen = hello_dolly_get_lyric();
	$lang   = '';
	if ( 'en_' !== substr( get_user_locale(), 0, 3 ) ) {
		$lang = ' lang="en"';
	}

	printf(
		'<p id="dolly"><span class="screen-reader-text">%s </span><span dir="ltr"%s>%s</span></p>',
		__( 'Quote from Hello Dolly song, by Jerry Herman:', 'hello-dolly' ),
		$lang,
		$chosen
	);
}

// 将插件设置为管理界面时执行
add_action( 'admin_notices', 'hello_dolly' );

// 需要一些CSS来放置插件
function dolly_css() {
	echo "
        <!-- 原文件此处是CSS样式。已省略-->
	<style type='text/css'>
	#dolly 
	</style>
	";
}

add_action( 'admin_head', 'dolly_css' );

插件主要分为两个部分：介绍基本信息的注释和后面的代码。WordPress通过读取头部注释来获得插件的基本信息，比如插件名称，作者，简介等，只需要对应的填写即可。

代码部分可以看到随机截取歌词的部分还是很简单直接的。 hello_dolly_get_lyric() 这个函数随机选择一行歌词； hello_dolly() 将 hello_dolly_get_lyric() 返回的歌词加上原作信息处理后打印出来。dolly_css()负责放置必要的css来管理歌词的显示方式。最后使用wp的钩子（add_action）挂载插件，在加载管理界面的时候触发执行。

钩子钩子是插件能够不更改内核的同时添加功能的关键。Wp中的插件主要分为action和filter两种。Action类型将一段代码插入到指定的时间节点执行。比如在页面载入后，加载正文前弹出问候窗口；filter则将输入的数据进行一定处理后输出，例如让所有正文内容先附加一段作者介绍，再显示。此处以action类型为例，我们先编写好回调函数，再通过add_action()对我们的回调函数进行挂载。

在WordPress的开发文档中，对add_action方法的介绍如下：

add_action( string $hook_name, callable $callback, int $priority = 10, int $accepted_args = 1 )

该函数共有四个基本参数：使用的钩子名称，回调函数，回调优先级以及接受的参数数量。钩子名称是必须参数，决定了函数插入的位置。例如save_post（文章被保存后），admin_head（后台页面头）等。第二个参数是我们要传入的回调函数。最后两个参数为可选项，分别是优先级和参数数量。优先级一项决定执行顺序，数字越小优先级越高，默认为10。

// 将插件设置为管理界面时执行
add_action( 'admin_notices', 'hello_dolly' );

操作自定义主题

在搞清楚wp中插件的基本运作原理之后，我们就可以开始动手了。个性化主题（利用本页面使用的argon）在主页提供了多个适合放置歌词的位置，例如副标题，格言栏以及公告栏。此处以格言栏为例。在wp后台管理界面中进入外观-主题编辑器页面即可查看主题代码。在argon主题中，格言栏位于页面边栏中，如图：

在主题文件的边栏sidebar.php中，包含以下代码控制左侧子标题/格言的显示：

<?php 
	$sidebar_subtitle = get_option('argon_sidebar_banner_subtitle'); 
	if ($sidebar_subtitle == "--hitokoto--"){
		$sidebar_subtitle = "<span class='hitokoto'></span>";
	}
?>
<?php if ($sidebar_subtitle != '') { /*左侧栏子标题/格言(如果选项中开启)*/?>
	<span class="leftbar-banner-subtitle text-white"><?php echo $sidebar_subtitle; ?></span>
<?php } /*顶栏标题*/?>

主题会从WordPress的数据表中使用get_option方法取得我们预先设置好的格言。定制主题并未在此处提供供我们修改格言栏内容的钩子，因此如果不修改主题文件我们只能对wp的数据表下手。Option数据表是WordPress数据库中一个独立的数据表，存储了网站的自定义数据，并开放给用户和插件进行修改编辑。因此一种可行的思路是在每次刷新后，页面显示前更改数据表中argon_aidebar_banner_subtitle一项的值为我们想要的内容。

在单个网站中WordPress提供了以下函数来操作option数据表（引用自wpzhiku.com/understanding-working-wordpress-options-table）：

函数	参数	备注
`add_option()`	`$option`, `$value`, `$deprecated`, `$autoload`	只有 `$option` 是必需参数，如果数据表的`option_name` 字段是`$option` , WordPress 将添加`$value` 值作为数组添加到 `option_value` 字段，如果没有匹配的字段，将添加新记录。
`delete_option()`	`$option`	删除该项的所有记录。
`get_option()`	`$option`, `$default`	`$default` (可选) 如果获取不到选项之，则返回该值。
`update_option()`	`$option`, `$new_value`	`$new_value` 将要添加到`option_value` 字段的值。
`add_site_option()`	`$option` `$value`	`类似 add_option()` ，但是在全站点中可用。也就是说此设置将添加在`wp_options` 数据表中，而不是 `wp_XX_options数据表`( `XX` 是站点 ID)。
`delete_site_option()`	`$option`	和`delete_option()` 一样，在多站点模式中使用。
`get_site_option()`	`$option` `$default$use_cache`	`和 get_option()` 一样，在多站点模式中使用。
`update_site_option()`	`$option`, `$value`	`和 update_option()` 一样，在多站点模式中使用。

插件的代码实现如下：

<?php
/**
 * @package VC_lyrics_random_display
 * @version 2012.7.12
 */
/*
Plugin Name: Singsingsing-主页随机显示vc歌词
Plugin URI: https://ltyxh.com
Description: 博客主页每次刷新显示一句随机VC歌词。适用于所有主题，自行修改插件即可。【默认为argon主题/显示位置博客格言区】世界很大很乱，地球在转，数不清的各种悲和欢。总是想太多还不如什么都别想。
Author: 珞林
Version: 2012.7.12
Author URI: https://ltyxh.com/
*/

function vc_get_lyric() {
    define('MYPLUGINNAME_PATH', plugin_dir_path(__FILE__) );
	$lyrics = file_get_contents(MYPLUGINNAME_PATH . 'vc_lyrics.txt');
	$lyrics = explode( "\n", $lyrics );
	return wptexturize( $lyrics[ mt_rand( 0, count( $lyrics ) - 1 ) ] );
}


function vc_lyric_change_option() {
	$chosen = vc_get_lyric();
	$chosen = str_replace(array(' ','&nbsp;'),'',$chosen);
	//修改数据表
	update_option( 'argon_sidebar_banner_subtitle', $chosen);
}

//execute when the plugins_loaded action is called.
add_action( 'plugins_loaded', 'vc_lyric_change_option' );

在备选歌词量较大的情况下，把歌词一股脑儿塞进代码的变量初始化语句里显然不是明智之举，也不方便后期修改。因此这里把歌词放到了vc_lryics.txt这个单独的文件中。我们将函数挂载到了“plugins_loaded”也就是页面载入插件时执行。需要注意的是读取vc_lyrics.txt时要在文件名前获取并加上wp的插件路径，否则会找不到文件报错。

至于效果么，读者可以回到博客首页体验。Argon移动端查看格言栏需要点击左上角打开侧边栏。玩得愉快！