مرحله ۱: ماژول پایه

هدف مرحله اول، ساخت یک ماژول سایت عملی است که بتوانید در نصب جوملای خود آن را ببینید. 

در این مرحله، ماژول فقط یک کد HTML ساده به شکل زیر نمایش می‌دهد:

<h4>Hello</h4>

کد منبع این مرحله نیز در پروژه mod_hello مرحله ۱ موجود است.

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

کد منبع

در این مرحله شما باید ۳ فایل را در پوشه‌ای به نام `mod_hello` بسازید (بر اساس نموداری که در زیر آمده است).

فایل مانیفست

`mod_hello/mod_hello.xml`

<?xml version="1.0" encoding="UTF-8"?>
<extension type="module" client="site" method="upgrade">
    <name>Joomla module tutorial</name>
    <version>1.0.1</version>
    <author>me</author>
    <creationDate>today</creationDate>
    <description>Code used in the Joomla module tutorial</description>
    <namespace path="src">My\Module\Hello</namespace>
    <files>
        <folder module="mod_hello">services</folder>
        <folder>src</folder>
    </files>
</extension>

توضیح فایل مانیفست

این فایل "مانیفست" نام دارد و به نصب‌کننده جوملا اطلاعات کلیدی درباره افزونه‌ای که می‌خواهید نصب کنید، می‌دهد:

- `type="module"`: نوع افزونه ماژول است (نه کامپوننت، پلاگین و غیره). 

- `client="site"`: این ماژول برای سمت «سایت» یا بخش جلویی جوملا است، نه مدیریت (administrator).

- `method="upgrade"`: این مورد بیشتر مربوط به مراحل بعدی است و به این معنی است که نسخه‌ای که نصب می‌شود می‌تواند نسخه قبلی را جایگزین کند (یعنی یک به‌روزرسانی است). 

- `<name>`, `<author>`, `<creationDate>`, `<description>`: این موارد توضیحی هستند و توسط جوملا اعتبارسنجی نمی‌شوند. بعد از نصب ماژول می‌توانید آن‌ها را در بخش مدیریت ماژول‌ها مشاهده کنید. 

- `<version>`: نسخه ماژول است که باید هنگام انتشار نسخه‌های بعدی به‌روزرسانی شود. 

- `<files>`: به نصب‌کننده می‌گوید کدام فایل‌ها جزو کد ماژول هستند. صفت `module="mod_hello"` به جوملا می‌گوید پوشه `services` را بررسی کند تا فایل سرویس‌دهنده (service provider) که نقطه شروع ماژول است را بیابد. اگر فایل‌هایی در دایرکتوری وجود داشته باشند که در این بخش `<files>` بیان نشده باشند، توسط نصب‌کننده جوملا نادیده گرفته می‌شوند. 

- `<namespace>`: فضای نام (namespace) پیشوندی مخصوص ماژول `mod_hello` است. این نام طبق توصیه‌های جوملا انتخاب شده و ما به عنوان نام شرکت از "My" استفاده کرده‌ایم.

صفت `path="src"` به این معنی است که کلاس‌های PHP ما باید در زیرشاخه `/src` قرار بگیرند و این پوشه باید در بخش `<files>` ذکر شود تا نصب‌کننده جوملا آن را پردازش کند.

فضای نام (namespace) `\My\Module\Hello\Site` به این پوشه اشاره خواهد کرد و ما باید طبق استاندارد PSR-4 کلاس‌هایمان را در اینجا نامگذاری کنیم.

توضیحات بیشتر درباره فضای نام در بخش Namespaces و درباره فایل‌های مانیفست در بخش Manifest Files مقاله اصلی موجود است.

فایل سرویس پروایدر

کد زیر را در فایل `mod_hello/services/provider.php` قرار دهید:

<?php

\defined('_JEXEC') or die;

