版本：5.1

清单文件

您可以通过清单 XML 文件安装 Joomla 扩展，并且有很多 Joomla 示例可以作为您自己的扩展的基础。

组件 - 在 administrator/components 中，例如 administrator/components/com_contact/contact.xml
模块 - 在 modules 或 administrator/modules 中，例如 modules/mod_breadcrumbs/mod_breadcrumbs.xml
插件 - 在 plugins 中，例如 plugins/system/remember/remember.xml
模板 - 在 templates 或 administrator/templates 中，例如 administrator/templates/atum/templateDetails.xml
语言 - 在 language 或 administrator/language 中，例如 language/en-GB/install.xml

本节介绍清单文件中 XML 的详细定义。

文件命名约定

正确命名清单文件非常重要。否则，您可能会发现您的扩展已安装，但扩展的命名空间未正确构建，并且您的扩展无法运行。

以下是不同扩展类型的命名规则（如构建扩展中所列）

组件：对于名为 com_example 的组件，您可以使用 com_example.xml 或 example.xml。

模块：对于模块 mod_example，请使用 mod_example.xml。这必须与清单<files>部分中给出的模块名称匹配

<files>
    <folder module="mod_example">services</folder>
    ...
</files>

或者如果您尚未使用 services/provider.php 文件

<files>
    <filename module="mod_example">mod_example.php</folder>
    ...
</files>

插件：对于插件 plg_example，请使用 example.xml。这必须与清单<files>部分中给出的插件名称匹配

<files>
    <folder plugin="example">services</folder>
    ...
</files>

或者如果您尚未使用 services/provider.php 文件

<files>
    <filename plugin="example">example.php</folder>
    ...
</files>

模板：您的清单文件必须命名为 templateDetails.xml

语言：使用 install.xml

文件、库、程序包：您可以使用任何名称，但库通常命名为 lib_example.xml，程序包命名为 pkg_example.xml。

对于组件、模块和插件，清单文件必须与#__extensions表中扩展记录的“element”字段匹配（除了组件可以省略“com_”前缀）。“element”是 Joomla 中扩展的内部名称。

优先级顺序“element”数据库字段设置

来自清单文件中的<element>，或
来自<files>中的“module=”或“plugin=”属性，或
来自<name>（文本清理后）。

根元素

安装文件的首要标签是

<extension>
...
</extension>

此起始和结束标签对于所有扩展都是相同的。以下属性在标签内允许使用

属性	值	适用对象	描述
type	component file language library module package plugin template	所有扩展
method	install upgrade	所有扩展	install 值（默认值）表示如果安装程序找到任何新扩展的现有文件/文件夹，它将优雅地停止 upgrade 值允许您在现有版本的基础上安装升级版本
client	site administrator	模块	定义模块是前端站点模块还是后端管理员模块
group	字符串	插件	组名称指定新插件可用于哪个插件组。现有组是目录/plugins中文件夹的名称。安装程序将为尚不存在的组名称创建新文件夹名称。

元数据

以下元素可用于插入元数据。尽管不是严格要求，但您应该至少定义<name>、<author>、<version>和<description>标签，所有这些标签都用于默认的管理员“管理扩展”表单。

<name> – extension name (e.g. com_banners). 
<author> – author's name (e.g. Joomla! Project)
<creationDate> – date of creation or release (e.g. April 2006)
<copyright> – a copyright statement (e.g. (C) 2020 - 2030 Open Source Matters. All rights reserved.)
<license> – a license statement (e.g. GNU General Public License version 3 or later; see LICENSE.txt)
<authorEmail> – author's email address (e.g. [email protected])
<authorUrl> – URL to the author's website (e.g. www.joomla.org)
<version> – the version number of the extension (e.g. 1.6.0)
<description> – the description of the component (may be shown as a tooltip on the admin Manage Extensions page)
<element> – the internal name of the component. If omitted, name will be cleaned and used

<name>和<description>字段是可翻译的。如果您为这些元素使用语言字符串，则应在您的语言 .sys.ini 文件和 .ini 文件中定义它们。

前端文件

<files folder="from-folder">
    <filename>example.php</filename>
    <folder>examples</folder>
</files>

这用于将文件从您的开发“from-folder”复制到已安装扩展的前端目录。您可以使用<filename>单独识别文件，也可以使用<folder>复制完整目录。

