ایجاد یک ماژول جوملا   

از دانشنامه جوملا فارسی - مامبو فارسی
پرش به: ناوبری، جستجو

ماژول Hello World

یک ماژول جوملا 1.5 در حالت عادی معمولا شامل 2 فایل می‌باشد . یک فایل شامل تنظیمات XML ویک فایل کنترل کننده PHP. فایل تنظیمات XML شامل اطلاعات عمومی ماژول می‌باشد اگر ماژول دارای پارامترهایی باشد که یک عملکرد یا یک مدل نمایش خاص را برای ماژول ارائه کند در قسمت پارامترهای ماژول نمایش داده می‌شود (که در قسمت مدیریت ماژول‌ها در مدیریت جوملا نمایش داده می‌شوند) .

فایل PHP وظیفه کنترل منطق برنامه و کارایی ماژول جوملا را برعهده دارد.

به عنوان مثال برای ایجاد یک ماژول ساده Hello World باید موارد زیر را انجام دهیم:

ابتدا باید یک پوشه در داخل پوشه ماژول‌ها (modules در فولدر ریشه جوملا) ایجاد کنیم. نام این پوشه را mod_hello_world می‌گذاریم این نحوه نام گذاری و این نام حائز اهمیت است.

پس از ایجاد پوشه مورد نظر اقدام به ایجاد فایل XML نماییم، این فایل را در پوشه
/modules/mod_hello_world/mod_hello_world.xml
ایجاد می‌کنیم. دقت کنید که نحوه نام گذاری این فایل XML هم حائز اهمیت است.

نکته: این نکته بسیار مهم است که نام فایل XML و نام ماژول یکی باشند در غیر اینصورت نصب کننده جوملا قادر به نصب بسته ماژول نخواهد بود.

قوانین نامگذاری پوشه‌ها برای ایجاد ماژول:

  • تمامی پوشه‌ها باید با نام mod_ آغاز شوند
  • قسمت دوم نام تمام ماژول‌ها باید بانام فایل XML یکی باشد.


<source lang="xml" > <?xml version="1.0" encoding="utf-8"?> <install type="module" version="1.5.0"> <name>Hello World - Hello</name>

<author>Shahab Matapour</author>

<creationDate>2011-06-23</creationDate>

<copyright>All rights reserved by Sh Matapour 2011.</copyright>

<license>GPL 2.0</license>

<authorEmail>[email protected]</authorEmail>

<authorUrl>www.studio-design.co</authorUrl>

<version>1.0.0</version>

<description>Provides a basic "Hello World" notice</description>

<files> <filename module="mod_hello_world">mod_hello_world.php</filename> <filename>index.html</filename> </files>

<params /> </install>

</source>


این دستورات XML صرفا برای معرفی نویسنده ماژول و تاریخ ایجاد و ... نیست بلکه برای شناسایی به نصب کننده جوملا می‌گوید کدام فایل‌ها باید در جوملا کپی شوند و ایجاد بخش پارامترهای ماژول که از قسمت مدیریت ماژول‌ها (از مدیریت جوملا) مورد دسترسی و مدیریت قرار می‌گیرد، وظیفه تمامی اینکارها به عهده این فایل XML است.

توجه کنید به چه صورت برای تک تک فایل‌ها یک reference ایجاد کردیم.

نکته: در بخش معرفی فایل‌ها ما به هیچ عنوان نباید برای فایل XML مان یک reference ایجاد کنیم.

ایجاد فایل PHP در آدرس
/modules/mod_hello_world/mod_hello_world.php


<source lang="php " > <?php //این خط برای تضمین امنیت در جوملا است. defined('_JEXEC') or die('Direct Access to this location is not allowed.'); ?>

Hello World

</source>


وقتی این ماژول در جوملا اجرا می‌شود، چه اتفاقی می‌افتد؟

پیغام Hello World در صفحه نمایش ظاهر می‌شود.

این ساده ترین شکل ایجاد یک ماژول جوملا است.

در آخر نیز می‌توانیم یک صفحه HTML ایجاد کنیم.

/modules/mod_hello_world/index.html

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

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

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

حالت واقعی ماژول‌های جوملا

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

برای ایجاد ماژول‌های پیچیده تر ما نیاز داریم که از قبل با الگوی MVC) Model View Controller) آشنا باشیم . نام این ماژول را Hello World 2 می‌گذاریم و در آن معماری لایه بندی 3 لایه MVC را رعایت می‌کنیم.

نیازمندی‌ها

برای ایجاد این ماژول‌ ما به فایل‌ها و فولدرهای زیر نیاز داریم:

/modules/mod_hello_world2/index.html

/modules/mod_hello_world2/mod_hello_world2.php

/modules/mod_hello_world2/mod_hello_world2.xml

/modules/mod_hello_world2/helper.php

/modules/mod_hello_world2/en-GB.mod_hello_world2.ini

/modules/mod_hello_world2/tmpl/index.html

/modules/mod_hello_world2/tmpl/default.php

تفاوت‌ها

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

این فایل‌ها عبارتند از:

helper.php , tmpl/default.php , en-GB.mod_hello_world2.ini

ما 2 هدف را به منظور اضافه کردن این فایل‌ها دنبال می‌کنیم .

هدف اول: جدا کردن منطق برنامه از نحوه نمایش خروجی.

هدف دوم: باز نویسی (خطا گیری , توسعه و ...) آن براحتی انجام می‌پذیرد.

بنابراین در فایل

/modules/mod_hello_world2/mod_hello_world2.php

خواهیم داشت:


<source lang="php " > <?php //برای جلوگیری از دسترسی مستقیم و غیر مجاز defined('_JEXEC') or die('Direct Access to this location is not allowed.');