use Joomla\CMS\Extension\Service\Provider\Module as ModuleServiceProvider;
use Joomla\CMS\Extension\Service\Provider\ModuleDispatcherFactory as ModuleDispatcherFactoryServiceProvider;
use Joomla\DI\Container;
use Joomla\DI\ServiceProviderInterface;
return new class () implements ServiceProviderInterface {
    public function register(Container $container): void
    {
        $container->registerServiceProvider(new ModuleDispatcherFactoryServiceProvider('\\My\\Module\\Hello'));
        $container->registerServiceProvider(new ModuleServiceProvider());
    }
};

اگر تازه‌کار در توسعه جوملا هستید، احتمالاً این کد برایتان کمی گیج‌کننده به نظر برسد. بهتر است فعلاً آن را بدون نگرانی قبول کنید. این فقط کد پایه (boilerplate) است که اتصال کد هسته جوملا با افزونه `mod_hello` ما را برقرار می‌کند. توضیحات بیشتر درباره‌ی این بخش در مرحله «تزریق وابستگی‌ها (Dependency Injection)» آموزش داده خواهد شد.

فایل دیسپاچر (Dispatcher)

هنگامی که جوملا کد ماژول `mod_hello` را اجرا می‌کند، با نمونه‌سازی (ایجاد آبجکت) از کلاس `Dispatcher` آغاز کرده و متد `dispatch()` آن را فرا می‌خواند.

فایل: `mod_hello/src/Dispatcher/Dispatcher.php`

<?php
namespace My\Module\Hello\Site\Dispatcher;
\defined('_JEXEC') or die;
use Joomla\CMS\Dispatcher\DispatcherInterface;
class Dispatcher implements DispatcherInterface
{
    public function dispatch()
    {
        echo '<h4>Hello</h4>';
    }
}

نکته امنیتی: خط `\defined('_JEXEC') or die;` در ابتدای فایل، ویژگی امنیتی است. اگر کسی تلاش کند مستقیماً به این فایل PHP از طریق آدرس اینترنتی دسترسی پیدا کند، بدلیل نبود تعریف ثابت `_JEXEC`، اسکریپت متوقف می‌شود. جوملا هنگام اجرا، این ثابت را تعریف می‌کند؛ بنابراین وقتی جوملا ماژول را اجرا می‌کند، این خط مانع اجرای مستقیم و غیرمجاز کد می‌شود.

