مرحله 7: افزودن جاوا اسکریپت

  • محمد علایی
  • منتشر شده در
  • زمان خواندن 3 دقیقه

مقدمه

در این مرحله، ما یک "!" به انتهای پیام خوش‌آمدگویی "Hello Username" اضافه می‌کنیم، اما این کار را با استفاده از جاوااسکریپت انجام می‌دهیم و علامت "!" را به‌عنوان یک متغیر از کد PHP ارسال می‌کنیم. این مرحله شامل موارد زیر است:

- چگونگی ارسال متغیرها از PHP به جاوااسکریپت 

- استفاده از Joomla Web Asset Manager برای مدیریت فایل جاوااسکریپت

کد منبع در پوشه mod_hello مرحله 7 موجود استhttps://github.com/joomla/manual-examples/tree/main/module-tutorial/step7_javascript

ارسال متغیرها به جاوااسکریپت

برای ارسال متغیرها از PHP به JS از تابع `Document::addScriptOptions` استفاده می‌کنیم:

 
$document = $this->app->getDocument();
$document->addScriptOptions('mod_hello.vars', array('suffix' => "!"));

شما می‌توانید شی Document (که مربوط به خروجی HTML است) را از طریق پارامتر Application که توسط جوملا به سازنده ماژول تزریق می‌شود بدست آورید (همان‌طور که در مرحله آموزشی قبل توضیح داده شد).

سپس در کد جاوااسکریپت می‌توانیم این متغیرها را با همان کلید "mod_hello.vars" دریافت کنیم:

 
const arr = Joomla.getOptions('mod_hello.vars');
console.log(arr);   // خروجی: Object { suffix: "!" }

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

روی عنصری که می‌خواهیم به‌روزرسانی کنیم کلاس HTML با نام "mod_hello" قرار می‌دهیم، پس کد جاوااسکریپت ما به صورت زیر است:

 
if (!window.Joomla) {
  throw new Error('Joomla API به درستی مقداردهی نشد');
}
const { suffix } = Joomla.getOptions('mod_hello.vars');
document.querySelectorAll('.mod_hello').forEach(element => {
  element.innerText += suffix;
});

مدیریت دارایی وب (Web Asset Manager)

اگر با Web Asset Manager آشنایی ندارید بهتر است بخش راهنمای مرتبط در مستندات جوملا را مطالعه کنید.

برای فایل کد جاوااسکریپت، یک دارایی در مسیر `mod_hello/media/joomla.asset.json` تعریف می‌کنیم، همان‌طور که در تعریف Web Asset Manager آمده است:

 
{
  "$schema": "https://developer.joomla.org/schemas/json-schema/web_assets.json",
  "name": "mod_hello",
  "version": "1.0.0",
  "description": "Joomla Module Tutorial",
  "license": "GPL-2.0-or-later",
  "assets": [
    {
      "name": "mod_hello.add-suffix",
      "type": "script",
      "uri": "mod_hello/add-suffix.js",
      "dependencies": [
        "core"
      ],
      "attributes": {
        "type": "module"
      },
      "version": "1.0.0"
    } 
  ]
}

در کد بالا از تابع `Joomla.getOptions` برای دریافت مقدار suffix استفاده شده که بخشی از کتابخانه جاوااسکریپت core.js در مسیر `media/system/js/core.js` است، بنابراین نیاز است "core" به‌عنوان وابستگی وارد شود.

Web Asset Manager به‌صورت خودکار فایل joomla.asset.json ماژول‌ها را نمی‌خواند، بنابراین باید این فایل را به ثبت برسانیم و سپس مشخص کنیم که می‌خواهیم از دارایی "mod_hello.add-suffix" استفاده کنیم تا فایل جاوااسکریپت ما در پاسخ HTTP قرار گیرد:

 
$document = $this->app->getDocument();
$wa = $document->getWebAssetManager();
$wa->getRegistry()->addExtensionRegistryFile('mod_hello');
$wa->useScript('mod_hello.add-suffix');

Web Asset Manager ترتیب بارگذاری برچسب‌های <script> در HTML را تنظیم می‌کند تا وابستگی "core" قبل از فایل add-suffix.js بارگذاری شود.

کد فوق می‌تواند در کد Dispatcher یا فایل tmpl قرار گیرد، اما در جوملا این رویه معمول است که چنین کدهایی در فایل tmpl قرار گیرد.

فایل tmpl به‌روزرسانی‌شده به شکل زیر است: 

mod_hello/tmpl/default.php

 
<?php
defined('_JEXEC') or die;
$document = $this->app->getDocument();
$wa = $document->getWebAssetManager();
$wa->getRegistry()->addExtensionRegistryFile('mod_hello');
$wa->useScript('mod_hello.add-suffix');
// ارسال suffix به جاوااسکریپت
$document->addScriptOptions('mod_hello.vars', array('suffix' => "!"));
$h = $params->get('header', 'h4');
$greeting = "<{$h} class='mod_hello'>{$hello}</{$h}>"
?>
<?php echo $greeting; ?>

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

برای اینکه نصب‌کننده جوملا پوشه رسانه (media) ما را شامل کند و فایل‌ها را زیر مسیر `/media/mod_hello` قرار دهد، باید فایل مانیفست `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.7</version>
    <author>me</author>
    <creationDate>today</creationDate>
    <description>MOD_HELLO_DESCRIPTION</description>
    <namespace path="src">My\Module\Hello</namespace>
    <files>
        <folder module="mod_hello">services</folder>
        <folder>src</folder>
        <folder>tmpl</folder>
        <folder>language</folder>
    </files>
    <scriptfile>script.php</scriptfile>
    <media destination="mod_hello" folder="media">
        <filename>joomla.asset.json</filename>
        <folder>js</folder>
    </media>
    <config>
        <fields name="params">
            <fieldset name="basic">
                <field
                    name="header"
                    type="list"
                    label="MOD_HELLO_HEADER_LEVEL"
                    default="h4"
                    >
                    <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>

نکات مهم:

- تمام فایل‌های js و css باید زیر پوشه `/media` جوملا ذخیره شوند، در یک زیرپوشه‌ای که نامش با نام افزونه‌ی شما یکسان است. 

- بنابراین فایل js ما در مسیر `/media/mod_hello/js/add-suffix.js` قرار می‌گیرد.

بعد از اینکه ماژول به‌روزشده را فشرده (zip) و نصب کردید، باید در صفحه سایت پیام mod_hello همراه با علامت "!" در انتها نمایش داده شود.

افزودن CSS

می‌توانید به‌صورت مشابه از Web Asset Manager برای افزودن فایل‌های CSS استفاده کنید. فرض کنید یک فایل به نام `example.css` دارید، مراحل کار به شرح زیر است:

1. فایل CSS را در مسیر `mod_hello/media/css/example.css` ذخیره کنید. 

2. یک دارایی استایل (style asset) در همان فایل `mod_hello/media/joomla.asset.json` اضافه کنید:

 
{
  "name": "mod_hello.example",
  "type": "style",
  "uri": "mod_hello/example.css",
  "version": "1.0.0"
}

(همانند جاوااسکریپت، در مقدار `uri` زیرپوشه `css` نیامده است.)

3. در کد PHP می‌توانید استایل را به این صورت بارگذاری کنید:

 
$wa->useStyle('mod_hello.example');