版本：5.1

步骤 5 添加配置

介绍

在这一步中，我们添加一个配置参数来指定“Hello”消息的标题级别。通过单击内容/站点模块中的模块，管理员可以将标题级别设置为 h3 到 h6 之间。

顺便说一句，您可能已经注意到，在管理员模块编辑表单的“高级”选项卡中存在模块参数。这些指的是 Joomla 自动添加到每个模块的模块包装器和模块标题。

源代码可以在 mod_hello step 5 找到。

更新的清单文件

配置是通过在清单文件中添加一个部分来实现的

mod_hello/mod_hello.xml
<?xml version="1.0" encoding="UTF-8"?>
<extension type="module" client="site" method="upgrade">
    <name>MOD_HELLO_NAME</name>
    <version>1.0.5</version>
    <author>me</author>
    <creationDate>today</creationDate>
    <description>MOD_HELLO_DESCRIPTION</description>
    <namespace path="src">My\Module\Hello</namespace>
    <files>
        <filename module="mod_hello">mod_hello.php</filename>
        <folder>src</folder>
        <folder>tmpl</folder>
        <folder>language</folder>
    </files>
    <config>
        <fields name="params">
            <fieldset name="basic">
                <field
                    name="header"
                    type="list"
                    label="MOD_HELLO_HEADER_LEVEL"
                    >
                    <option value="h3">MOD_HELLO_HEADER_LEVEL_3</option>
                    <option value="h4">MOD_HELLO_HEADER_LEVEL_4</option>
                    <option value="h5">MOD_HELLO_HEADER_LEVEL_5</option>
                    <option value="h6">MOD_HELLO_HEADER_LEVEL_6</option>
                </field>
            </fieldset>
        </fields>
    </config>
</extension>

Joomla 提供了一种在 XML 中定义 HTML 表单的机制，您可以在表单和表单字段部分了解相关信息。这包括一个用于处理表单 HTTP POST 参数的框架，一直到将这些参数存储在数据库中。

所有这些使得快速开发 Joomla 表单变得非常容易，无需重复样板文本，一旦您克服了最初理解其工作原理的障碍。

在本例中，<config> 部分指定了一个带有下拉列表的 HTML Select 输入字段。此字段成为表单的一部分，该表单在管理员单击内容/站点模块列表中的模块时呈现。（此表单实际上是在 administrator/components/com_modules/forms/module.xml 中定义的）。

<config> 部分中的一些部分在下面描述

<fields name="params"> 导致数据以名为 params 的数组形式发送（在 HTTP POST 参数中）。这将映射到数据库字段“params”，该字段位于此站点模块在 #__modules 数据库表中的记录中，其中参数以 JSON 字符串形式存储。
<fieldset name="basic"> 导致字段包含在表单内的模块选项卡中。如果您指定“advanced”，它将出现在高级选项卡中。
<field name="header"> 用于在代码中获取字段的值
<field type="list"> 指定将生成的 Joomla 字段类型。可用的字段类型列在标准表单字段类型中。
<field label="MOD_HELLO_HEADER_LEVEL"> 将映射到字段的 HTML 标签

待办

在将标准表单字段添加到手册后更新上面的链接

获取参数值

当 Joomla 实例化您的 Dispatcher 类时，它会将 3 个参数传递到构造函数中

public function __construct(\stdClass $module, CMSApplicationInterface $app, Input $input)

让我们更详细地看一下每个参数。

模块参数

$module 参数是一个结构，其中包含与模块相关的多个字段，其中一些字段可以在 #__modules 数据库表中找到。特别是，配置参数保存在名为 params 的字段中，以 JSON 字符串形式存储。

要访问单个参数，您可以使用 Joomla Registry 类，它是一个用于操作数据结构的实用程序类。

在我们的 Dispatcher 构造函数中，我们将 $module 存储为一个实例变量，然后稍后像这样访问“header”参数

use Joomla\Registry\Registry;

$params = Registry($this->module->params);

// and in the tmpl file:
$h = $params->get('header', 'default');

有关详细信息，请参阅 Registry API 文档。

应用程序参数

Application 类是 Joomla 应用程序的核心类，访问它使我们能够访问许多其他 Joomla 类实例，例如上一个教程步骤中的 Language 类。

在我们的 Dispatcher 构造函数中，我们将它存储为一个实例变量 $app，然后使用它来替换以下代码行

