הסבר זה מיועד למתכנתים המעוניינים לבנות מודול בג'ומלה.
ישנם 3 סוגים של הרחבות בג'ומלה – הראשונה היא plugin שמספקת קוד קצר שרץ בכל האתר (למשל קוד ג'אווהסקריפט שמסתיר כתובות מייל) השניה היא קומפוננטה – קומפוננטה מטפלת בהוספת Content Type לאתר ג'ומלה. ההרחבה השלישית היא מודול באמצעותו אנו יכולים ליצור תיבת מידע או פריטי מידע נוספים שיופיעו במקומות שונים באתר – כמו למשל רשימת משתמשים רנדומליים או מובילים (בכמה פרמטרים) או רשימה של תוכן נבחר.
יצירת מודול בג'ומלה היא פשוטה למדי, יותר מדרופל והרבה יותר מוורדפרס. מדריך זה ילמד אתכם כיצד ליצור מודול כזה תוך התמקדות במרכיבי המודול השונים. המודול שנבנה במאמר זה יציג לנו רשימה של כל הכותרות של התכנים כאשר מספר הכותרות ברשימה ייקבע מממשק הניהול.
ג'ומלה היא מערכת שכתובה בפרדיגמה מונחית עצמים (OOP). אם אין לכם ניסיון ב-OOP, אני ממליץ לכם ללמוד OOP ו-PHP5 לפני הקריאה במדריך זה.
חלקי המודול השונים
המודול בנוי משלושה חלקים עיקריים. הראשון והכיפי שביניהם הוא ה-XML שבאמצעותו אנו מגדירים את השם והתיאור של המודול אבל גם יכולים להגדיר פרמטרים שהמשתמש יוכל לשנות בממשק הניהול.
השני הוא קבצי ה-PHP השונים שמבצעים את הפעילות השונות שהמודול עושה – כמו למשל שאילתה למסד הנתונים או יצירת רשימה (ul).
החלק השלישי הוא קבצים נלווים כמו למשל קבצי שפה, קבצי CSS, ג'אווהסקריפט וכו'.
כמה מילים על פיתוח המודול
כיוון שהתקנת המודולים בג'ומלה מניחה שהמודול כבר מגיע 'מוכן', אנו יוצרים את כל הקבצים לפני הפיתוח. שומרים את כולם ב-ZIP ואז מתקינים את המודול. כעת ניתן לבצע שינויים בקבצים ולראות את התוצאה בג'ומלה.
אני ממליץ על Eclipse PDT שהיא פלטפורמת פיתוח נהדרת עבור PHP
XML
ה-XML של המודול קובע עבורנו לא רק את פרטי המודול (היוצר שלו, זכויות היוצרים וכו') אלא גם איך הוא יופיע בממשק הניהול וגם את הפרמטרים שהמשתמש יכול להכניס. הנה קוד XML שישמש את המודול שלנו
<?xml version="1.0" encoding="utf-8"?>
<install type="module" version="1.5.0">
<name>mod_top_list</name>
<author>Ran Bar-Zik</author>
<creationDate>March 2010</creationDate>
<copyright>Copyright (C) Ran Bar-Zik. All rights reserved.</copyright>
<authorEmail>[email protected]</authorEmail>
<authorUrl>internet-israel.com</authorUrl>
<version>1.5.0</version>
<description>Displays block with list of nodes</description>
<files>
<filename module="mod_top_list">mod_top_list.php</filename>
<filename>mod_top_list_helper.php</filename>
<filename>tmpl/mod_top_list_default.php</filename>
<filename>tmpl/top_list.css</filename>
<filename>tmpl/top_list.js</filename>
</files>
<languages>
<!-- Any language files included with the module -->
<language tag="en-GB">mod_top_list.ini</language>
</languages>
<params addpath="[path-Joomla]/templates/mod_top_list">
<param name="nodecount" type="text" default="5"
label="nodecount"
description="nodecount" />
</params>
<positions>
<position>top</position>
<position>left</position>
<position>right</position>
<position>bottom</position>
<position>banner</position>
<position>syndicate</position>
<position>footer</position>
<position>user1</position>
<position>user2</position>
<position>user3</position>
<position>user4</position>
</positions>
</install>
רוב המידע כמו שם היוצר, אתר היוצר, תיאור המודול ושם המודול הוא סטנדרטי ואין מה להתעכב עליו. יש כאן כמה דברים לא טריוויאלים ב-XML שהם כן חשובים:
files – כל הקבצים שכולל המודול כולל התיקיות השונות – חובה להכניס את כל הקבצים למרות שזה מעיק מאד.
languages – קבצי התרגום. במקרה הזה יש רק תרגום לאנגלית. אבל אפשר להכניס כמה קבצי שפה שרוצים באותו הפורמט.
params – זה החלק הכי מגניב שיש בג'ומלה – כאן אני יכול להכניס פרמטרים שאפשר לעדכן מממשק הניהול ואחר כך אני יכול להשתמש בהם במודול שלי. אני יכול לשים default ולהשתמש בלא מעט סוגים של פרמטרים כמו פרמטרים שיציגו בפני המשתמש רשימה לבחור ממנה, או פרמטרים שמבצעים שאילתת SQL ומציגים בפני המשתמש את רשימת התוצאות לבחור ממנה. במקרה הזה בחרתי ב-type שהוא text שמציג בפני המשתמש שדה טקסט קטן. יש כאן גם את הלייבל שאני יכול לבחור עבור השדה שלי במסך הניהול וגם ערך דיפולטיבי והכי חשוב – השם שלו שאחר כך יאפשר לי רפרנס מהסקריפט. בדוקומנטציה של ג'ומלה אפשר למצוא פירוט של כל הפרמטרים.
positions – מאפשרים לי לקבוע את המקומות האפשריים למודול שלי.
קבצי ה-PHP השונים
mod_top_list.php
הקובץ הראשי ייקרא בשם של המודול והוא יעשה כמה דברים:
1. יטען את הפרמטר של המשתמש (במקרה הזה מספר כלשהו שישמש אותנו כ-LIMIT של השאילתה).
2. יטען קובץ php נוסף שבו יש את שאילתת ה-SQL ושמו הוא helper.
3. יקרא למתודה מתוך ה-helper.
4. יטען 2 קבצים חיצוניים – JavaScript ו-CSS.
5. יטען את קובץ ה-template.
<?php
/**
* @version $Id: mod_maketology_top_list.php $
* @package Joomla
* @copyright Copyright (C) Ran Bar-Zik. All rights reserved.
* @license GNU/GPL, see LICENSE.php
* Joomla! 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.
* See COPYRIGHT.php for copyright notices and details.
*/
//Mandatory line
defined('_JEXEC') or die('Direct Access to this location is not allowed.');
// include the helper file
require_once(dirname(__FILE__).DS.'mod_top_list_helper.php');
// get a parameter from the module's configuration
$nodecount = $params->get('nodecount');
// get the items to display from the helper
$items = TopListHelper::getItems($nodecount);
//adding css and script to the module
JHTML::stylesheet("modules/top_list/tmpl/top_list.css", null);
JHTML::script("modules/top_list/tmpl/top_list.js", null);
// include the template for display
require(JModuleHelper::getLayoutPath('mod_top_list'));
כפי שאנו רואים, הקוד הוא די פשוט. טעינת השדה שהמשתמש ממלא בממשק הניהול נעשית על ידי $params->get('nodecount') כאשר ה-nodecount הוא השם של המשתנה שהגדרנו ב-XML וניתן לשנות את התוכן שלו דרך ממשק הניהול. אל תגידו שזה לא גאוני.
את שאר הפרמטרים היותר טריוויאליים של המודול (כמו למשל הכותרת שלו) אפשר לקבל מאובייקט module$.
שאר הקוד הוא בעיקר require לקבצים אחרים, למעט הקריאה למתודה בקובץ ה-helper והקריאה לקבצים החיצוניים שעליה נדון בהמשך.
mod_top_list_helper.php
הקובץ הזה מכיל class שבו מתודה שמבצעת את השאילתה ויורה חזרה אובייקט שמכיל את כל התוצאות. למתודה אנו קוראים ב-mod_top_list.php באופן הבא: $items = TopListHelper::getItems($nodecount); ואם תבדקו את הקוד של mod_top_list.php תוכלו לראות את הקריאה הזו. הפרמטר nodecount$ מגיע מממשק המשתמש ומוגדר ב-XML.
<?php
defined('_JEXEC') or die('Direct Access to this location is not allowed.');
class ModTopListHelper
{
/**
* Returns a list of post items
*/
public function getItems($nodecount)
{
// get a reference to the database
$db = &JFactory::getDBO();
// get a list of nodes limited by #nodecount
$query = 'SELECT title FROM jos_content LIMIT ' . $nodecount . '';
$db->setQuery($query);
$items = ($items = $db->loadObjectList())?$items:array();
return $items;
} /
}
אין יותר מדי מה לפרט על mod_top_list_helper.php שמבצע שאילתת MySQL פשוטה.
mod_top_list_default.php
זה קובץ ה-template שלנו שיושב כדת וכדין בתיקית tmpl. התפקיד שלו הוא לקחת את ה-items ולהפוך אותם ל-HTML. ה-items כזכור הגיעו מה-mod_top_list_helper.php ומשאילתת ה-MySQL שלו.
<?php
defined('_JEXEC') or die('Direct Access to this location is not allowed.');
?>
<div class="module-title">
<h2 class="title"><?php echo JText::_('Top nodes'); ?></h2>
</div>
<div class="module-inner">
<?php foreach ($items as $item) { ?>
<ul class="top_module">
<li class="top_module_title">
<?php print $item->title; ?>
</li>
</ul>
<?php } ?>
</div>
קבצים חיצוניים
אני דוגל בשיטה שבה לכל מודול יש את קבצי ה-CSS שלו וקבצי ה-javaScript שלו. את ההכנסה של הקבצים החיצוניים ראינו ב-mod_top_list.php:
//adding css and script to the module
JHTML::stylesheet("modules/top_list/tmpl/top_list.css", null);
JHTML::script("modules/top_list/tmpl/top_list.js", null);
מדובר בקבצים פשוטים שאין יותר מדי מה להרחיב עליהם.
אחרי שיצרנו את כל הקבצים, אנו נכניס את כולן לתיקית zip ונתקין את הקובץ כמודול באמצעות תפריט ה-extenstion במסך האדמין. שם גם אנו יכולים לקבוע את מספר השורות שאנו רוצים (יופיע כפרמטר באדמין) וגם את המיקום שבו אנו רוצים לראות את המודול.
