آموزش ساخت کامپوننت (افزونه) برای جوملا قسمت (1)

[k2-4u]

جوملا 1.5 دارایه یک فریم ورک قویه که کل اسکریپت با این فریم ورک کار می کنه .

در جوملا از معماری MVC استفاده شده (Model-View-Controller) . این آموزش هم بر مبنای معماری MVC هستش

معماری MVC در جوملا به وسیله 3 کلاس JModel , JView و JController. فریم ورک جوملا انجام میشه .

.
.و..

که برای اطلاعات بیشتر می تونین به رفرنس سایت جوملا مراجعه کنید

برای ساخت یک کامپوننت ساده ما به 5 فایل زیر نیاز داریم

فایل سمپل مورد نیاز برای آموزش را از اینجا دانلود کنید

site/hello.php : نقطه شروع کامپوننت از این فایل

site/controller.php : این فایل هم حاوی کنترلر اصلی ماست (کنترلر MVC )

site/views/hello/view.html.php : این فایل اطلاعات لازم رو دریافت میکنه و داخل template میریزه

site/views/hello/tmpl/default.php : این هم فایل template برای خروجی

hello.xml : این فایل هم شامل اطلاعاتی در مورد کامپوننت هستش که جوملا از این فایل برای نصب کامپوننتمون استفاده می کنه .



به این نکته توجه کنید . فایلی که برای شروع کامپوننت استفاده می کنید (در اینجا hello.php ) هم اسم نام

خود کامپوننت است .برای مثال اگر شما نام کامپوننت رو salam khobi pesaram بزارین

باید نام فایل hello.php و hello.xml به ترتیب salamkhobipesaram.php و

salamkhobipesaram.xml باشه و نام فولدر کامپوننت هم com_salamkhobipesaram

در غیر این صورت کامپوننت شما کار نخواهد کرد .

نکته : از کارکتر Underline (_) در نام کامپوننت و فایل ها استفاده نکنید .

برای اطلا ع از سیستم نام گذاری در جوملا به این آدرس مراجعه کنید

http://docs.joomla.org/Naming_conventions





نقطه شروع کامپوننت (در اینجا فایل hello.php )

جوملا همیشه از یک راه اجازه دسترسی شما به فایل های کامپوننت رو میده و اونم index.php

است و برای قسمت مدیریت هم index.php داخل فوادر administrator . کامپوننت مورد نظر

به صورت زیر قابل دسترسه

index.php?option=com_hello&view=hello
hello نام کامپوننت مورد نظر است و البته اگر آدرس رو به صورت زیر بزنید

index.php?option=com_hello
باز هم همون صفحه باز میشه (چون به صورت پیشفرض view=hello است مگر اینکه مقدار دیگه ای بهش بدین)

این آدرس در حقیقت باعث باز شدن فایل components/com_hello/hello.php میشود

که فایل اصلی ما برای شروع است . محتویات فایل hello.php به صورت زیر است

<?php
/**
 * @package    Joomla.Tutorials
 * @subpackage Components
 * components/com_hello/hello.php
 * @link http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_1
 * @license    GNU/GPL
*/

// No direct access
defined( '_JEXEC' ) or die( 'Restricted access' );

// Require the base controller

require_once( JPATH_COMPONENT.DS.'controller.php' );

// Require specific controller if requested
if($controller = JRequest::getWord('controller')) {
    $path = JPATH_COMPONENT.DS.'controllers'.DS.$controller.'.php';
    if (file_exists($path)) {
        require_once $path;
    } else {
        $controller = '';
    }
}

// Create the controller
$classname    = 'HelloController'.$controller;
$controller   = new $classname( );

// Perform the Request task
$controller->execute( JRequest::getWord( 'task' ) );

// Redirect if set by the controller
$controller->redirect();

خط 12 : مربوط به امنیت میشه و از اجرای فایل به صورت مستقیم از آدرس جلوگیری می کنه

خط 17 : JPATH_COMPONENT این ثابت حاوی آدرس مطلق کامپوننت فعلی است در این مثال

اینو "components/com_hello" بر می گر دونه . برای دسترسی به آدرس فولدر کامپوننت سایت و مدیریت

