基本模块
如果你对 Joomla 开发完全陌生,你可能会发现浏览模块教程会更容易,它将更详细地解释你需要做些什么。
在本部分,我们将创建一个简单模块,以便在前台输出一个文本字符串。
清单文件
有关清单文件的常规信息,请参阅清单文件。
<?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>
查看清单文件文档中有关语言文件约定部分以获取更多信息。对于我们的模块,我们设置了以下语言常量
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"
请注意,描述文本应始终具有描述性。例如,如果我们有一个标题为“公司徽标”的字段,则仅仅名称本身就应该足够有意义,甚至可能不需要描述。
MOD_EXAMPLE="Example"
MOD_EXAMPLE_XML_DESCRIPTION="An example Module for Joomla!"
mod_example.ini
文件包含模块渲染(管理界面和渲染)中使用的所有语言常量和翻译,而 mod_example.sys.ini
用于模块设置或模块渲染之外的所有内容,例如模块表单中的模块标题和描述。
服务提供程序文件
<?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 行即可为模块设置正确的命名空间。
$container->registerServiceProvider( new ModuleDispatcherFactory('\\My\\Module\\Example'));
$container->registerServiceProvider( new HelperFactory('\\My\\Module\\Example\\Site\\Helper'));
调度程序
<?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
在我们的调度程序中,我们调用了一个助手文件,现在需要创建该文件。
<?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 结构放置在模板文件中并输出变量。
<?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 文件:此处。