// include the helper file require_once(dirname(__FILE__).DS.'helper.php');

// گرفتن پارامتر از تنظیمات ماژول $userCount = $params->get('usercount');

// گرفتن آیتم از هلپر برای نمایش $items = ModHelloWorld2Helper::getItems($userCount);

// include the template for display require(JModuleHelper::getLayoutPath('mod_hello_world2')); ?> </source>


این موضوع که تفاوت این قسمت را با ماژول قبلی متوجه شویم خیلی مهم است . درواقع وقتی که تصمیم گرفته‌ایم برروی منطق افزونه و قابلیت‌های آن کارکنیم باید فایل helper را include کنیم و داده‌های آماده‌ای که می‌خواهند نمایش داده شوند و باید با یک قالب به خروجی ارسال شود.

/modules/mod_hello_world2/mod_hello_world2.xml

<source lang="xml" > <?xml version="1.0" encoding="utf-8"?> <install type="module" version="1.5.0"> <name>Hello World 2 - Hello</name>

<author>Shahab Matapour</author>

<creationDate>2010-06-23</creationDate>

<copyright>All rights reserved by Shahab Matapour 2011.</copyright>

<license>GPL 2.0</license>

<authorEmail>[email protected]</authorEmail>

<authorUrl>www.studio-design.co</authorUrl>

<version>1.0.0</version>

<description>Provides a random listing of registered users</description>

<files> <filename module="mod_hello_world2">mod_hello_world2.php</filename> <filename>index.html</filename> <filename>helper.php</filename> <filename>tmpl/default.php</filename> <filename>tmpl/index.html</filename> </files>

   <languages>
       <!—فایل‌های مربوط زبان‌هایی که این ماژول پشتیبانی می‌کند -->
       <language tag="en-GB">en-GB.mod_hello_world2.ini</language>
   </languages>

<params> <param name="moduleclass_sfx" type="text" default="" label="Module Class Suffix" description="PARAMMODULECLASSSUFFIX" />

<param name="@spacer" type="spacer" default="" label="" description="" />

       <param name="usercount" type="text" default="5" label="LABEL USER COUNT" description="DESC USER COUNT" />
   </params>

</install> </source>


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

اتصال به Database در جوملا

/modules/mod_hello_world2/helper.php


<source lang="php " > <?php defined('_JEXEC') or die('Direct Access to this location is not allowed.');

class ModHelloWorld2Helper {

   /**
    * بازگرداندن لیست آیتمها
   */
   public function getItems($userCount)
   {
       // ایجاد یک کانکشن به بانک اطلاعاتی در جوملا
       $db = &JFactory::getDBO();

       // نحوه نگارش کوئری در جوملا 
       $query = 'SELECT a.name FROM `#__users` AS a ORDER BY rand() LIMIT ' . $userCount  . ;
	// اجرای کوئری در جوملا 
       $db->setQuery($query);
       $items = ($items = $db->loadObjectList())?$items:array();

       return $items;
   } 

} ?> </source>


در این فایل helper ما سعی کردیم با بانک اطلاعاتی ارتباط برقرار کنیم و یک کوئری نیز اجرا کنیم این یک نمونه آموزشی و الگوی ارتباط با دیتابیس در جوملا 1.5 است.

/modules/mod_hello_world2/tmpl/default.php


<source lang="php " > <?php defined('_JEXEC') or die('Restricted access'); // no direct access ?> <?php echo JText::_('RANDOM USERS'); ?>

    <?php foreach ($items as $item) { ?>
  • <?php echo JText::sprintf('USER LABEL', $item->name); ?>
  •    <?php } ?>
    

</source>


در این فایل ما یک HTML نامرتب (فعلا بدون استایل) ایجاد کردیم در این فایل حلقه‌ای وجود دارد که باعث می‌شود تمام itemsهاییکه از helper بازگردانده می‌شود را به نمایش درآورد.

/modules/mod_hello_world2/en-GB.mod_hello_world2.ini

LABEL USER COUNT=User Count DESC USER COUNT=The number of users to display RANDOM USERS=Random Users for Hello World2 USER LABEL=%s is a randomly selected user

در این قسمت ما فایل‌های ترجمه انگلیسی ماژول را نوشته‌ایم. در واقع دستورات JText::_ یا JText::sprintfاین امکان را فراهم می‌سازد تا بدون تغییر در HTML براحتی بتوانیم یک ترجمه برای ماژول اضافه کنیم.

ایجاد یک package نصبی از ماژول

اینک ما باید یک بسته zip از پوشه mod_hello_world2 تهیه کنیم به نام mod_hello_world2.zip .

نکته: این فایل zip همان بسته نصبی ما خواهد بود .

در این مرحله می‌توانیم از مدیریت جوملا اقدام به نصب این ماژول کنیم. بعد از نصب این ماژول فایل en-GB.mod_hello_world2.ini در language/en-GB/en-GB.mod_hello_world2.ini قرار می‌گیرد و بقیه فایل‌ها در modules/mod_hello_world2 قرار می‌گیرند. این عمل توسط installer جوملا انجام می‌شود.



منبع : http://docs.joomla.org/Creating_a_simple_module

جمع آوری و ترجمه: شهاب مطاع پور

Indent support.png
هر گونه سوال و یا مشکلی در این رابطه دارید، می‌توانید در انجمن تخصصی تیم جوملا فارسی جستجو کرده و در صورت عدم دریافت نتیجه مورد نظر، سوال جدیدی را مطرح کنید.
8.pngاستفاده از مطالب دانشنامه جوملا فارسی - مامبو فارسی با ذکر منبع ( دانشنامه جوملا فارسی ) و لینک مستقیم به http://docs.joomlafarsi.com بلامانع است.