Joomla 1.5 Modules
What can you do with them? What not? How to module DIY?
Peter Martin, www.db8.nlJoomladays.nl 2009Saturday 13 June 2009
Peter Martin – joomladays.nl – 13 June 2009 2
Presentation overview Introduction Module principles Creating a Module – 1.5 native (old style) Creating a Module – 1.5 native (MVC) Questions
Peter Martin – joomladays.nl – 13 June 2009 3
Joomla ExtensionsExtend functionality of
Content Management System: Components Modules Plugins Languages Templates
Peter Martin – joomladays.nl – 13 June 2009 4
Module principles Supporting One “modus”
– No internal processing of user interaction
Multiple modules per page Dependency on active menu
– URL + &Itemid=x
Peter Martin – joomladays.nl – 13 June 2009 5
Components Are everything
– Main part of page– Process data
Have Multiple modi– Internal processing of user interaction
Only one per page Multiple “views”, e.g. Content component:
– Category List Layout– Category Blog Layout– Article Layout
Peter Martin – joomladays.nl – 13 June 2009 6
Plugins Supporting “Listening” in background Different types, e.g.:
– System– WYSIWYG editors– Search
Peter Martin – joomladays.nl – 13 June 2009 7
“Cooperation” of Extensions Search Module Search Component
– Result Form– Search Form
Search Plugin– Articles– Categories– Sections– Contacts
C Form
C Show results
C Processing
P Search database table
M Form
P Search database table
P Search database table
Peter Martin – joomladays.nl – 13 June 2009 8
Module Positions Defined positions
– show: www.example.com/index.php?tp=1 Defining positions
– <?php if($this>countModules('left')) : ?><jdoc:include type="modules" name="left" style="xhtml" /><?php endif; ?>
Peter Martin – joomladays.nl – 13 June 2009 9
And now the real thing... Development Tools Module parts: .PHP & .XML Usage of “Sandbox installer” Parameters Layout Translation Distribution Questions
Peter Martin – joomladays.nl – 13 June 2009 10
Development Tools 1/2 Local web environment
– OS: Windows / MAC OSX / Linux– LAMP stack (or XAMPP)– Xdebug (PHP module)– php.ini: error_reporting = E_ALL & E_NOTICE
Joomla (Latest Stable Version)– Example data + default Rhuk Milkyway template– 2nd language installed (nlNL)– J!Dump
Peter Martin – joomladays.nl – 13 June 2009 11
Development Tools 2/2 PHP Editor with “code highlighting”
– Eclipse PDT
phpMyAdmin FireFox
+ plugins:– Firebug– Webdeveloper toolbar– MeasureIT– ColorZilla
Peter Martin – joomladays.nl – 13 June 2009 12
Creating a Module (simple)
Joomla's Weblinks component– Shows weblinks from category + register clicks– Database table: jos_weblinks
title, URL, description, date, hits, catid.
Create a simple Module for Joomla 1.5 native– Show the title + link + “mouseover” description for
the latest 3 weblink entries
Peter Martin – joomladays.nl – 13 June 2009 13
Module Elements 1/2 Location
– Backend: /administrator/modules/mod_example– Frontend: /modules/mod_example– My example module:
“db8 Latest Weblinks” => mod_db8latestweblinks File names
– .PHP (logic)– .XML (installation & parameters)– .INI (language files, in /languages/ )
Peter Martin – joomladays.nl – 13 June 2009 14
Module Elements 2/2 Reference in jos_modules Manual reference
INSERT INTO `jos_modules` VALUES (0, 'db8 Latest Weblinks', '', 0, 'left', 0, '00000000 00:00:00', 1, 'mod_db8latestweblinks', 0, 0, 1, '', 0, 0, '');
“Automatic” reference– Install in Joomla backend with XML installation file
(“Sandbox installer”)mod_db8latestweblinks.xmlmod_db8latestweblinks.php mod_db8latestweblinks.zip
Peter Martin – joomladays.nl – 13 June 2009 15
Module – XML Installation Filemod_db8latestweblinks.xml<?xml version="1.0" encoding="utf-8"?><install type="module" version="2.1" client="site"><name>db8 Latest Weblinks</name><author>Peter Martin (pe7er)</author><authorEmail>[email protected]</authorEmail><authorUrl>www.db8.nl</authorUrl><creationDate>June 2009</creationDate><copyright>Copyright 2009 by Peter Martin / db8.nl.</copyright><license>http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL</license><version>2.3</version><description>This module shows the latest weblinks.</description><files><filename module="mod_db8latestweblinks">mod_db8latestweblinks.php</filename></files></install>
Peter Martin – joomladays.nl – 13 June 2009 16
Module – PHP File (logic)mod_db8latestweblinks.php<?php/*** @version $Id: mod_db8latestweblinks.php 0001 2009-06-13 14:20:00Z pe7er $* @copyright Copyright 2009 by Peter Martin / db8.nl. All rights reserved.* @license http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL*/
defined('_JEXEC') or die('Restricted access');
$db =& JFactory::getDBO();$query = 'SELECT title, url, description' .
' FROM #__weblinks' .' ORDER BY date DESC';
$db->setQuery($query, 0, 3);$rows = $db->loadObjectList();foreach ($rows as $item) : ?>
<a href="<?php echo $item->url; ?>" target="_blank" title="<?php echo $item->description; ?>">
<?php echo $item->title; ?></a><br/><?php endforeach; ?>
Peter Martin – joomladays.nl – 13 June 2009 17
It's working, but...
What if you want 4?
>>> Parameters <<<
Peter Martin – joomladays.nl – 13 June 2009 18
Module Parameters
How does Joomla... determine parameters?
– .XML file define all parameters→
keep parameters?– jos_modules.params stores parameters→
use parameters?– .php file retrieve & use→
Peter Martin – joomladays.nl – 13 June 2009 19
Module – Determine parametersmod_db8latestweblinks.xml
For “Number of weblinks” parameter, add:
<params><param name="count" type="text" default="5" label="Number of weblinks" description="The number of weblinks to display (default is 5)" /></params>
Peter Martin – joomladays.nl – 13 June 2009 20
Module – Use parameters
<?phpdefined('_JEXEC') or die('Restricted access');$count = intval( $params->get( 'count' ) ); // new!
$db =& JFactory::getDBO();$query = 'SELECT title, url, description' .
' FROM #__weblinks' .' ORDER BY date DESC';
$db->setQuery($query, 0, $count); // changed!$rows = $db->loadObjectList();foreach ($rows as $item) : ?>
<a href="<?php echo $item->url; ?>" target="_blank" title="<?php echo $item->description; ?>">
<?php echo $item->title; ?></a><br/><?php endforeach; ?>
mod_db8latestweblinks.php
Peter Martin – joomladays.nl – 13 June 2009 21
Configure parameters in backend
Peter Martin – joomladays.nl – 13 June 2009 22
Store parameters in jos_modulesIn phpMyAdmin:
Peter Martin – joomladays.nl – 13 June 2009 23
Result in Frontend
It is working!...
but I would like the same layoutas Main Menu...
Peter Martin – joomladays.nl – 13 June 2009 24
Module Layout Default layout
– In template.css – (CSS tag “module”)
Individual layout– Specific layout in template.css
(CSS tag: module_menu)– Module Class Suffix in Module parameters
(tag: _menu)
Peter Martin – joomladays.nl – 13 June 2009 25
Module Layout Class Suffix 1/2
<params>
</params>
<param name="moduleclass_sfx" type="text" default="" label="Module Class Suffix" description="PARAMMODULECLASSSUFFIX" /><param name="@spacer" type="spacer" default="" label="" description="" />
mod_db8latestweblinks.xml
Peter Martin – joomladays.nl – 13 June 2009 26
Module Layout Class Suffix 2/2Backend > Module Parameters
Frontend
Storage in jos_modules
Peter Martin – joomladays.nl – 13 June 2009 27
TranslationCreate language independent modulesINI files: UTF8 without Byte Order Mark (BOM)Location, for each language:
– /language/enGB/– /language/nlNL/
Naming convention: ISO tag.mod_modulename.ini
– Language files for db8weblinks ModuleenGB.mod_db8latestweblinks.ininlNL.mod_db8latestweblinks.ini
Peter Martin – joomladays.nl – 13 June 2009 28
Translate “parameters” filemod_db8latestweblinks.xml
<params><param name="moduleclass_sfx" type="text" default="" label="Module Class Suffix" description="PARAMMODULECLASSSUFFIX" /><param name="@spacer" type="spacer" default="" label="" description="" /><param name="count" type="text" default="5" label="COUNTLINKS" description="COUNTDESCR" /></params></install>
Peter Martin – joomladays.nl – 13 June 2009 29
Language file – English
COUNT = Number of weblinksCOUNTDESCR = The number of weblinks to display (default is 5)
enGB.mod_db8latestweblinks.ini
Peter Martin – joomladays.nl – 13 June 2009 30
Language file – English (corrected)
COUNTLINKS = Number of weblinksCOUNTDESCR = The number of weblinks to display (default is 5)
enGB.mod_db8latestweblinks.ini
Peter Martin – joomladays.nl – 13 June 2009 31
Language file – Dutch
COUNTLINKS = Aantal weblinksCOUNTDESCR = Het aantal weblinks dat wordt getoond (standaard is 5)
nlNL.mod_db8latestweblinks.ini
Peter Martin – joomladays.nl – 13 June 2009 32
Creating a Module (complex)
Objectoriented programming (OOP),seperation:– Business logic
easier to extend the code
– Presentation layerEasier to change without PHP knowledge
(webdesigners will love it) “Template overrides” (no more core hacks!)
ModelViewController (MVC)
Peter Martin – joomladays.nl – 13 June 2009 33
Module (simple, no MVC)mod_db8latestweblinks.php<?phpdefined('_JEXEC') or die('Restricted access');$count = intval( $params->get( 'count' ) );$db =& JFactory::getDBO();$query = 'SELECT title, url, description' .
' FROM #__weblinks' .' ORDER BY date DESC';
$db->setQuery($query, 0, $count);$rows = $db->loadObjectList();foreach ($rows as $item) : ?>
<a href="<?php echo $item->url; ?>" target="_blank"
title="<?php echo $item->description; ?>"><?php echo $item->title; ?></a><br/>
<?php endforeach; ?>
Peter Martin – joomladays.nl – 13 June 2009 34
Module MVC style: overview1 Root file: mod_db8latestweblinks.php
– Controls the process
2 Helper file: helper.php– Retrieves records from database
3 Installer file: mod_db8latestweblinks.xml– Used with installation & parameter initialisation
4 Presentation layer: /tmpl/default.php– Screen output
>> Note: example code is PHP4 compatible <<
Peter Martin – joomladays.nl – 13 June 2009 35
Module MVC style: 1. root file
<?phpdefined('_JEXEC') or die('Restricted access');
//Trigger Helper filerequire_once (dirname(__FILE__).DS.'helper.php');$list = modDB8LatestWeblinksHelper::getItems($params);
//Trigger Layout file mod_db8latestweblinks/tmpl/default.phprequire(JModuleHelper::getLayoutPath('mod_db8latestweblinks'));
mod_db8latestweblinks.php
Peter Martin – joomladays.nl – 13 June 2009 36
helper.php - shown in 3 parts: overview
class modDB8LatestWeblinksHelper{ // [retrieve parameters]
// [retrieve database records]
// [return data]}
Module MVC style: 2. helper file
Peter Martin – joomladays.nl – 13 June 2009 37
Module MVC style: 2. helper filehelper.php - shown in 3 parts: 1st part
class modDB8LatestWeblinksHelper{ function &getItems(&$params){ // [retrieve parameters] $count = intval($params->get('count', 5));
// [retrieve database records] // [return data] }}
Peter Martin – joomladays.nl – 13 June 2009 38
Module MVC style: 2. helper filehelper.php - shown in 3 parts: 2nd part
class modDB8LatestWeblinksHelper{ function &getItems(&$params){ // [retrieve parameters] // [retrieve database records] $db =& JFactory::getDBO(); $query = 'SELECT title, url, description' . ' FROM #__weblinks' . ' ORDER BY date DESC'; $db->setQuery($query,0,$count); $list = $db->loadObjectList(); // [return data] }}
Peter Martin – joomladays.nl – 13 June 2009 39
Module MVC style: 2. helper filehelper.php - shown in 3 parts: 3rd part
class modDB8LatestWeblinksHelper{ function &getItems(&$params){ // [retrieve parameters]
// [retrieve database records]
// [return data] return $list; }}
Peter Martin – joomladays.nl – 13 June 2009 40
Module MVC style: 3. installer filemod_db8latestweblinks.xml<?xml version="1.0" encoding="utf-8"?><install type="module" version="2.1" client="site"><name>db8 Latest Weblinks</name><author>Peter Martin (pe7er)</author><authorEmail>[email protected]</authorEmail><authorUrl>www.db8.nl</authorUrl><creationDate>June 2009</creationDate><copyright>Copyright 2009 by Peter Martin / db8.nl.</copyright><license>http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL</license><version>2.3</version><description>This module shows the latest weblinks.</description><files><filename module="mod_db8latestweblinks">mod_db8latestweblinks.php</filename></files></install><params><param name="moduleclass_sfx" type="text" default="" label="Module Class Suffix" description="PARAMMODULECLASSSUFFIX" /><param name="@spacer" type="spacer" default="" label="" description="" /><param name="count" type="text" default="5" label="COUNTLINKS" description="COUNTDESCR" /></params>
Peter Martin – joomladays.nl – 13 June 2009 41
Module MVC style: 4. screen output/tmpl/default.php
<?php defined('_JEXEC') or die('Restricted access'); ?>
<ul><?php foreach ($list as $item) : ?> <li> <a href="<?php echo $item->url; ?>"
title="<?php echo $item->description; ?>"target="_blank">
<?php echo $item->title; ?></a> </li><?php endforeach; ?></ul>
Peter Martin – joomladays.nl – 13 June 2009 42
Module Diagram: 1. root file
0. Joomla 1. Root file
mod_db8latestweblinks.php
//Trigger Helper filerequire_once (dirname(__FILE__).DS.'helper.php');$list = modDB8LatestWeblinksHelper::getItems($params);
Peter Martin – joomladays.nl – 13 June 2009 43
Module Diagram: 2. helper file
0. Joomla 1. Root file 2. Helper file
jos_modules
jos_weblinks
helper.phpclass modDB8LatestWeblinksHelper{ function &getItems(&$params){ // [retrieve parameters]
// [retrieve database records]
// [return data] }}
0. Joomla
Peter Martin – joomladays.nl – 13 June 2009 44
Module Diagram: 3. installer file
jos_modules
0. Joomla not used during process only for installing & configuration
Peter Martin – joomladays.nl – 13 June 2009 45
Module Diagram: 4. screen output
0. Joomla 1. Root file 2. Helper file
jos_modules
jos_weblinks
0. Joomla
3. Layout file
mod_db8latestweblinks.php
//Trigger Layout file mod_db8latestweblinks/tmpl/default.phprequire(JModuleHelper::getLayoutPath('mod_db8latestweblinks'));
Peter Martin – joomladays.nl – 13 June 2009 46
Module Diagram: 4. screen output
0. Joomla 1. Root file 2. Helper file
jos_modules
jos_weblinks
0. Joomla
3. Layout file/tmpl/default.php<ul><?php foreach ($list as $item) : ?> <li> <a href="<?php echo $item->url; ?>"
title="<?php echo $item->description; ?>"target="_blank">
<?php echo $item->title; ?></a> </li><?php endforeach; ?></ul>
Peter Martin – joomladays.nl – 13 June 2009 47
Distribution – packaging 1/2mod_db8latestweblinks.xml +
<files><filename module="mod_db8latestweblinks">
mod_db8latestweblinks.php</filename><filename>index.html</filename><filename>helper.php</filename><filename>tmpl/index.html</filename><filename>tmpl/default.php</filename>
</files><languages><language tag="enGB">enGB.mod_db8latestweblinks.ini</language><language tag="nlNL">nlNL.mod_db8latestweblinks.ini</language></languages>
Peter Martin – joomladays.nl – 13 June 2009 48
Distribution – packaging 2/2
mod_db8latestweblinks.zip
mod_db8latestweblinks.phpmod_db8latestweblinks.xmlhelper.phpindex.htmltmpl/index.htmltmpl/default.phpenGB.mod_db8latestweblinks.ininlNL.mod_db8latestweblinks.ini
Peter Martin – joomladays.nl – 13 June 2009 49
Possible improvements 1
Peter Martin – joomladays.nl – 13 June 2009 50
Possible improvements 1 The output uses target=”_blank”/tmpl/default.php
<a href="<?php echo $item->url; ?>"
title="<?php echo $item->description; ?>"
target="_blank">
Maybe use parameters to define target of weblinks
Peter Martin – joomladays.nl – 13 June 2009 51
Possible improvements 2
Peter Martin – joomladays.nl – 13 June 2009 52
Possible improvements 2 The output uses direct URL from database/tmpl/default.php
<a href="<?php echo $item->url; ?>"
title="<?php echo $item->description; ?>"
target="_blank">
Therefore the hits are not recorded by the weblinks component
Maybe change module so that it triggers the weblink component to open the weblink
Peter Martin – joomladays.nl – 13 June 2009 53
Possible improvements 3 Increase performance.... add cache to Module
– JCache
<params group="advanced"><param name="cache" type="list" default="1" label="Caching"
description="Select whether to cache the content of this module"><option value="1">Use global</option><option value="0">No caching</option>
</param><param name="cache_time" type="text" default="900" label="Cache
Time" description="The time before the module is recached" /></params>
Peter Martin – joomladays.nl – 13 June 2009 54
Possible improvements 4 Use PHP 5 code
– This MVC example module uses PHP4 compatible code because Joomla 1.5 is PHP4 compatible
– Most hosting providers are using PHP5 now– The code can be refactored to PHP5 code
Peter Martin – joomladays.nl – 13 June 2009 55
Questions ? Thanks for your attention! Presentation & module will be available at
www.db8.nl
Peter Martinemail: info at db8.nlwebsite: www.db8.nl