نسخهٔ ‏۳۱ ژانویهٔ ۲۰۱۲، ساعت ۰۵:۳۲

ماژول Hello World

یک ماژول جوملا1.5 در حالت عادی معمولا شامل 2 فایل می باشد . یک فایل شامل تنظیمات XML ویک فایل کنترل کننده PHP . فایل تنظیمات XML شامل اطلاعات عمومی ماژول می باشد اگر ماژول دارای پارامترهایی باشد که یک عملکرد یا یک مدل نمایش خاص را برای ماژول ارائه کند در قسمت پارامترهای ماژول نمایش داده می شود (که در قسمت مدیریت ماژول ها در مدیریت جوملا نمایش داده میشوند) .
فایل PHP وظیفه کنترل منطق برنامه و کارایی ماژول جوملا را برعهده دارد .
به عنوان مثال برای ایجاد یک ماژول ساده Hello World باید موارد زیر را انجام دهیم :
ابتدا باید یک پوشه در داخل پوشه ماژول ها (modules در فولدر ریشه جوملا ) ایجاد کنیم . نام این پوشه را 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 در آدرس

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

Hello World

</source> وقتی این ماژول در جوملا اجرا چه اتفاقی می افتد ؟ پیغام Hello World در صفحه نمایش ظاهر میشود . این ساده ترین شکل ایجاد یک ماژول جوملا است .
در آخر نیز میتوانیم یک صفحه html ایجاد کنیم

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

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

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

نیازمندیها

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

تفاوتها

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

ما 2 هدف را به منظور اضافه کردن این فایلها دنبال میکنیم
هدف اول : جدا کردن منطق برنامه از نحوه نمایش خروجی
هدف دوم : باز نویسی (خطا گیری , توسعه و ...) آن براحتی انجام میپذیرد
بنابراین در فایل

خواهیم داشت :
<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 کنیم و داده های آماده ای که میخواهند نمایش داده شوند و باید با یک قالب به خروجی ارسال شود .

<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 در جوملا

<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 است.

<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 بازگردانده میشود را به نمایش درآورد.

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

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

اینک ما باید یک بسته zip از پوشه mod_hello_world2 تهیه کنیم به نام mod_hello_world2.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
جمع آوری و ترجمه: شهاب مطاع پور

استفاده از مطالب دانشنامه جوملا فارسی - مامبو فارسی با ذکر منبع ( دانشنامه جوملا فارسی ) و لینک مستقیم به http://docs.joomlafarsi.com بلامانع است.