(بک اسلش `\` قبل از تابع `defined` مشخص می‌کند که می‌خواهیم از تابع `defined` در فضای نام (namespace) سراسری PHP استفاده کنیم و نه فضای نام فعلی فایل. در اینجا اگر نگذاریم هم مشکلی پیش نمی‌آید چون تابعی به این نام در فضای محلی وجود ندارد و PHP به صورت پیش‌فرض تابع سراسری را فرا می‌خواند.)

نصب ماژول شما

حالا پوشه‌ی `mod_hello` که شامل ۳ فایل کد منبع است را در قالب یک فایل ZIP فشرده کنید تا مثلا فایلی بنام `mod_hello.zip` بسازید.

1. به بخش مدیریت (Administrator) جوملا بروید. 

2. به مسیر System > Install > Extensions بروید و تب Upload Package File را باز کنید. 

3. روی دکمه‌ی «browse for file» کلیک کنید و فایل `mod_hello.zip` را انتخاب کنید تا جوملا آن را نصب کند.

پس از نصب موفق، پیامی مانند زیر دریافت خواهید کرد:

Installation of the module was successful.

همراه با متن توضیحی که در عنصر `<description>` در فایل مانیفست شما نوشته شده است.

جوملا کد شما را در پوشه `/modules` ذخیره می‌کند. اگر این پوشه را باز کنید، باید پوشه `mod_hello` را به همراه ساختار فایل‌ها در آن ببینید.

نمایش ماژول شما

برای اینکه ماژول شما در سایت دیده شود، باید سه کار انجام دهید:

- ماژول خود را منتشر (Publish) کنید 

- موقعیت (Position) قالب برای ماژول تعریف کنید 

- صفحات سایت که ماژول در آن‌ها نمایش داده می‌شود را تعیین کنید

مراحل انجام کار

1. وارد بخش مدیریت (Administrator backend) جوملا شوید و به مسیر Content / Site Modules بروید. 

2. باید ماژولی با عنوان «Joomla module tutorial» (یا هر نامی که در تگ `<name>` فایل مانیفست وارد کرده‌اید) ببینید. در ستون وضعیت (Status) علامت ضربدر (cross) نشان می‌دهد که ماژول منتشر نشده است. 

3. روی عنوان ماژول کلیک کنید تا به صفحه ویرایش ماژول بروید، سپس تب Module را انتخاب کنید.

4. در فیلد Position موقعیت ماژول را روی `"sidebar-right"` انتخاب کنید. 

5. در فیلد Status مقدار `"Published"` را انتخاب کنید. 

6. به تب Menu Assignment بروید، در فیلد Module Assignment گزینه "On all pages" را انتخاب کنید. 

7. روی دکمه Save and Close کلیک کنید تا به لیست ماژول‌های سایت بازگردید.

نتیجه

اکنون در لیست ماژول‌ها باید در ستون Status علامت تیک سبز و در ستون Position مقدار `"sidebar-right"` را برای ماژول «Joomla module tutorial» مشاهده کنید.

اگر حالا یک صفحه از وب‌سایت خود را باز کنید، ماژول شما باید در نوار کناری سمت راست (right-hand sidebar) نمایش داده شود.

عیب‌یابی

اگر خطای Class not found دریافت کردید، به این معنی است که جوملا نتوانسته یکی از کلاس‌هایی که در کد خود تعریف کرده‌اید را پیدا کند.

موارد زیر را به دقت بررسی کنید:

- تگ `<namespace>` در فایل مانیفست 

- دستورات `use` در فایل‌های PHP 

- نام کلاس در فایل کلاس PHP 

- نام فایل کلاس PHP

جوملا با توجه به این موارد، فایل منبع کلاس را طبق استاندارد PSR-4 پیدا می‌کند.

همچنین مطمئن شوید که زیرپوشه‌ها در داخل پوشه `/src` و نام فایل‌های کلاس PHP شما با حروف بزرگ و کوچک به درستی نوشته شده‌اند. 

اگر در سیستم عامل ویندوز توسعه می‌دهید، ویندوز تفاوت بین حروف بزرگ و کوچک در نام فایل‌ها را نادیده می‌گیرد، اما اگر افزونه را در یک سایت زنده (live) که روی لینوکس است نصب کنید، ممکن است خطای «کلاس پیدا نشد» رخ دهد زیرا لینوکس حساس به بزرگی و کوچکی حروف است.

پیدا کردن موقعیت‌های قالب (Template Positions)

در بخش قبلی ما موقعیت `"sidebar-right"` را برای ماژول پیشنهاد کردیم، اما مطمئناً تعداد زیادی موقعیت مختلف وجود دارد. پس چگونه موقعیت مناسب را انتخاب کنیم؟

- اگر از قالب پیش‌فرض جوملا به نام Cassiopeia استفاده می‌کنید، می‌توانید موقعیت‌های قالب آن را [در اینجا مشاهده کنید](https://docs.joomla.org/Cassiopeia_Template#Positions).

- روش مفید دیگری این است که به بخش مدیریت جوملا بروید به مسیر System / Global Configuration، تب Templates را باز کنید، گزینه Preview Module Positions را فعال (Enabled) کرده و تغییرات را ذخیره کنید.

سپس به سایت خود بروید و در انتهای آدرس صفحه خود پارامتر `?tp=1` را اضافه کنید؛ مثلا: 

`http://localhost/joomsite/index.php?tp=1`

در این حالت موقعیت‌های قالب به شما نشان داده خواهد شد.