مرحله ۵: اضافه کردن تنظیمات

مقدمه 

در این مرحله، یک پارامتر پیکربندی اضافه می‌کنیم که سطح هدر پیام "Hello" را مشخص می‌کند. با کلیک روی ماژول در بخش Content / Site Modules، مدیر سایت می‌تواند سطح هدر را بین h3 تا h6 تنظیم کند. 

به عنوان نکته‌ای جانبی، ممکن است دیده باشید که پارامترهای ماژول در تب Advanced فرم ویرایش ماژول در پنل مدیریت وجود دارند. این پارامترها به ماژول رابریا (wrapper) و عنوان ماژول اشاره دارند که جوملا به صورت خودکار به هر ماژول اضافه می‌کند. 

کد منبع در mod_hello مرحله ۵ در دسترس است.

  https://github.com/joomla/manual-examples/tree/main/module-tutorial/step5_config

فایل مانیفست به‌روز شده 

پیکربندی با افزودن یک بخش به فایل مانیفست انجام می‌شود: 

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>

جوملا مکانیزمی برای تعریف فرم‌های HTML در قالب XML دارد که در بخش‌های Forms و Form Fields توضیح داده شده است. این شامل چارچوبی برای مدیریت پارامترهای HTTP POST فرم تا ذخیره آن‌ها در پایگاه داده می‌شود. 

این موضوع توسعه فرم‌های جوملا را بسیار ساده می‌کند و به شما امکان می‌دهد خیلی سریع فرم‌ها را بدون نیاز به تکرار کدهای پایه‌ای بسازید، البته بعد از اینکه اصول کارکرد آن را یاد گرفتید. 

در این مورد، بخش <config> یک فیلد انتخاب (Select) با لیست کشویی HTML تعریف می‌کند. این فیلد بخشی از فرمی است که هنگام کلیک مدیر روی ماژول در لیست Content / Site Modules نمایش داده می‌شود. (این فرم در واقع در مسیر administrator/components/com_modules/forms/module.xml تعریف شده است). 

بخش‌هایی از این بخش <config> به شرح زیر است: 

- `<fields name="params">` باعث می‌شود داده‌ها در پارامترهای HTTP POST در آرایه‌ای به نام params ارسال شوند. این آرایه به فیلد "params" در رکورد ماژول در جدول #__modules در پایگاه داده نگاشت می‌شود که به صورت رشته JSON ذخیره می‌گردد. 

- `<fieldset name="basic">` باعث می‌شود این فیلد در تب Module در فرم ظاهر شود. اگر به جای آن "advanced" انتخاب می‌شد، فیلد در تب Advanced نمایش داده می‌شد. 

- `<field name="header">` برای دسترسی به مقدار فیلد در کد استفاده می‌شود. 

- `<field type="list">` نوع فیلد جوملا را مشخص می‌کند که لیست کشویی تولید می‌شود. انواع فیلدهای استاندارد در مستندات فرم‌ها لیست شده‌اند. 

- `<field label="MOD_HELLO_HEADER_LEVEL">` برچسب HTML فیلد را تعیین می‌کند. 

دریافت مقدار پارامتر

وقتی جوملا کلاس Dispatcher شما را نمونه‌سازی می‌کند، سه پارامتر را به سازنده (constructor) منتقل می‌کند:

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

بیایید هر کدام از این پارامترها را با جزئیات بیشتری بررسی کنیم.

پارامتر Module

پارامتر `$module` یک ساختار شامل چندین فیلد مرتبط با ماژول است و بسیاری از این فیلدها در جدول پایگاه داده #__modules ذخیره شده‌اند. به طور خاص، پارامترهای پیکربندی در فیلدی با نام `params` به صورت رشته JSON نگهداری می‌شوند.

برای دسترسی به پارامترهای جداگانه، می‌توانید از کلاس `Joomla\Registry\Registry` که یک کلاس کمکی برای کار با ساختارهای داده است، استفاده کنید.

