گام دوم - افزودن فایل قالب به ماژول

در این مرحله ما یک فایل tmpl را به ماژول اضافه می کنیم و مفهوم ویرایش قالب یا template overrides در جوملا را معرفی می کنیم.

template overrides در جوملا یک قابلیت قدرتمند برای شخصی‌سازی و تطبیق ظاهر سایت با نیازهای خاص است. این ویژگی به کاربران و توسعه‌دهندگان اجازه می‌دهد تا بدون تغییر در کد اصلی ماژول  ها یا کامپوننت‌ها، ظاهر آنها را تغییر دهند. در این روش، یک نسخه کپی از فایل‌های چیدمان (layout) اصلی ایجاد می‌شود و در پوشه قالب قرار می‌گیرد. جوملا از این فایل‌های کپی شده استفاده می‌کند تا ظاهر سایت را مطابق با طراحی دلخواه تغییر دهد.

مزایای استفاده از template overrides:

• حفظ تغییرات در بروزرسانی‌ها: با استفاده از override، تغییرات شما در بروزرسانی‌های بعدی از بین نمی‌رود.
• امنیت بیشتر: این روش به شما امکان می‌دهد تا افزونه‌ها را بروزرسانی کنید بدون اینکه تغییرات ظاهری از بین برود.
• کنترل بیشتر بر روی طراحی: override به شما امکان می‌دهد تا ظاهر هر کامپوننت، ماژول یا پلاگین را به صورت جداگانه تغییر دهید.

موارد استفاده از template overrides:

• تغییر ظاهر کامپوننت‌ها و ماژول‌ها
• جایگزینی لینک‌ها و اقدامات فرم
• رفع مشکلات طراحی با ساختار HTML بهتر
• تست A/B برای طرح‌های مختلف.

حالا که در مورد قابلیت ویرایش قالب یا template overrides در جوملا توضیح دادیم نوبت آن است که این امکان را به ماژول مان اضافه کنیم.

اضافه کردن زیر پوشه tmpl

در اولین گام ما یک پوشه جدید را در مجموعه فایل های منبع خود به نام tmpl اضافه می کنیم.

mod_hello
│   mod_hello.xml
│   
├───services
│       provider.php
│       
├───src
│   └───Dispatcher
│           Dispatcher.php
│           
└───tmpl
        default.php

باید به نصاب جوملا بگوییم تا آن را هنگام نصب نسخه جدید ماژول در نظر بگیرد. بنابراین فایل mod_hello.xml  را بصورت زیر ویرایش می کنیم:

<?xml version="1.0" encoding="UTF-8"?>
<extension type="module" client="site" method="upgrade">
    <name>Joomla module tutorial</name>
    <version>5.2.0</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>
        <folder>tmpl</folder>
    </files>
</extension>   

<?php
defined('_JEXEC') or die;

?>

<h4><?php echo $hello; ?></h4>

و در مسیر mod_hello/src/Dispatcher/Dispatcher.php عبارت ساده

echo "<h4>Hello</h4>";

را به صورت زیر تغییر می دهیم:

<?php

namespace Joomlaboy\Module\Hello\Site\Dispatcher;

\defined('_JEXEC') or die;

use Joomla\CMS\Dispatcher\DispatcherInterface;
use Joomla\CMS\Helper\ModuleHelper;

class Dispatcher implements DispatcherInterface
{
    public function dispatch()
    {
        $hello = "Hello";

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

توضیحات تکمیلی

در مسیر mod_hello/mod_hello.php ما همچنین در اینجا از این واقعیت استفاده کرده ایم که کد جوملا از فضا-نام PHP استفاده می کند:

use Joomla\CMS\Helper\ModuleHelper;
...
require ModuleHelper::getLayoutPath('mod_hello');

به ویژه "نقشه برداری از نام کاملاً واجد شرایط جوملا به فایل منبع" ما را قادر می سازد به سرعت منبع هر کلاس جوملا را پیدا کنیم. به عنوان مثال \Joomla\CMS\Helper\ModuleHelper در libraries/src/Helper/ModuleHelper.php یافت می شود.

توجه داشته باشید که تابع getLayoutPath مسیر فایل default.php را برمی گرداند ، و کد ما فایل default.php را از طریق تابع require فراخوانی می کند، یعنی محتویات 
فایل default.php در داخل فایل mod_hello.php قرار میگیرد. این بدان معنی است که هر متغیر PHP که در mod_hello.php بنویسید در tmpl/default.php نیز در دسترس است.

چرا لقمه را دور سرمان می چرخانیم

این کار، توسعه ماژول را بسیار پیچیده تر از گذشته می کند! پس چرا این کار را انجام می دهیم؟ پاسخ این است که با اینکار می توانیم از امکان ویرایش قالب یا template overrides استفاده کنیم.

هنگامی که جوملا HTML را به این شکل خروجی می‌دهد، PHP را به شکل یک فایل tmpl جدا می‌کند که مسئول بازتاب عناصر HTML است. سپس این امکان را برای مدیران یا توسعه دهندگان وب سایت فراهم می کند تا شکل HTML خروجی را تغییر دهند.

به عنوان مثال ، در مورد mod_hello یک مدیر ممکن است خروجی HTML را برای استفاده از برچسب های <h3> به جای <h4> ترجیح دهد.

نصب و تست

پس از نصب این نسخه از mod_hello ، (با فرض اینکه از قالب پیش فرض جوملا استفاده می کنید) می توانید به System / Site Templates بروید و سپس روی Cassiopeia Details and Files کلیک کنید. سپس می توانید بر روی برگه Create Overrides کلیک کنید و باید mod_hello را در لیست ماژول ها پیدا کنید.

چنانچه بر روی mod_hello کلیک کنید و باید پیامی دریافت کنید: "Override created in \templates\cassiopeia\html\mod_hello".

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

همانطور که در تصویر بالا می بینید، کدساده:

<h4><?php echo $hello; ?></h4>

به صورت زیر ویرایش کردیم:

<h3 class="bg-danger"><?php echo $hello; ?></h3>

یعنی هم از تگ h3 و هم از کلاس css بوت استاپ که بصورت پیشفرض در قالب cassiopeia وجود دارد استفاده کرده ایم. وقتی تغییرات را ذخیره کنید نحوه نمایش خروجی ماژول شما به شکل زیر در خواهد آمد: