Joomla中文教程:创建并使用插件对文章内容进行修改
概述
插件(plugin)是一种很容易创建的扩展。一个简单的插件只需要两个文件，非常小巧。
插件的一个典型应用就是每当保存一篇文章的时候，对该文章进行某种自定义处理。例如：
- 改变文章的发布状态。
- 为文章批量增加某种标准化的文字。
- 为文章设定section或category.
下面我们来看看如何通过创建简单的插件实现这些需求。
第一个插件
在原生的Joomla系统中，如果一个属于“作者”组的用户提交了一篇新文章，那么这篇文章默认的状态将是“未发布”。然而，一旦管理员确认并发布 了该文 章，这名用户就可以编辑这篇文章了，而这篇文章将永远处于“已发布”的状态。在我们的例子中，我们希望改变这种模式，即希望每次用户进行了文章编辑之后， 文章的状态都会变成“未发布”。下面我们来创建第一个插件。
一个简单的插件至少要包括两个文件：一个XML文件，用来告诉Joomla如何安装该插件；另外一个是负责插件实际功能的PHP文件。
为了让人们可以更容易的编写自己的插件，Joomla在完成安装后会提供插件范本。因为我们需要通过插件来修改文章内容，所以要编写的是针对“内容”(content)的插件。我们所需要的插件范本位于：
- Joomla根路径/plugins/content/example.xml
- Joomla根路径/plugins/content/example.php
我们将自己的插件命名为modifyarticle，于是XML文件的名字就是modifyarticle.xml.我们只需要将 plugins/content/example.xml文件中的代码复制粘帖到我们自己的空白的modifyarticle.xml中，将该文件置于一 个文件夹，并将该文件夹放在Joomla根路径之外(我们之后会使用Joomla的安装程序将该插件安装到系统中，所以现在只需要将它独立的置于 Joomla系统之外就可以)。下面我们将modifyarticle.xml文件的代码修改为：
<?xml version="1.0" encoding="utf-8"?>
<install version="1.5" type="plugin" group="content">
<name>Modify Edited Articles</name>
<creationDate>January 2009</creationDate>
<author>Joomla Doc Team</author>
<authorEmail>
myemail@myemail.com This e-mail address is being protected from spambots. You need JavaScript enabled to view it </authorEmail>
<authorUrl>http://joomlacode.org</authorUrl>
<copyright>Copyright (c) 2009</copyright>
<license>GPL</license>
<version>1.0.0</version>
<description>Example plugin for Joomla! wiki.</description>
<files>
<filename plugin="modifyarticle">modifyarticle.php</filename>
</files>
</install>
接下来，我们将plugins/content/example.php文件中的代码复制粘帖到我们自己的空白的modifyarticle.php文件中；与modifyarticle.xml一样，将PHP文件放在之前的那个独立的文件夹中。然后我们将代码修改为：
<?php
/**
* @copyright Copyright (C) 2005 - 2008 Open Source Matters. All rights reserved.
* @license GNU/GPL, see LICENSE.php
*/
// Check to ensure this file is included in Joomla!
defined( '_JEXEC' ) or die( 'Restricted access' );
jimport( 'joomla.plugin.plugin' );
class plgContentModifyArticle extends JPlugin
{
/**
* Constructor
*
* For php4 compatability we must not use the __constructor as a constructor for plugins
* because func_get_args ( void ) returns a copy of all passed arguments NOT references.
* This causes problems with cross-referencing necessary for the observer design pattern.
*
* @param object $subject The object to observe
* @param object $params The object that holds the plugin parameters
* @since 1.5
*/
function plgContentModifyArticle ( &$subject, $params )
{
parent::__construct( $subject, $params );
}
/**
* Example before save content method
*
* Method is called right before content is saved into the database.
* Article object is passed by reference, so any changes will be saved!
* NOTE: Returning false will abort the save with an error.
* You can set the error by calling $article->setError($message)
*
* @param object A JTableContent object
* @param bool If the content is just about to be created
* @return bool If false, abort the save
*/
function onBeforeContentSave( &$article, $isNew )
{
global $mainframe;
$user =& JFactory::getUser(); // get the user
if ($user->usertype == 'Author') { // unpublish if user is "Author"
$article->state = 0; // from dev 11:59
}
return true;
}
}
注意，在原来的example.php文件中，构造器(constructor)含有6个方法(methods)。这些方法涵盖了6种通常可能用到 的事件应用。在我们的例子中，我们只需要在文章被保存到数据库之前对文章进行修改，所以我们将我们的方法(函数)命名 为"onBeforeContentSave".其名称必须准确，它会告诉Joomla合适运行我们的插件对文章进行处理。
上面的代码即可实现我们的需求。首先获得用户信息，如果用户属于“作者”组，就将文章的状态设置为0，即“未发布”状态。注意"onBeforeContentSave"方法使用$article作为参数，所以文章对象的字段和方法对我们来说都是可以调用的。
安装插件
我们已经搞定了插件的代码，接下来我们需要创建zip格式的文件包，用来安装到我们的Joomla站点中。步骤如下：
- 使用普通的压缩软件将我们之前创建的两个文件打包为Zip或Gzip文件。
- 进入站点管理后台中的“扩展”→“安装/卸载”(Extensions → Install / Uninstall)。
- 点击“浏览”(Browse)并找到我们之前创建的压缩包。
- 点击“上传文件”(Upload File)并执行安装(Install)。成功安装后会看到系统提示。
- 进入“扩展”→“插件管理”(Extensions → Plugin Manager)，找到我们新安装的插件(根据我们在XML文件中的设置，插件名应该是“Modify Edited Articles”)，激活。
搞定。
添加标准化文字
我们已经创建了第一个插件，基于这个插件进行修改进而创建其他插件就很容易了。例如，对于每一篇由属于“作者”组的用户提交的文章，我们都希望添加一段标准化的文字。下面就是新插件的PHP文件中"onBeforeContentSave()"方法的代码：
function onBeforeContentSave( &$article, $isNew )
{
global $mainframe;
$newText = '<p>This is my new text to add to the article.</p>';
$user =& JFactory::getUser(); // get the user
if ($user->usertype == 'Author') {
if ($article->fulltext) {
if (strpos($article->fulltext, $newText) == 0) {
$article->fulltext .= $newText;
}
}
else {
if (strpos($article->introtext, $newText) == 0) {
$article->introtext .= $newText;
}
}
}
return true;
}
上面的代码中，我们向变量$newText中添加了一些标准化文字。然后我们对文章对象进行了一些判断处理：如果文章中没有“Read more...”分割，则将文章处理为正文+标准化文字；如果有“Read more...”分割，则将“Read more...”之前的引文处理为引文+标准化文字。
另外一点需要判断的是，原文章内是否包括我们要添加的标准化文字。如果文章已经被添加过这段文字，则不会在编辑并保存时继续添加。
该方法的另一个参数$isNew用来判断该文章是否为新提交的；我们可以通过这个判断参数来决定是否只为新提交的文章进行添加文字的处理。
设置section或category
为文章设置section或category的ID是很容易的。例如，对于安装了Joomla范例内容的Joomla站点，这段代码：
$article->sectionid = '4';
$article->catid = '25';
会将文章的section设置为"About Joomla!"，将category设置为"The Project"。注意，我们需要设置的是“id”字段。另外，如果想移除文章的section或category，也可以通过模板覆盖的方式在模板代码 中直接去掉相关的代码。(关于模板覆盖，可以参见“Joomla文档中文翻译 - 如何通过模板覆盖的方式修改Joomla的系统输出”)
其他
我们还可以通过创建插件对文章进行其他方面的修改；下面列出了一些文章对象的字段：
- title：文章标题。
- alias：文章别名。
- state：发布状态；0代表未发布，1代表已发布，-1代表已存档。
- created：文章创建日期。
- created_by：用户id或作者名。
- created_by_alias：作者别名。
- modified：文章最后一次修改的日期。
- modified_by：最后一次修改文章的用户id或作者名。
- metakey：文章的元数据信息/关键词。
- metadesc：文章的元数据信息/描述。
- access：文章的浏览权限；0代表公开，1代表只对注册用户公开，2代表只对特殊(special)用户公开。
我们也可以用plugins/content/example.php文件中提供的其他原生内建事件来创建插件。关于其他一些类型的插件(非content类型)，可以参考plugins section of the Wiki 获取更多信息。