$language = Factory::getApplication()->getLanguage();

替换为

$language = $this->app->getLanguage();

输入参数

这可以用于访问 URL 参数，如输入文档中所述，但 mod_hello 中不需要使用它。

更新的 Dispatcher 文件

mod_hello/src/Dispatcher/Dispatcher.php
<?php

namespace My\Module\Hello\Site\Dispatcher;

\defined('_JEXEC') or die;

use Joomla\CMS\Dispatcher\DispatcherInterface;
use Joomla\CMS\Helper\ModuleHelper;
use Joomla\CMS\Factory;
use Joomla\CMS\Language\Text;
use Joomla\CMS\Application\CMSApplicationInterface;
use Joomla\Input\Input;
use Joomla\Registry\Registry;
use My\Module\Hello\Site\Helper\HelloHelper;

class Dispatcher implements DispatcherInterface
{
    protected $module;
    
    protected $app;

    public function __construct(\stdClass $module, CMSApplicationInterface $app, Input $input)
    {
        $this->module = $module;
        $this->app = $app;
    }
    
    public function dispatch()
    {
        $language = $this->app->getLanguage();
        $language->load('mod_hello', JPATH_BASE . '/modules/mod_hello');
        
        $username = HelloHelper::getLoggedonUsername('Guest');

        $hello = Text::_('MOD_HELLO_GREETING') . $username;
        
        $params = new Registry($this->module->params);

        require ModuleHelper::getLayoutPath('mod_hello');
    }
}

更新的 tmpl 文件

请记住，tmpl 文件将在与我们的 dispatch() 函数相同的函数上下文中运行，因此我们可以访问在那里定义的 $params 变量。

mod_hello/tmpl/default.php
<?php
defined('_JEXEC') or die;

$h = $params->get('header', 'h4');
$greeting = "<{$h}>{$hello}</{$h}>"
?>

<?php echo $greeting; ?>

更新的语言文件

我们必须将 <config> 中的新语言常量包含在 .ini 文件中

mod_hello/language/en-GB/mod_hello.ini
; language strings used inside mod_hello 
MOD_HELLO_NAME="Joomla Module Tutorial"
MOD_HELLO_DESCRIPTION="Source code for the Joomla module tutorial"
MOD_HELLO_GREETING="Hello "
MOD_HELLO_HEADER_LEVEL="Header level of greeting"
MOD_HELLO_HEADER_LEVEL_3="Header level 3"
MOD_HELLO_HEADER_LEVEL_4="Header level 4"
MOD_HELLO_HEADER_LEVEL_5="Header level 5"
MOD_HELLO_HEADER_LEVEL_6="Header level 6"

安装

以通常的方式安装 zip 文件后，您可以转到管理员内容/站点模块，然后单击 mod_hello 模块以编辑它。这应该允许您将标题级别更改为 h3 到 h6 之间。保存更改后，显示网站页面并使用浏览器的开发者工具检查 html 元素。

扩展和模块表

您可能已经注意到，mod_hello 出现在 #__extensions 和 #__modules 数据库表中，您可能想知道为什么。

#__extensions 表包含安装在 Joomla 实例上的所有扩展的记录。此表中每个扩展只有一个记录。

#__modules 表包含已选择出现在管理员后端或网站前端的每个模块的记录，每个模块实例一个记录。您可以创建 mod_hello（或任何模块）的多个实例，使其出现在网页上的不同（甚至相同）模板位置中。然后您将在 #__modules 数据库表中获得该模块的多个实例。

当 Joomla 安装 mod_hello 时，它不仅创建 #__extensions 记录，而且它试图通过也创建一个 #__modules 记录来简化您的操作。它假定，由于您正在安装此模块，因此您将想在网页上使用它。当然，它不知道您想把它放在哪里（模板位置），也不确定您是否真的想把它放在页面上，因此它在未发布的状态下创建它，并将菜单分配设置为“无页面”。

我们在这里实现的配置与各个模块实例的配置相关。因此，您可以使用内容/站点模块创建 mod_hello 的多个实例，每个实例都有自己特定的配置参数。

介绍​

更新的清单文件​

获取参数值​

模块参数​

应用程序参数​

输入参数​

更新的 Dispatcher 文件​

更新的 tmpl 文件​

更新的语言文件​

安装​

扩展和模块表​

介绍