به ترتیب از ثابت JPATH_COMPONENT_SITE و JPATH_COMPONENT_ADMINISTRATOR

استفاده کنید که در این مثال مقدارشون "components/com_hello

و "administrator/components/com_hello" است

ثابت DS که در خط 22 استفاده شده جدا کننده فولدراست که معمولا slash (/) یا backslash (\) و به

سیستم عامل سرور بستگی داره

بعد از load شدن فایل کنترلر اصلی ( controller.php خط 17) در خط 21 در صورت نیاز به کنترل خاص دیگه

اونو load می کنه متد JRequest::getWord() به دنبال یک متغییر GET یا POST به نام controller

میگرده که در صورتی که وجود داشته باشه حاوی نام کنترل خاص مورد نظره . برای مثال اگر آدرس

index.php?option=com_hello&controller=controller_name باز بشه

مقدار این متد برابر میشه با controller_name و در نتیجه در خط 24 فایل این کنترلر load میشه

یعنی در اینجا میشه فایل "components/com_hello/controllers/controller_name.php"

در خط 33 شئ کلاس کنترلر که فایلش در خط 17 و یا خط 24 load شد ، ساخته میشه

اسم کلاس کنترل اصلی ما helloController است که در فایل com_hello/controller.php قرار داره

برای کنترلری به غیر از کنترلر اصلی نام کلاس به این صورت میشه {نام کنترلر}{Controller}{نام کامپوننت}

(ما در بالا نام کنترلر را controller_name مثال زدیم ) و آدرس فایلش به این صورت

php.{نام کنترلر}/controllers/{نام کامپوننت}_com است . و کنترل اصلی هم نام کلاسش به این صورت

{Controller}{نام کامپوننت} و آدرس فایلش controller.php/{نام کامپوننت}_com به این صورت

است .



بعد از اجرا شدن کلاس کنترلر . در خط 37 . متد execute این کلاس task مورد نظر رو از GET یا POST گرفته

و اجرا می کنه . برای مثال اگر آدرس index.php?option=com_hello&task=sometask

باز کنیم task ی با نام sometask اجرا میشه . در صورتی که task انتخاب نشه به صورت پیشفرض

'display' در نظر گرفته میشه و وقتی این task اجرا بشه شما رو به قسمت 'view' هدایت می کنه

تا مشخص بشه چه صفحه ای نمایش داده بشه . برای مثال task ها میتونن save , edit , new و ...

باشن.

بعضی وقت ها کنترلر نیاز داره که بعد از اجرای task های مثل save . صفحه رو به آدرس دیگه منتقل یا

redirect کنه برای همین از متد redirect() در خط 41 استفاده شده

نکته مهم : در جوملا 5.1 آخر فایل ها رو با تک php نبندین ! و بگذارید باز باشه



ساخت یک Controller

این کنترلر یک نمونه خیلی سادست که یک task داره و اونم کارش نمایش hello word! معروفه ! .

ما اینجا فقط یک متد به نام ()display داریم که این متد باید حتما با همین نام در کلاس کنترلر ما باشه

. کد زیر مربوط به کنترلر اصلی کامپوننت ما به آدرس com_hello/controller.php است

<?php
/**
 * @package    Joomla.Tutorials
 * @subpackage Components
 * @link http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_1
 * @license    GNU/GPL
 */

// No direct access

defined( '_JEXEC' ) or die( 'Restricted access' );

jimport('joomla.application.component.controller');

/**
 * Hello World Component Controller
 *
 * @package    Joomla.Tutorials
 * @subpackage Components
 */
class HelloController extends JController
{
    /**
     * Method to display the view
     *
     * @access    public
     */
    function display()
    {
        parent::display();
    }

}

سازنده کلاس JController جوملا همیشه متد ()display رو به عنوان task پیشفرض ریجستر می کنه

مگر اینکه تغییرش بدین ( به وسیله متد () registerDefaultTask ) .

متد ()display در واقع کاربردی نداره ! چون همیشه متد پدر رو اجرا می کنه . اما این یک مثال عملی خیلی

خوبه تا به ما کمک کنه بفهمیم داخل کنترلر چی میگذره

