跳至主要内容
版本:5.1

基本模块

如果你对 Joomla 开发完全陌生,你可能会发现浏览模块教程会更容易,它将更详细地解释你需要做些什么。

在本部分,我们将创建一个简单模块,以便在前台输出一个文本字符串。

清单文件

有关清单文件的常规信息,请参阅清单文件

mod_example/mod_example.xml
<?xml version="1.0" encoding="utf-8"?>
<extension type="module" client="site" method="upgrade">
<name>MOD_EXAMPLE</name>
<creationDate>Today</creationDate>
<author>Me</author>
<authorEmail>email</authorEmail>
<authorUrl>web</authorUrl>
<copyright>(C) 2024 Open Source Matters, Inc.</copyright>
<license>GNU General Public License version 2 or later</license>
<namespace path="src">My\Module\Example</namespace>
<version>1.0.0</version>
<description><![CDATA[MOD_EXAMPLE_XML_DESCRIPTION]]></description>
<files>
<folder module="mod_example">services</folder>
<folder>language</folder>
<folder>src</folder>
<folder>tmpl</folder>
<file>mod_example.xml</file>
</files>
<languages>
<language tag="en-GB">language/en-GB/mod_example.ini</language>
<language tag="en-GB">language/en-GB/mod_example.sys.ini</language>
</languages>
<config>
<fields name="params">
<fieldset name="basic" addfieldprefix="My\Module\Example\Site\Field">
<field name="my-message" type="text" label="MOD_EXAMPLE_FIELD_MY_MESSAGE_LABEL" description="MOD_EXAMPLE_FIELD_MY_MESSAGE_DESC" />
</fieldset>
</fields>
</config>
</extension>

当涉及到清单文件时,Joomla 非常具体,很容易出点问题,让你疑惑于你的模块为何不起作用。这里有一些你必须正确处理的事情。

扩展类型

<extension type="module" client="site" method="upgrade">

语言常量

<name>MOD_EXAMPLE</name>
<description><![CDATA[MOD_EXAMPLE_XML_DESCRIPTION]]></description>

您不必在此处使用语言字符串,但如果您这样做,则应在您的语言.sys.ini文件中提供语言字符串的值。(名称和描述显示在管理员模块表单中)。

命名空间

<namespace path="src">My\Module\Example</namespace>

严格来说,您不必按照 Joomla 推荐的方式进行操作

<MyCompany>\Module\<module name>

但您必须确保您在此处的命名空间前缀与

  • 位于您的 services/provider.php 文件中的 use 语句相匹配,以及,
  • 位于您的 main Extension 类的 namespace 语句相匹配

并且您的所有类都位于在 path 属性中指定的 /src 文件夹之下。

如果您遇到命名空间问题,则可以检查 administrator/cache/autoload_psr4.php 以验证插件的命名空间前缀是否指向您期望的位置。只要您安装任何扩展(前提是已启用 Extension - Namespace Updater 插件),就会重新生成此缓存文件,但如果您直接在 Joomla 站点代码中进行更改,则可能需要删除缓存文件;下次导航到 Joomla 实例时,会重新生成该文件。

模块入口点

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

通过在 services 文件夹上使用 module="mod_example" 确保指定模块的入口点。

确保您的清单 XML 文件的名称与命名约定匹配(即必须命名为 mod_example.xml)。

语言文件

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

查看清单文件文档中有关语言文件约定部分以获取更多信息。对于我们的模块,我们设置了以下语言常量

language/en-GB/mod_example.ini
MOD_EXAMPLE="Example"
MOD_EXAMPLE_XML_DESCRIPTION="An example Module for Joomla!"

MOD_EXAMPLE_FIELD_MY_MESSAGE_LABEL="Your Message"
MOD_EXAMPLE_FIELD_MY_MESSAGE_DESC="Description Text for your Message Field"

请注意,描述文本应始终具有描述性。例如,如果我们有一个标题为“公司徽标”的字段,则仅仅名称本身就应该足够有意义,甚至可能不需要描述。

language/en-GB/mod_example.sys.ini
MOD_EXAMPLE="Example"
MOD_EXAMPLE_XML_DESCRIPTION="An example Module for Joomla!"

mod_example.ini 文件包含模块渲染(管理界面和渲染)中使用的所有语言常量和翻译,而 mod_example.sys.ini 用于模块设置或模块渲染之外的所有内容,例如模块表单中的模块标题和描述。

服务提供程序文件

mod_example/services/provider.php
<?php
defined('_JEXEC') or die;

use Joomla\CMS\Extension\Service\Provider\HelperFactory;
use Joomla\CMS\Extension\Service\Provider\Module;
use Joomla\CMS\Extension\Service\Provider\ModuleDispatcherFactory;
use Joomla\DI\Container;
use Joomla\DI\ServiceProviderInterface;

