مرحله ۲: اضافه کردن فایل tmpl

مقدمه

در این مرحله یک فایل tmpl به ماژول اضافه می‌کنیم و مفهوم بازنویسی قالب (template overrides) در جوملا را معرفی می‌کنیم.

کد منبع در مرحله ۲ ماژول mod_hello موجود است

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

فایل tmpl و بازنویسی قالب‌ها

عبارت ساده قبلی خود که به این صورت بود:

echo "<h4>Hello</h4>"

را به شکل زیر تغییر می‌دهیم:

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;
class Dispatcher implements DispatcherInterface
{
    public function dispatch()
    {
        $hello = "Hello";

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

و در زیر شاخه‌ی `tmpl` فایل `default.php` را اضافه می‌کنیم:

mod_hello/tmpl/default.php

<?php
defined('_JEXEC') or die;
?>
<h4><?php echo $hello; ?></h4>

 این کار خیلی پیچیده‌تر از قبل شده است! چرا این‌طور انجام می‌دهیم؟ دلیل این است که این روش بازنویسی قالب‌ها را پشتیبانی می‌کند.

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

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

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

اگر روی mod_hello کلیک کنید، پیامی با این مضمون خواهید دید: 

"Override created in \templates\cassiopeia\html\mod_hello". 

در این مسیر یک نسخه از فایل default.php شما قرار گرفته، که می‌توانید با گسترش نمای فایل‌ها آن را مشاهده کنید.

بازنویسی قالب mod_hello

وقتی روی default.php کلیک کنید، می‌توانید فایل را ویرایش کنید و خروجی HTML را تغییر دهید. 

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

خط کد `ModuleHelper::getLayoutPath('mod_hello')` بررسی می‌کند که آیا فایل بازنویسی در مسیرهای ممکن در سیستم فایل جوملا وجود دارد یا نه، و تنها در صورتی که پیدا نشود، فایل `modules/mod_hello/tmpl/default.php` را بارگیری می‌کند.

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

فضای نام (Namespacing)

در اینجا همچنین از قابلیت فصای نام در PHP که جوملا استفاده می‌کند بهره برده‌ایم:

mod_hello/mod_hello.php

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

می‌توانید نحوه پیاده‌سازی فضای نام در جوملا را در بخش namespaces مطالعه کنید.

به‌خصوص، نگاشت نام کامل کلاس جوملا به فایل منبع به ما کمک می‌کند تا به سرعت منبع هر کلاس جوملا را پیدا کنیم. به عنوان مثال، کلاس \Joomla\CMS\Helper\ModuleHelper در مسیر `libraries/src/Helper/ModuleHelper.php` قرار دارد.

به‌روزرسانی فایل manifest

چون یک پوشه جدید به فایل‌های منبع اضافه کرده‌ایم، باید به نصب‌کننده جوملا بگوییم که آن را پردازش کند:

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.2</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>
        <folder>tmpl</folder>
    </files>
</extension>

نصب

وقتی تغییرات کد منبع را انجام دادید، پوشه mod_hello را زیپ کرده و نسخه به‌روزشده ماژول را مطابق توضیحات بخش قبلی نصب کنید. نیازی نیست دوباره وضعیت انتشار، مکان قالب یا تخصیص منو را تنظیم کنید؛ جوملا همان تنظیمات قبلی را استفاده می‌کند.

با بارگذاری مجدد یک صفحه سایت، باید همان نتیجه قبلی را ببینید، اما اکنون می‌توانید از پنل مدیریت برای ایجاد بازنویسی قالب استفاده کنید.

اما اگر بازنویسی قالب ساختید، یادتان باشد که آن را بعد از آزمایش حذف کنید؛ در غیر این صورت تغییرات بعدی در فایل tmpl این آموزش در سایت نشان داده نخواهند شد.