آموزش ساخت ماژول برای جوملا 3x

در این مقاله طریقه ساخت ماژول برای جوملا نسخه 3x آموزش داده می شود. برای اینکار یک ماژول ساده جوملا ساخته می شود و مراحل گام به گام شرح داده می شود. جوملا با استفاده از سه اپلیکیشن مختلف ساخته شده است:

  • اپلیکیشن نصب (مورد استفاده برای نصب جوملا)
  • اپلیکیشن مدیریت (مورد استفاده برای مدیریت محتوا)
  • اپلیکیشن عمومی (مورد استفاده برای نمایش محتوا)

برنامه نصب فقط یکبار استفاده می شود. مدیریت و عمومی به کرات استفاده می شود و استفاده از این دو اپلیکیشن به صورت کامپوننت و ماژول است. هر ماژول دارای یک نقطه ورودی منفرد در پوشه modules است. این ورودی را mod_modulename/modulename.php می نامند (پیشوند mod_ یک تریس تاریخی است و همیشه برای ماژول ها استفاده می شود).

راهنمای ساخت ماژول برای جوملا

ملزومات

برای استفاده از این راهنما به یک نسخه به روز جوملا 3x (به همراه PHP، MySQL، Apache و Microsoft II) نیاز دارید. ماژول ها افزونه های سبک و انعطاف پذیر هستند. ماژول برای نمایش قطعات کوچک اطلاعات در صفحه استفاده می شوند و معمولا از پیچیدگی کمتری برخوردار بوده و می توان آنها را در بین اجزای مختلف صفحه چید.

نمونه های زیادی از ماژول ها به صورت استاندارد با نصب جوملا نصب می شود از قبیل ماژول منو (menus)، آخرین اخبار (Latest News)، فرم ورود (Login form) و مانند این ها.

در این راهنما طریقه ایجاد ماژول ساده سلام به دنیا (Hello World module) آموزش داده می شود. در این راهنما ساختار پایه فایل های ماژول را می آموزیم. سپس ساختار پایه را بسط داده و می توانیم ماژول های پیچیده تری بنویسم.

ساختار فایل

در الگوی استاندارد نوشتن ماژول چهار فایل پایه وجود دارد که در تمامی ماژول ها دیده می شود:

  • فایل mod_helloworld.php: این فایل نقطه اصلی ورودی برای ماژول است. این فایل تمامی روتین های آغاز کننده ضروری را فراخوانی و اجرا می کند، روتین های کمکی را برای جمع آوری هر گونه داده ضروری فراخوانی می کند، و قالبی را شامل می شود که خروجی ماژول را نمایش می دهد.
  • فایل mod_helloworld.xml: این فایل حاوی اطلاعات مربوط به ماژول است. در این فایل سایر فایل های مورد نیاز که بایستی توسط نصاب جوملا نصب شوند را تعریف کرده و پارامترهای پیکربندی مخصوص ماژول را مشخص می کند.
  • فایل helper.php: این فایل حاوی کلاس های کمکی (helper class) است که برای انجام کار حقیقی بازیافت اطلاعاتی که باید در ماژول نمایش یابند، استفاده می شوند (معمولا اطلاعات را از بانک اطلاعاتی یا هر منبع دیگر بازیافت می کند).
  • فایل tmpl/default.php: این قالب یا تمپلیت ماژول است. این فایل داده های جمع آوری شده توسط mod_helloworld.php را گرفته و یک فایل HTML تولید می کند که بر روی وب پیج نمایش می یابد.

ایجاد فایل mod_helloworld.php

فایل mod_helloworld.php سه کار انجام می دهد:

  • فایل helper.php را درج می کند که شامل کلاس هایی است که برای جمع آوری داده های مورد نیاز و ضروری استفاده می شوند
  • متد کلاس های کمکی متناسب را اجرا می کند تا داده های مورد نیاز را بازیافت کنند
  • شامل قالبی است که خروجی ماژول را نمایش می دهد

کلاس هلپر یا کلاس کمکی در فایل helper.php تعریف می شود. این فایل شامل یک عبارت require_once است:

 require_once dirname(__FILE__) . '/helper.php'; 

عبارت require_once به این خاطر استفاده می شود که توابع کمکی (هلپر) در درون کلاس تعریف می شود و ما می خواهیم که هر کلاس فقط یکبار تعریف شود.

کلاس هلپر ما هنوز تعریف نشده است، اما وقتی تعریف شد، حاوی یک متد خواهد بود که ()getHello نامیده می شود. برای مثال پایه ما لازم نیست که اینکار انجام شود، پیغام "سلام دنیا" که این متد بر می گرداند را می توان به سادگی در قالب ماژول گنجاند. ما از کلاس هلپر در اینجا فقط برای نمایش تکنیک کار استفاده می کنیم.

در ماژول این مثال از پارامتر خاصی استفاده نمی شود، اما ما پارامترهایی به متد هلپر ارجاع می کنیم تا بعدا از آنها استفاده کنیم، اگر خواستیم عملکرد ماژول خود را بسط دهیم.

متد کلاس کمکی در این مثال به صورت زیر فراخوان و فعال می شود:

 $hello = modHelloWorldHelper::getHello($params); 

فایل mod_helloworld.php کامل

فایل تکمیل شده mod_helloworld.php به صورت زیر خواهد بود:

<?php
/**
 * Hello World! Module Entry Point
 * 
 * @package    Joomla.Tutorials
 * @subpackage Modules
 * @license    GNU/GPL, see LICENSE.php
 * @link       http://docs.joomla.org/J3.x:Creating_a_simple_module/Developing_a_Basic_Module
 * mod_helloworld is free software. This version may have been modified pursuant
 * to the GNU General Public License, and as distributed it includes or
 * is derivative of works licensed under the GNU General Public License or
 * other free or open source software licenses.
 */

// No direct access
defined('_JEXEC') or die;
// Include the syndicate functions only once
require_once dirname(__FILE__) . '/helper.php';

$hello = modHelloWorldHelper::getHello($params);
require JModuleHelper::getLayoutPath('mod_helloworld');

یک خط از این که قبلا شرح داده نشده است. این خط کد اطمینان حاصل می کند که این فایل از برنامه جوملا در اجرای ماژول گنجانده می شود. درج این فایل از اهمیت بالایی برخوردار است زیرا از تزریق متغیر به ماژول و سایر مشکلات امنیتی بالقوه پیشگیری می کند.

ایجاد فایل helper.php

فایل helper.php حاوی کلاس هلپر است که برای بازیافت داده هایی که به عنوان خروجی ماژول نمایش داده می شوند، استفاده می شود. همانطور که ذکر شد، کلاس هلپر ما دارای یک متد است: ()getHello. این متد پیام "سلام دنیا!" را بر می گرداند.

کد فایل helper.php به صورت زیر است:

<?php
/**
 * Helper class for Hello World! module
 * 
 * @package    Joomla.Tutorials
 * @subpackage Modules
 * @link http://docs.joomla.org/J3.x:Creating_a_simple_module/Developing_a_Basic_Module
 * @license        GNU/GPL, see LICENSE.php
 * mod_helloworld is free software. This version may have been modified pursuant
 * to the GNU General Public License, and as distributed it includes or
 * is derivative of works licensed under the GNU General Public License or
 * other free or open source software licenses.
 */
class ModHelloWorldHelper
{
    /**
     * Retrieves the hello message
     *
     * @param   array  $params An object containing the module parameters
     *
     * @access public
     */    
    public static function getHello($params)
    {
        return 'Hello, World!';
    }
}

قانونی وجود ندارد که ما بایستی حتما کلاس هلپر را به این شکل نامگذاری کنیم، اما انجام اینکار مفید است زیرا به سادگی می توانیم کلاس را شناسایی و تعیین کنیم. بخاطر داشته باشید که اگر می خواهید از پلاگین com_ajax استفاده کنید، قالب این متد بایستی به شکل بیان شده باشد.

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

ایجاد فایل tmpl/default.php

فایل default.php قالب یا تمپلیتی است که خروجی ماژول را نمایش می دهد. کد فایل به صورت زیر خواهد بود:

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

نکته مهمی که باید توجه داشت این است که فایل قالب دارای حوزه عملکردی مشابه با فایل mod_helloworld.php است. این بدین معنی است که متغیر $hello را می توان در فایل mod_helloworld.php تعریف کرد و سپس در فایل تمپلیت بدون هر گونه اعلان اضافه یا فراخوانی تابع استفاده نمود.

ایجاد فایل mod_helloworld.xml

فایل mod_helloworld.xml برای مشخص کردن فایل هایی که نصاب جوملا بایستی کپی کرده و توسط مدیریت ماژول جوملا برای تعیین پارامترهای مورد نیاز برای پیکربندی ماژول استفاده شود؛ بکار می رود. سایر اطلاعات مربوط به ماژول نیز در این فایل مشخص می شود.

کد فایل mod_helloworld.xml به صورت زیر خواهد بود:

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.1.0" client="site" method="upgrade">
    <name>Hello, World! </name>
    <author>John Doe</author>
    <version>1.0.0</version>
    <description>A simple Hello, World! module. </description>
    <files>
        <filename>mod_helloworld.xml</filename>
        <filename module="mod_helloworld">mod_helloworld.php</filename>
        <filename>index.html</filename>
        <filename>helper.php</filename>
        <filename>tmpl/default.php</filename>
        <filename>tmpl/index.html</filename>
    </files>
    <config>
    </config>
</extension>

فایل های مانیفست (Manifest files) جزئیات تکنیکی عناصر مورد استفاده در فایل XML را مشخص می کنند.

متوجه شده اید که دو فایل دیگر در این ساختار وجود دارد که هنوز معرفی نشده است: index.html و tmpl/index.html

این فایل ها به این خاطر در ساختار فایل ماژول گذاشته می شوند که دایرکتوری ماژول قابل جستجو نباشد و اگر کاربر به جستجوی فایل پرداخت، صفحه سفید نمایش داده شود اگر که فایل ها خالی باشند یا می توان یک خط ساده متن در آن گنجاند و یا برای فایل مانیفست ساختار سفارشی ایجاد کرد. کد رایج فایل مانیفست به صورت زیر است:

 <html><body bgcolor="#FFFFFF"></body></html>

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

خلاصه مطلب

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

اگر هنوز جوملا نصب نکرده اید، می توانید راهنمای گام به گام نصب جوملا را خوانده یا کتابچه تصویری نصب جوملا را دانلود کرده و مطالعه نمایید.