در سازنده Dispatcher، ما `$module` را به عنوان یک متغیر نمونه ذخیره می‌کنیم و سپس پارامتر `header` را به این صورت دریافت می‌کنیم:

use Joomla\Registry\Registry;
$params = new Registry($this->module->params);
// و در فایل tmpl:
$h = $params->get('header', 'default');

برای جزئیات بیشتر مستندات API مربوط به Registry را مطالعه کنید.

پارامتر Application

کلاس Application هسته اصلی برنامه جوملا است و دسترسی به آن به ما امکان می‌دهد به بسیاری از نمونه‌های کلاس‌های دیگر جوملا دسترسی پیدا کنیم، مثلاً کلاس Language در مرحله آموزشی قبلی.

در سازنده Dispatcher، این پارامتر را به عنوان متغیر نمونه `$app` ذخیره می‌کنیم و سپس از آن برای جایگزینی خط زیر استفاده می‌کنیم:

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

با:

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

پارامتر Input

این پارامتر برای دسترسی به پارامترهای URL کاربرد دارد، همانطور که در مستندات Input توضیح داده شده است؛ اما در ماژول 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"

نصب 

پس از نصب فایل زیپ به روش معمول، به بخش Administrator > Content / Site Modules بروید و روی ماژول mod_hello کلیک کنید تا آن را ویرایش کنید. 

در اینجا می‌توانید سطح هدر را بین h3 تا h6 تغییر دهید. 

پس از ذخیره تغییرات، صفحه‌ای از سایت را نمایش دهید و با استفاده از ابزارهای توسعه‌دهنده مرورگر (devtools)، عنصر HTML ایجاد شده را بررسی کنید. 

جدول‌های Extensions و Modules

شاید متوجه شده باشید که ماژول mod_hello هم در جدول‌های #__extensions و هم #__modules پایگاه داده ظاهر می‌شود و ممکن است بپرسید چرا این اتفاق می‌افتد.

- جدول #__extensions شامل رکوردهایی برای همه افزونه‌های نصب شده در جوملا است. در این جدول، فقط یک رکورد برای هر افزونه وجود دارد.

  - جدول #__modules شامل رکوردهایی برای هر نمونه (instance) ماژولی است که در بخش مدیریت یا سایت فعال شده است؛ یعنی هر بار که یک نمونه از ماژول روی یک موقعیت قالب یا صفحه مشخص فعال می‌شود، یک رکورد جداگانه خواهد داشت. بنابراین می‌توان چند نمونه (instance) از mod_hello یا هر ماژول دیگری ایجاد کرد تا در موقعیت‌ها یا صفحات مختلف (حتی یک موقعیت) نمایش داده شوند و به این ترتیب رکوردهای متعددی در این جدول ایجاد می‌شود.

زمانی که جوملا mod_hello را نصب می‌کند، علاوه بر ایجاد رکورد در جدول #__extensions، به شما کمک می‌کند که سریع‌تر شروع کنید و یک رکورد پیش‌فرض در #__modules هم ایجاد می‌کند. جوملا فرض می‌کند که چون شما این ماژول را نصب کرده‌اید، احتمالاً می‌خواهید آن را در یک صفحه وب استفاده کنید. اما جایی که می‌خواهید آن را قرار دهید (موقعیت قالب) یا اینکه واقعاً می‌خواهید ماژول فعال باشد یا نه را نمی‌داند؛ پس این نمونه ماژول را به صورت منتشر نشده (unpublished) و تنظیم شده روی "بدون صفحه" (No pages) ایجاد می‌کند.

تنظیماتی که در اینجا پیاده کرده‌ایم مربوط به پیکربندی نمونه‌های مجزای هر ماژول است. بنابراین شما می‌توانید چند نمونه از mod_hello را در بخش Content / Site Modules ایجاد کنید که هر کدام تنظیمات پیکربندی خاص خود را داشته باشند.