return new class() implements ServiceProviderInterface
{
/**
* @param Container $container
*
* @since version
*/
public function register(Container $container)
{
$container->registerServiceProvider( new ModuleDispatcherFactory('\\My\\Module\\Example'));
$container->registerServiceProvider( new HelperFactory('\\My\\Module\\Example\\Site\\Helper'));
$container->registerServiceProvider( new Module());
}
};

这几乎是用于从依赖注入容器获取模块的样板代码,您只需要更改 2 行即可为模块设置正确的命名空间。

需要在 mod_example/services/provider.php 中更改的行

$container->registerServiceProvider( new ModuleDispatcherFactory('\\My\\Module\\Example'));
$container->registerServiceProvider( new HelperFactory('\\My\\Module\\Example\\Site\\Helper'));

调度程序

mod_example/src/Dispatcher/Dispatcher.php
<?php
/**
* @package <mod_example>
*
* @author <MyCompany> | <Me> <email>
* @copyright Copyright(R) year by <MyCompany> | <Me>
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link <mywebsite>
* @since 1.0.0
*
*/

namespace My\Module\Example\Site\Dispatcher;

defined('_JEXEC') or die;

use Joomla\CMS\Dispatcher\AbstractModuleDispatcher;
use Joomla\CMS\Helper\HelperFactoryAwareInterface;
use Joomla\CMS\Helper\HelperFactoryAwareTrait;
use Joomla\CMS\Uri\Uri;
use Joomla\Registry\Registry;
use My\Module\Example\Site\Helper\ExampleHelper;

class Dispatcher extends AbstractModuleDispatcher implements HelperFactoryAwareInterface
{
use HelperFactoryAwareTrait;

protected function getLayoutData()
{
// Get the module Parameters
$params = new Registry($this->module->params);
$data = parent::getLayoutData();

$helperName = 'ExampleHelper';
$data['mymsg'] = $this->getHelperFactory()->getHelper($helperName)->getMessage($data['params'], $this->getApplication());
return $data;
}
}

调度程序负责处理我们的模块调用,并确保处理所需数据并准备用于显示。为此,我们使用一个辅助类,我们的ExampleHelper。getLayoutData 方法仍然可以通过许多方式进行扩展,你还可以在此处集成 WebAssets json 并集中注册此模块的资源,寻址其他辅助类或模块等等。

$data 数组中的所有键值将来在模块模板中都可以直接使用。例如,我们将来可以通过 $mymsg 在模块模板中检索我们的消息。

ExampleHelper

在我们的调度程序中,我们调用了一个助手文件,现在需要创建该文件。

mod_example/src/Helper/ExampleHelper.php
<?php
/**
* @package <mod_example>
*
* @author <MyCompany> | <Me> <email>
* @copyright Copyright(R) year by <MyCompany> | <Me>
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link <mywebsite>
* @since 1.0.0
*
*/

namespace My\Module\Example\Site\Helper;

defined('_JEXEC') or die;

use Joomla\CMS\Language\Text;

class ExampleHelper
{
/**
* Method to get the items the helper calls the model to get the items
*
* @param Registry $params The module parameters
* @param object $app The application object
*
* @return array
*
* @since 2.0
*/
public function getMessage($params, $app)
{
// Get the message from the $params
$message = $params->get('my-message', 'Fallback Message can be noted here');

return $message;
}
}

当然,整个构造对于在模板中显示来自模块设置的消息来说有些过火,但它应该作为一个如何在模块中实现助手的示例。与往常一样,重要的是定义适当的命名空间,以便 Joomla! 也会将此助手考虑在内。

如果需要,助手类当然可以包含更多逻辑、调用模型等等。

模板文件

模板文件负责模块的实际呈现,在大多数情况下,你将 HTML 结构放置在模板文件中并输出变量。

mod_example/tmpl/default.php
<?php
/**
* @package <mod_example>
*
* @author <MyCompany> | <Me> <email>
* @copyright Copyright(R) year by <MyCompany> | <Me>
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link <mywebsite>
* @since 1.0.0
*
* @var $module \Joomla\CMS\Module\Module The module object
* @var $params \Joomla\Registry\Registry The module params
* @var $mymsg string The String that has been noted in the module settings and has been stored in the data array in our Dispatcher
*
*/

defined('_JEXEC') or die;

echo '<h1>' . $mymsg . '</h1>';

安装和测试

在创建了源文件之后,对目录进行压缩,再通过 Joomla administrator 后端安装扩展。

然后,你需要转到管理员内容/网站模块,单击你的 Example 模块进行编辑,然后

  • 输入你的消息
  • 发布你的模块
  • 为你的模块定义一个模板位置
  • 在菜单分配中定义你的模块将显示在哪些网站页面中

然后,你可以导航到你的网站前端,你应该会看到你的模块显示了你的自定义消息。

如果你遇到问题,那么可以从此处下载模块的 zip 文件:此处