对于插件和模块，您应该识别代码的入口点。如果您在模块或插件中使用依赖注入并且具有 services/provider.php 文件，则使用

    <folder module="mod_example">services</folder> 
or
    <folder plugin="example">services</folder> 

这里“mod_example”/“example”是模块/插件的内部名称（又名“element”）。

如果您不使用 services/provider.php 文件，则指向特定文件名

    <filename module="mod_example">mod_example.php</folder> 
or
    <filename plugin="example">example.php</folder> 

媒体文件

此类别涵盖

您的 javascript 文件
您的 css 文件
任何作为扩展固有部分的图像（即管理员不应该能够更改的内容）。

（例如，考虑 media/mod_languages/images/ 中的标志符号，这些符号由语言切换器使用。）

在您的开发区域，您应该将它们存储在单独的文件夹中：js/、css/、images/，然后使用

<media folder="media" destination="com_example">
    <folder>js</folder>
    <folder>css</folder>
    <folder>images</folder>
</media>

安装程序会将这些文件夹移动到 media/com_example/js、media/com_example/css 和 media/com_example/images 中，并在需要时创建 com_example 文件夹。

此媒体文件夹用于站点前端和管理员后端。

管理部分

<administration>
    <!-- various elements -->
</administration>

管理部分在<administration>元素中定义。由于只有组件同时适用于站点和管理员，因此只有组件清单可以包含此元素。

管理员后端文件

要复制到 administrator 目录下的文件应放在<administration>下的<files>元素中，并且可以用于复制单个文件或完整文件夹，如上文所述的前端文件。

这映射到管理员侧边栏菜单（在“组件”下）中组件的菜单和子菜单链接。

<administration>
    <menu>COM_EXAMPLE</menu>
    <submenu>
        <!--
            Note that all & must be escaped to &amp; for the file to be valid
            XML and be parsed by the installer
        -->
        <menu link="anoption=avalue&amp;anoption1=avalue1">COM_EXAMPLE_SUBMENU_ANOPTION</menu>
        <menu view="viewname">COM_EXAMPLE_SUBMENU_VIEWNAME</menu>
    </submenu>
</administration>

每个<menu>项目可以定义以下属性

属性	描述
link	单击菜单项时发送用户的链接。您可以使用“view”代替。
view	要添加到链接的 URL 参数。例如，com_example 的 XML 清单中的`<menu view="cpanel">COM_EXAMPLE</menu>`将导致菜单项的 URL 为 index.php?option=com_example&view=cpanel。您可以使用“link”代替。
img	出现在菜单项旁边的图像（16x16 像素）的（相对）路径。也必须是与文件兼容的 url（例如，没有空格）！
alt	链接的 alt 文本

您还可以创建指向仪表板的链接 - 请参阅下一节以获取详细信息。

标签内的值是菜单的标签。如果您在这些元素内使用语言字符串，则应在组件的 .sys.ini 文件中定义它们。

安装程序在#__menu表中为这些菜单项创建条目，并且 Joomla 在构建管理员菜单时从数据库加载这些条目。

（com_content 等组件的管理员菜单项在组件的预设文件夹中定义，例如在 administrator/components/com_content/presets/content.xml 中）。

仪表板

您可以使用以下方法为您的组件创建仪表板

<dashboards>
    <dashboard title="Example Dashboard" icon="icon-lock">example</dashboard>
</dashboards>

安装您的组件后，您可以使用以下方法导航到您的仪表板

administrator/index.php?option=com_cpanel&view=cpanel&dashboard=example

这将在顶部显示title和icon，但最初为空。您可以使用预设为仪表板定义项目，或者使用位置cpanel-example向其中添加管理员模块，如仪表板中所述。

要创建指向您的仪表板的链接，请使用（在您的管理员菜单部分）

<administration>
    <menu>COM_EXAMPLE
        <params>
            <dashboard>example</dashboard>
        </params>
    </menu>
</administration>

<dashboard>标签中的文本“example”必须与<dashboards>元素中相应标签中的文本匹配。

配置

对于模块、插件和模板，您可以使用<config>部分定义配置。在<config>标签内，您指定配置字段，如表单字段中所述。

Joomla 扩展中有很多示例，例如 mod_breadcrumbs。

