Extension标签
xml文件以开头,表明这是一个Joomla扩展。有四种不同的类型:components, modules, plugins, templates。因此,需要制定type属性。
<extension type=″component″>
对于插件,还需要指定插件类别,因为这决定了插件安装在哪个目录。
<extension type=″plugin″ group=″content″>
通常还会看到一个版本参数,指的是Joomla核心的版本信息。最终的样式如下
<extension version=″3.4″ type=″plugin″ group=″content″>
extension标签是所有其他标签的父标签。在xml文件的结尾关闭</extension>
XML头
通常<extension>
前面还有个XML头。表明这是个XML文件,最重要的是指定文件的字符集。一般指定为utf-8.
<?xml version=″1.0″ encoding=″utf-8″ ?>
<extension ….>
…
</extension>
实际上,utf-8可以不用指定。因为Joomla使用SimpleXML
解析XML,二这个哭默认认为编码是UTF-8。建议只使用utf-8编码。
基本标签
<extension>
标签之后,是一些插件的meta信息。首先是插件的名称,要遵循Joomla的原则。plg开头,下划线,插件类型名,下划线,插件名。
plg_content_ch03test01
This <name>
tag does not contain the technical name as for your plugin on the flesystem.???
名称标签也可以使用语言文件翻译。技术名称必须全部小写,语言字符串必须全部大写。
<name>PLG_CONTENT_CH03TEST01</name>
一般情况下,还应该加一点描述。同样,只是一个语言字符串,内容放在语言文件中。
接下来是插件版本,随便写什么都行
<version>1A</version>
<version>24 beta</version>
<version>my frst attempt</version>
最好是用x.y.x的格式。
接下来是插件的创建日期,每次修改日期室,修改版本号。
三种日期格式 (August 2014, 08-2014, 08/2014)
<creationDate>August 2014</creationDate>
接下来是作者信息
<author>Jisse Reitsma</author>
<authorEmail>jisse@yireo.com</authorEmail>
<authorUrl>http://joomla-plugins-book.yireo.com/</authorUrl>
最后,需要一些法律信息,版权和许可。许可应该是GNU/GPL ,版本2、3都行。因为Joomla的Extension Directory需要一个LICENSE.txt文件,所以可以指向这个文件。
<license>GNU/GPL version 3 or later; see LICENSE.txt</license>
<copyright>Copyright of Jisse Reitsma (2012)</copyright>
文件&目录&媒体
<file>
标签很重要,安装文件时,表明,那些文件从源包(压缩文件解压到的临时目录)复制到目标文件夹(/plugin/下的子目录)。这个标签中必须总是包含主php文件,
<fles>
<flename plugin=″ch03test01″>ch03test01.php</flename>
<flename>index.html</flename>
</fles>
主php文件还包含一个plugin的参数,这表明当插件被调用时,那个文件被调用。如果主php文件是其他名称,比如/plugins/content/ch03test01/main.php,
也可以这样完成。但是最好使用标准命名规则,文件名就是插件名。
注意,这个xml文件不在<file>
标签中,但是它还是会被拷贝到目标目录。
一般还要包含一个index.html文件,防止外部浏览插件目录文件,其实可以通过其他方式做到这点,比如.htaccess。但是Joomla这样要求的,所有的Joomla目录都有这个文件。
当一个插件逻辑很复杂时,最好是将逻辑文件放在不同的文件中。比如是用helper.php
提供一些方法。如果使用很多的php文件,最好新建一个子目录。比如,当需要一个新的表格类型时,一个自定义的下拉表,最好新建一个子目录(别忘了里面放个index.html文件),绝对路径是/plugins/content/ch03test01/felds/。
<fles>
<flename plugin=″ch03test01″>ch03test01.php</flename>
<flename>index.html</flename>
<flename>helper.php</flename>
<folder>felds</folder>
</fles>
不必在<file>
标签中包含LICENCE.txt文件。
如果想要加入一些静态文件,比如,图片文件,CSS,JS文件,不要放在插件目录中,放在/media目录中。通常这样做:
<media destination=″plg_content_ch03test01″>
<folder>images</folder>
<folder>css</folder>
<folder>js</folder>
</media>
其中,destination
表示目标目录在/media/plg_content_ch03test01/
。安装文件包中应该包括,images,css,js子目录。
另一种做法是,在压缩目录中创建plg_content_test01
,其下包含上面三个子目录,不带destination
,这样写
<media>
<folder>plg_content_ch03test01</folder>
</media>
使用语言文件
每个语言文件需要一个tag参数,指明是哪种语言。Joomla核心默认是英语,所以至少包含英语(en_GB)
<languages>
<language tag=″en-GB″>
en-GB.plg_content_ch03test01.ini
</language>
<language tag=″en-GB″>
en-GB.plg_content_ch03test01.sys.ini
</language>
</languages>
这两个文件都会拷贝到/administrator/language/en-GB/
,区别是不带sys的前台和后台都能用,带sys的只用于后台使用。如果插件没有前端,可以忽略不带sys的文件。带sys的,会被Plugin Manager自动加载,不需要额外的代码。如果没有前端使用的语言,可以把所有的语言翻译都放到这个文件中
在前端显示中使用语言文件的方法是,JText::_()方法。使用前,要确保en-GB.plg_content_ch03test01.ini已经加载。默认,插件加载时,是不加载语言文件的。为确保加载语言文件,Joomla 3 以上的版本,这样写
class PlgContentCh03test01 extends JPlugin
{
protected $autoloadLanguage = true;
其他版本的
class PlgContentCh03test01 extends JPlugin
{
public function __construct(&$subject, $confg)
{
parent::__construct($subject, $confg);
$this->loadLanguage();
}
语言文件中也可以使用HTML,需要将HTML标签先编码。 < 变成 <
,> 变成 >
PLG_CONTENT_CH03TEST01_DESCRIPTION=″This is an example
<strong>Content Plugin</strong>″
虽然这是个很酷的技巧,但是不要滥用。
安装时部分和实时信息
XML中有些标签是Joomla安装时使用的,比如<file
,一旦安装完成,这些信息就不需要了。有些tag当访问一些特定页面时会被实时读取,比如Extension Manage会显示作者、版本和日期。如果在XML文件中修改这些信息,只需要Refresh Cache按钮,Joomla就会重新解析XML文件。
但是<name>
标签不行。这个字段在插件安装时会被拷贝进数据库。
打包多个扩展
如果想将多个插件打包到一个扩展中,只需要将多个打包文件和一个类型为pakeage的XML配置文件打包就可以了。这个XML配置文件可以是任何名字。
<?xml version="1.0" encoding="UTF-8" ?>
<extension type="package" version="2.5">
<name>Test</name>
<packagename>test</packagename>
<author>Yireo</author>
<authoremail>support@yireo.com</authoremail>
<authorurl>http://www.yireo.com</authorurl>
<creationDate>August 2014</creationDate>
<copyright>Copyright 2014 Yireo.com</copyright>
<license>http://www.gnu.org/licenses/gpl-3.0.html</license>
<version>0.0.1</version>
<url>http://www.yireo.com</url>
<packager>Yireo</packager>
<packagerurl>http://www.yireo.com</packagerurl>
<files>
<file type="plugin" id="plg_content_ch03test01" group="content">plg_content_ch03test01.zip</file>
<file type="plugin" id="plg_content_ch03test02" group="content">plg_content_ch03test02.zip</file>
</files>
</extension>
所有<file>
标签中的字段,都会被解析为一个单独的扩展。这样可以一次安装多个扩展,唯一需要注意的是服务器的限制,执行时间和最大上传大小。
添加SQL表达式
XML文件中可以通过标签方便的规定哪些是安装时(<install>
)、卸载时(<uninstall>
)、更新时(<update>
)执行的。
<install>
<sql>
<file driver="mysql" charset="utf8">install.mysql.utf8.sql</file>
</sql>
</install>
<uninstall>
<sql>
<file driver="mysql" charset="utf8">uninstall.mysql.utf8.sql</file>
</sql>
</uninstall>
<update>
<schemas>
<schemapath type="mysql">sql/updates/mysql</schemapath>
</schemas>
</update>
使用XML模式进行更新
更新操作稍微复杂。目录sql/updates/mysql
需要包含每个插件版本的文件,比如0.0.1版本中,要有0.0.1.sql文件;0.0.2版本中,要有0.0.2.sql文件。每个版本都要有个对应的文件,即使是空文件。
安装0.0.1版本时,显然只是安装过程被执行。Joomla还是会在数据库的#__schemas
表中添加一条记录,其中ID是#__extensions
表中扩展存储的ID。如果XML中没有<update>
标签的话,这一过程就会跳过。
这就有一个问题,当版本0.0.1不包括<update>
标签,#__schemas
表中就没有这条0.0.1这个版本的记录。当更新到0.0.2时,有一个<update>
标签,插件就会在#__schemas
表添加一条记录。但是sql目录中的SQL更新将不会执行,因为Joomla没有标记这是一个实际的模式更新。重装也不起作用。这就是为什么必须从一开始就需要写上模式文件,除非这个插件确定不需要更新SQL。
手动更新,要更新XML中的版本号,同时更新`#__schemas``表中的版本号。
执行自定义安装
也可以添加一段在安装、卸载、更新时执行的代码。在XML配置文件中通过<scriptfle>
标签标示,指向一个PHP文件。
<scriptfle>ch03test01.script.php</scriptfle>
文件中需要一个预定义的类和几个方法,类名命名规则Plg + group + name + InstallerScript
,5个方法可以用
- install(JAdapterInstance $adapter)
- update(JAdapterInstance $adapter)
- uninstall(JAdapterInstance $adapter)
- preflight(string $route,JAdapterInstance $adapter)
- postflight(string $route, JAdapterInstance $adapter)
install(), update() and uninstall()在使劲执行操作是调用。如果失败,Joomla会回滚。
preflight()在文件被拷贝之前执行。所以,用 preflight(),看看条件是否满足;用install()执行一些安装后的操作。
$adapter
和$route
参数
根据文档,$adapter
指向JAdapterInstance类,在安装插件时,总是指向它的子类JInstallerPlugin类。$route
包含要执行的工作,比如是安装、卸载还是更新。由于它只在安装前,或者安装完成后执行,不知道是不是更新操作,所以,更新操作没有这个参数。
要小心使用postflight()
,通常,不能用这个方法返回false,因为不允许回滚扩展安装。更糟糕的是,卡住了,不能卸载,因为找不到XML配置文件。
解决的方法是修改XML代码。在<extension>
标签中加入method=″upgrade″
。这让Joomla复写存在的文件,允许你强制安装插件
<extension version=″3.4″ type=″plugin″
group=″content″ method=″upgrade″>
更新扩展
当一个新扩展安装后,可以添加一个更新服务器,被插入到Joomla的数据库中。更新服务器被Extension Manager查询,看看是否有更新。这个特性需要以下几个步骤:
step1. 标记安装包为可更新,如上面的代码。加上之后,告诉Joomla这个安装包可以覆盖已有的文件。
step2.设置更新服务器
<updateservers>
<server type=″extension″ priority=″1″ name=″Test 01″>
http://example.com/ch03test01_update.xml
</server>
</updateservers>
Joomla要到服务器下载这个XML文件。除了这个,URL可以是任何东西,可以是XML文件,PHP文件生成XML文件。但是不能调到其他页面。
XML文件需要定义最新的插件版本和新插件在哪下载。
<?xml version="1.0" ?>
<updates>
<update>
<name>Chapter 03 / Test 01</name>
<description>Content - Chapter 03 / Test 01 plugin</description>
<element>ch03test01</element>
<type>plugin</type>
<folder>content</folder>
<version>0.0.1</version>
<infourl title="URL">http://example.com/plg_content_ch03test01</infourl>
<downloads>
<downloadurl type="full" format="zip">http://example.com/plg_content_ch03test01.zip</downloadurl>
</downloads>
<maintainer>Yireo</maintainer>
<maintainerurl>http://www.yireo.com</maintainerurl>
<tags>
<tag>ch03test01</tag>
</tags>
<targetplatform name="joomla" version="3.[0123456789]" />
</update>
</updates>
对比配置文件,<extension>
标签被<update>
取代。很多其他的信息可以拷贝。element对应那么,folder对应类型。targetplatform标签很重要,整个update需要制定一个目标平台,如果需要制定多个,可以用正则简写,像上面的例子。