گام اول - یک ماژول ساده

هدف از این مرحله اول این است که شما یک ماژول کارا داشته باشید که می توانید در سایت جوملایی خود مشاهده کنید.

در این مرحله اول ماژول به سادگی HTML را خروجی می کند

<h4>Hello</h4> 

کد منبع همچنین در گام 1 mod_hello موجود است.

در این مرحله باید 3 فایل را در یک پوشه به نام mod_hello ایجاد کنید، همانطور که در این تصویر نشان داده شده است (توجه کنید که بزرگی و کوچکی حروف را رعایت کنید):

حالا درباره تک تک فایلهای داخل این عکس توضیحاتی می دهیم:

فایل mod_hello.xml یا فایل مانیفست افزونه

همانطور که احتمالا می دانید در XML بر خلاف HTML، تگ ها از پیش تعریف شده نیستند. یعنی در زبان XML شما از هر تگی که بخواهید میتوانید استفاده کنید. یکی از مهمترین تفاوت های XML و HTML این است که در HTML برای نمایش اطلاعات و زبان XML برای ذخیره اصلاعات استفاده می شود. از آنجاکه فایل مانیفست افزونه های جوملا به زبان XML است پس اطلاعات فنی و حقوقی مربوط به افزونه های جوملا را در خود ذخیره کرده است. به فایل 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>MasoudNicksefat</author>
    <authorEmail>این آدرس ایمیل توسط spambots حفاظت می شود. برای دیدن شما نیاز به جاوا اسکریپت دارید</authorEmail>
    <authorUrl>https://MasoudNicksefat.ir</authorUrl>
    <creationDate>1404/08/19</creationDate>
    <description>Code used in the Joomla module tutorial</description>
    <namespace path="src">JoomlaBoy\Module\Hello</namespace>
    <files>
        <folder module="mod_hello">services</folder>
        <folder>src</folder>
    </files>
</extension>

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

عبارت "type="module به نصاب جوملا می گوید که نوع افزونه یک ماژول است (به جای یک کامپوننت، پلاگین یا هر چیز دیگری)

عبارت "client="site به نصاب جوملا می گوید که این ماژول مربوط به بخش کاربری یا front-end است، نه بخش مدیریت یا back-end.

عبارت "method="upgrade به نصاب جوملا م یگوید که این افزونه می تواند با نسخه جدید افزونه بروزرسانی شود. البته این مربوط به بخش های جلوتر این آموزش هست.

بعد از این بخش به تگ های XML موجود در فایل مانیفست میرسیم :

تگ <name> دربردارنده نام افزونه است.

تگ <version> شماره نسخه افزونه است که در هر بروز رسانی به این شماره افزوده می شود. معمولا این شماره بصورت اعشار می باشد.

تگ <author> نام مولف افزونه است.

تگ <authorEmail> ایمیل مولف افزونه است.

تگ <authorUrl> وبسایت مولف افزونه است.

تگ <creationDate> تاریخ ایجاد افزونه است که هم بصورت میلادی و هم بصورت شمسی می تواند باشد.

تگ <description> نیز توضیحاتی درباره افزونه در خود جای میدهد. نکته ایکه در مورد این تگ وجود دارد این است که محتوای این تگ توسط سیستم زبان جوملا قابل ترجمه است. در گامهای بعدی یاد خواهید گرفت که چطور افزونه هایتان را چند زبانه کنید.

هنگامی که ماژول نصب شد ، می توانید با مراجعه به Content / Site Modules و System / Manage / Extensions ، آنها را مشاهده کنید.

تگ <namespace> پیشوند فضا-نام یا name-space برای ماژول mod_hello ما است. در مستندات جوملا توصیه شده است که از namespace برای افزونه ها استفاده کنیم، و ما از JoomlaBoy به عنوان نام شرکت خود استفاده کرده ایم. برای اطلاع از مفهوم فضا-نام یا namespace کلیک کنید.

namespace یا فضا-نام در PHP یک مفهوم مهم برای سازماندهی و جلوگیری از تداخل نام‌ها در کلاس‌ها، توابع و ثابت‌ها است. در زیر به توضیح مختصر و جامعی از namespace می‌پردازیم:

چیستی namespace

namespace به شما امکان می‌دهد تا کلاس‌ها، توابع و ثابت‌هایی با نام یکسان داشته باشید بدون اینکه با یکدیگر تداخل کنند.