通过导航到管理员“管理模块”/“管理插件”/“模板样式”功能来定义配置。

您不能使用<config>来定义组件的配置。有关如何提供组件配置的详细信息，请参阅开发 MVC 组件/添加配置，该文档（尽管是为 Joomla 3 编写的）仍然适用。

待办事项

将上述链接更新为手册中包含 MVC 组件教程时。

命名空间

使用以下方法定义扩展的命名空间前缀

<namespace path="src">Mycompany\Component\Example</namespace>

有关详细信息，请参阅手册命名空间部分。

SQL

SQL 部分（主要由组件使用）允许您更改扩展程序拥有的数据库数据。

更改类型有 3 种

安装扩展程序的初始数据库设置，用于扩展程序的第一个版本（或至少是第一个配置数据库的版本）。
更新从先前版本升级到此版本时要应用的数据库更改
卸载卸载扩展程序时要应用的数据库更改。

对于每种类型的数据库（例如 mysql），您将拥有

1 个用于安装的 SQL 文件
1 个用于卸载的 SQL 文件
一个包含多个更新 SQL 文件的文件夹，每个文件都支持从先前版本升级到当前版本

每个 SQL 文件都包含一系列 SQL 语句，表名使用“#__”前缀，例如“#__categories”。

按照惯例，所有这些 sql 文件都存储在管理员文件夹内的名为“sql”的文件夹中，您必须在管理员文件部分中定义它，例如

<administration>
    <files folder="admin/">
        <folder>sql</folder>
    </files>
</administration>

对于您的安装文件

<install>
    <sql>
        <file driver="mysql" charset="utf8">sql/example.install.sql</file>
    </sql>
</install>

您可以拥有多个 <file> 元素，用于不同的数据库驱动程序。

对于您的卸载文件

<uninstall>
    <sql>
        <file driver="mysql" charset="utf8">sql/example.uninstall.sql</file>
    </sql>
</uninstall>

对于您的更新文件

<update>
    <schemas>
        <schemapath type="mysql">sql/updates/mysql</schemapath>
    </schemas>
</update>

例如，sql/updates/mysql 包含一系列文件，例如

0.0.2.sql（用于升级到 v0.0.2）
0.0.3.sql（用于从 v0.0.2 升级到 v0.0.3），等等。
0.0.4.sql（用于从 v0.0.3 升级到 v0.0.4），等等。

如果您安装的第一个版本例如是 0.0.4，那么 Joomla 将使用初始的 example.install.sql 文件，然后按顺序应用更新文件以达到 v0.0.4。

如果您安装了一个版本的扩展程序，然后跳过一些版本再安装下一个版本，那么 Joomla 将应用每个更新 sql 文件，以从您的先前版本转到您正在安装的版本。

当前安装的版本保存在 #__schemas 表中。您可以在开发 MVC 组件/使用数据库中找到一个可行的示例。

待办事项

将上述链接更新为手册中包含 MVC 组件教程时。

语言

您以类似于以下结构的方式指定语言 ini 文件

language
 ├─── en-GB
 │     ├─── mod_hello.ini
 │     └─── mod_hello.sys.ini
 └─── fr-FR
       ├─── mod_hello.ini
       └─── mod_hello.sys.ini

子文件夹名称（例如 en-GB）必须与扩展程序支持的语言的语言代码匹配。您可以通过 Joomla 语言下载找到 Joomla 支持的所有语言（及其语言代码）的列表。

（出于历史原因，Joomla 还支持以语言代码为前缀的语言文件名，例如 en-GB.mod_hello.ini）。

您可以使用两种方法来安装扩展程序的语言文件。

使用 <languages> 标签

<languages folder="language">
    <language tag="en-GB">com_example.ini</language>
    <language tag="en-GB">com_example.sys.ini</language>
</languages>

Joomla 将把您的语言文件（来自“folder”属性中指定的文件夹）复制到相应的 Joomla 语言文件夹

在 /language 下，用于网站前端（网站模块、网站模板和组件，当 <languages> 标签直接位于 <extension> 内部时）。
在 /administrator/language 下，用于管理员后端（插件、管理员模块、管理员模板和组件，当 <languages> 标签位于 <administration> 内部时）。

然后，您可以在代码中使用以下方法加载您的 .ini 语言文件（例如，对于 mod_example）