کار متد ()JController::display تعیین کردن view و layout به وسیله درخواستی که از صفحه

دریافت می کنه و اجرا کردن view و layout مورد نظره . کامپوننت ما در اینجا یک view و یک

layout (منظور از layout همون template خودمونه ) داره





ساخت یک view

taskی که برای view استفاده میشه بسیار ساده است : ابتدا اطلاعات رو برای نمایش دریافت می کنه

سپس اونا رو به template یا layout میفرسته . اطلاعات به وسیله متد JView::assignRef

به template فرستاده میشه . کد زیر فایل com_hello/views/hello/view.html.php

است .

<?php
/**
 * @package    Joomla.Tutorials
 * @subpackage Components
 * @link http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_1
 * @license    GNU/GPL
*/

// no direct access

defined( '_JEXEC' ) or die( 'Restricted access' );

jimport( 'joomla.application.component.view');

/**
 * HTML View class for the HelloWorld Component
 *
 * @package    HelloWorld
 */

class HelloViewHello extends JView
{
    function display($tpl = null)
    {
        $greeting = "Hello World!";
        $this->assignRef( 'greeting', $greeting );

        parent::display($tpl);
    }
}
{/code}
 
ساخت یک templateفایل های template/layout جوملا .   فایل معمولی php  هستند  . متغییر های که به وسیله JView::assignRef   به این فایل ها ارسال می شود به این صورت در template قابل درسترس هستند  {نام}<-this$ یک مثال ساده برای نمایش متغییر greeting  در زیر {code type=php}

<?php

// No direct access

defined('_JEXEC') or die('Restricted access'); ?>
<h1><?php echo $this->greeting; ?></h1>

فایل معرف کامپوننت برای نصب - hello.xmlشما می تونین فایل های کامپوننت رو از طریق FTP کپی کنید و تغییرات دیتابیس هم دستی از طریق phpmyadmin انجام بدین . اما این روش برای تبدیل کردن کامپوننت به یک فایل zip است که از طریق مدیریت خود جوملا قابل نصبه این فایل حاوی : 1-توضیحات پایه در مورد کامپوننت (مثل نام کامپوننت ) , و اطلاعات دلخواهی مثل کپی رایت لالسنس و ... 2- لیست کامل فایل ها و فولدر های کامپوننت که باید کپی شوند 3- ممکن است کامپوننت شما نیاز به install/uninstall فایل sql داشته باشه که در اینجا می تونین این فایل ها رو برای اجرا لیست کنید 4- دستوراتی که هنگام install/uninstall کامپوننت نیاز به اجراشون دارین این هم یک مثال {code

<?xml version="1.0" encoding="utf-8"?>
<install type="component" version="1.5.0">
 <name>Hello</name>
 <!-- The following elements are optional and free of formatting constraints -->
 <creationDate>2007-02-22</creationDate>
 <author>John Doe</author>
 <authorEmail>[email protected]</authorEmail>
 <authorUrl>http://www.example.org</authorUrl>
 <copyright>Copyright Info</copyright>
 <license>License Info</license>
 <!--  The version string is recorded in the components table -->
 <version>1.01</version>
 <!-- The description is optional and defaults to the name -->
 <description>Description of the component ...</description>

 <!-- Site Main File Copy Section -->
 <!-- Note the folder attribute: This attribute describes the folder
      to copy FROM in the package to install therefore files copied
      in this section are copied from /site/ in the package -->
 <files folder="site">
  <filename>controller.php</filename>
  <filename>hello.php</filename>
  <filename>index.html</filename>
  <filename>views/index.html</filename>
  <filename>views/hello/index.html</filename>
  <filename>views/hello/view.html.php</filename>
  <filename>views/hello/tmpl/default.php</filename>
  <filename>views/hello/tmpl/index.html</filename>
 </files>

 <administration>
  <!-- Administration Menu Section -->
  <menu>Hello World!</menu>

  <!-- Administration Main File Copy Section -->
  <files folder="admin">
   <filename>hello.php</filename>
   <filename>index.html</filename>
  </files>

 </administration>
</install>

منبع : http://docs.joomla.org/Developing_a_Model-View-Controller_Component_-_Part_1