این ویژگی در PHP 5.3 معرفی شد و به برنامه‌نویسان کمک می‌کند تا کدهای خود را به‌صورت منظم و سازمان‌یافته بنویسند.

از آنجا که توسعه دهنده های زیادی برای جوملا افزونه می نویسند اینکار باعث کاهش تداخل افزونه های جوملا نیز می شود. زیرا چنانچه دو توسعه دهنده جوملا از فایلها، کلاس‌ها، توابع و ثابت‌هایی با نام مشابه ولی با کارکردی متفاوت استفاده کنند افزونه ها دچار تداخل نشوند. همچنین استفاده از namespace در جوملا باعث می شود که فایل های همنام در دایرکتوری متفاوت ذخیره شوند.

الگوی کلی استفاده از namespace در افزونه های جوملا بصورت زیر است:

<namespace path="src">YourCompany\ExtensionType\ExtensionName</namespace>

YourCompany نام تجاری توسعه دهنده است. ما از عبارت Joomlaboy که نام تجاری ما هست استفاده کرده ایم.

ExtensionType نوع افزونه ای است که داریم می نویسم. چون در حال نوشتن یک ماژول هستیم پس از عبارت Module را استفاده کرده ایم.

ExtensionName نام افزونه ما است. نام افزونه ما Hello است.

پس namespace ماژول ما بصورت زیر نوشته می شود:

<namespace path="src">JoomlaBoy\Module\Hello</namespace>

تگ <files> حاوی تمام فایل ها و فولدرهایی هست که برای نصب افزونه ضروری هستند. در مثال ما به نصاب می گوید کدام پوشه ها باید بخشی از کد ماژول در نظر گرفته شوند. ویژگی "module= "mod_hello به جوملا می گوید که در پوشه seveices جستجو کند تا یک فایل ارائه دهنده خدمات را که نقطه شروع mod_hello است پیدا کند . اگر پوشه هایی را در فهرست خود دارید که به صراحت در بخش <files> گنجانده نشده است ، نصاب جوملا آنها را نادیده می گیرد.

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

سپس پیشوند فضا-نام JoomlaBoy\Module\Hello\Site\ به این پوشه اشاره می کند ، و ما باید طبق توصیه جوملا کلاس های خود را تحت آن نامگذاری کنیم.

فایل ارائه دهنده خدمات

کد زیر را در 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('\\JoomlaBoy\\Module\\Hello'));
        $container->registerServiceProvider(new ModuleServiceProvider());
    }
};

اگر در توسعه جوملا تازه کار هستید ، احتمالاً این کد بسیار ترسناک به نظر می رسد. اگر چنین است، بهترین کار این است که آنرا فقط بپذیرید. این تنها کد BoilerPlate است که برای پیوند کد اصلی JOOMLA با افزونه ی mod_hello ما استفاده می شود. ما آن را در مرحله تزریق وابستگی  Dependency Injection آموزش توضیح خواهیم داد.

فایل دیسپچر

هنگامی که جوملا کد mod_hello ما را اجرا می کند ، با نمونه سازی کلاس دیسپچر ما و فراخوانی تابع dispatch() آن شروع می شود.

کد زیر را در mod_hello/src/Dispatcher/Dispatcher.php قرار دهید:

<?php

namespace JoomlaBoy\Module\Hello\Site\Dispatcher;

\defined('_JEXEC') or die;

use Joomla\CMS\Dispatcher\DispatcherInterface;

class Dispatcher implements DispatcherInterface

{

    public function dispatch()

    {

        echo '<h4>Hello</h4>';

    }

}

بررسی _JEXEC در ابتدا یک ویژگی امنیتی است. اگر شخصی وارد URL ای شود که مستقیماً به این فایل PHP می رسد، مفسر PHP شروع به اجرای کد می کند. به منظور جلوگیری از به دست آوردن اطلاعات توسط هکر در مورد کد موجود در فایل، این خط بررسی می کند که آیا ثابت "_jexec" تعریف شده است و در صورت عدم تعریف،خارج می شود. هنگامی که جوملا به طور عادی اجرا می شود ، این "_jexec" را تعریف می کند ، بنابراین وقتی جوملا ماژول شما را صدا می کند ، قبلاً تعریف شده است.

نصب افزونه

حالا در مدیریت فایل کامپیوتر از تمام فایل ها و پوشه هایی که ساختید فایل zip تهیه این افزونه را نصب و در موقعیت مورد نظرتان فعال کنید.