Factory::getApplication()->getLanguage()->load('mod_example');

从语言文件夹复制

<files>
    <folder>language</folder>
</files>
or
<administration>
    <files>
        <folder>language</folder>
    </files>
</administration>

这将简单地将您的“language”文件夹复制到扩展程序的目标文件夹中。在这种情况下，您必须将文件夹命名为“language”，因为这是 Joomla 用于查找语言文件的文件夹的名称。

要加载您的 .ini 语言文件，您必须传递扩展程序的基本路径（例如，对于网站模块 mod_example）

Factory::getApplication()->getLanguage()->load('mod_example', JPATH_BASE . '/modules/mod_example');

这种第二种方法的优点是语言文件继续与您的扩展程序紧密相关。

如果管理员卸载了一种语言，则

对于选项 1，您的扩展程序的语言文件将被删除
对于选项 2，您的扩展程序的语言文件将保留。

如果管理员随后重新安装了已删除的语言，则

对于选项 1，需要重新安装您的扩展程序才能恢复已重新安装语言的语言文件
对于选项 2，无需采取任何进一步的操作。

脚本文件

<scriptfile>script.php</scriptfile>

这指定了一个脚本文件的名称，该文件包含在安装过程中运行的 PHP 代码。它在安装过程和脚本文件中进行了描述。

库文件

这特定于类型为“library”的清单。

<libraryname>mylib</libraryname>

Joomla 将把 libraries/mylib 视为目标目录，并将复制其中的所有文件和文件夹。

如果您的公司有多个库，并且希望将它们组合到 JPATH_SITE/libraries/mycompany 文件夹下，则在每个库的 <libraryname> 标签中包含您的公司名称

<libraryname>mycompany/mylib1</libraryname>

<libraryname>mycompany/mylib2</libraryname>

然后，这些库将安装在 JPATH_SITE/libraries/mycompany/mylib1 和 JPATH_SITE/libraries/mycompany/mylib2 文件夹中。卸载 mylib1 仍然会保留已安装在您网站上的 mylib2。

更新服务器

<updateservers>
    <server type="extension" priority="1" name="Extension Update Site">http://example.com/extension.xml</server>
    <server type="collection" priority="2" name="Collection Update Site">http://example.com/collection.xml</server>
</updateservers>

请参阅更新服务器。

变更日志

指定扩展程序此版本的变更日志描述的 URL

<changelogurl>https://example.com/updates/changelog.xml</changelogurl>

<changelogurl> 标签中的 URL 在其前后不得有任何空格或换行符。

请参阅有关变更日志的部分。

下载密钥

用户可以通过更新站点列表输入其下载密钥，该列表提供了一个管理密钥的集中位置。当用户要更新扩展程序时，Joomla 将检查是否存在下载密钥。如果存在下载密钥，Joomla 将将下载密钥添加到更新 URL 中。

要支持下载密钥，您必须在清单文件中包含 dlid 标签。dlid 标签采用 2 个参数

前缀
后缀

在您的清单文件中，dlid 标签将如下所示

<dlid prefix="dlid=" suffix="&amp;dummy=my.zip"/>

前缀将添加到下载密钥之前，后缀将添加到下载密钥之后。使用上面的示例，添加到下载链接的完整查询将是

dlid=KEY&amp;dummy=my.zip

在触发 onInstallerBeforePackageDownload 事件之前添加密钥，因此完整 URL 将传递到事件中。

摘要

本文档说明了在扩展程序的哪些安装过程中支持哪些清单元素。

组件	文件	语言	库	模块	包	插件	模板
`<sql>`	是	是	否	否	是	否	是
`<languages>`	是	是	否	是	是	是	是
`<tag>`	否	否	是	否	否	否	否
`<media>`	是	否	是	是	是	否	是
`<config>`	否	否	否	否	是	否	是
`<script>`	是	是	否	否	是	是	是
`<updateserver>`	是	是	是	是	是	是	是

文件命名约定​

根元素​

元数据​

前端文件​

媒体文件​

管理部分​

管理员后端文件​

管理员菜单链接和子菜单​

仪表板​

配置​

命名空间​

SQL​

语言​

脚本文件​

库文件​

更新服务器​

变更日志​

下载密钥​

摘要​