Joomla 1.

5 Modules
What can you do with them?
What not?
How to module DIY?

Peter Martin, www.db8.nl

Joomladays.nl 2009
Saturday 13 June 2009
 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 2

 Joomla Extensions
Extend functionality of
Content Management System:
 Components
 Modules
 Plugins
 Languages
 Templates

Peter Martin – joomladays.nl – 13 June 2009 3

 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 4

 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 5

 Plugins
 Supporting
 “Listening” in background
 Different types, e.g.:
– System
– WYSIWYG editors
– Search

Peter Martin – joomladays.nl – 13 June 2009 6

 “Cooperation” of Extensions
 Search Module
C Form M Form
 Search Component
– Result Form
– Search Form
 Search Plugin P Search
database table
– Articles
P Search
– Categories C Processing
database table
– Sections
P Search
– Contacts database table

C Show results

Peter Martin – joomladays.nl – 13 June 2009 7

 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 8

 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 9

 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 (nl-NL)
– J!Dump

Peter Martin – joomladays.nl – 13 June 2009 10

 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 11

 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 + “mouse-over” description for
the latest 3 weblink entries

Peter Martin – joomladays.nl – 13 June 2009 12

 Module Elements 1/2
 Location
– Back-end: /administrator/modules/mod_example
– Front-end: /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 13

 Module Elements 2/2
 Reference in jos_modules
 Manual reference
INSERT INTO `jos_modules` VALUES (0, 'db8 Latest
Weblinks', '', 0, 'left', 0, '0000-00-00 00:00:00', 1,
'mod_db8latestweblinks', 0, 0, 1, '', 0, 0, '');
 “Automatic” reference
– Install in Joomla back-end with XML installation file
(“Sandbox installer”)
 mod_db8latestweblinks.xml
 mod_db8latestweblinks.php
mod_db8latestweblinks.zip

Peter Martin – joomladays.nl – 13 June 2009 14

 Module – XML Installation File
mod_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>joomla@db8.nl</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 15

 Module – PHP File (logic)
mod_db8latestweblinks.php
<?php
/**
* @version $Id: mod_db8latestweblinks.php 0001 2009-06-13 14:20:00Z pe7er $
* @copyrightCopyright 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; ?>">
Peter Martin – joomladays.nl – 13 June 2009 16
 It's working, but...

What if you want 4?

>>> Parameters <<<

Peter Martin – joomladays.nl – 13 June 2009 17

 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 18

 Module – Determine parameters
mod_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 19

 Module – Use parameters
mod_db8latestweblinks.php
<?php
defined('_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/>
Peter Martin – joomladays.nl – 13 June 2009 20
 Configure parameters in back-end

Peter Martin – joomladays.nl – 13 June 2009 21

 Store parameters in jos_modules
In phpMyAdmin:

Peter Martin – joomladays.nl – 13 June 2009 22

 Result in Front-end

It is working!...

but I would like

the same layout
as Main Menu...

Peter Martin – joomladays.nl – 13 June 2009 23

 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 24

 Module Layout - Class Suffix 1/2
mod_db8latestweblinks.xml
<params>

<param name="moduleclass_sfx" type="text" default="" label="Module

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

</params>

Peter Martin – joomladays.nl – 13 June 2009 25

 Module Layout - Class Suffix 2/2
Back-end > Module Parameters
Front-end

Storage in jos_modules

Peter Martin – joomladays.nl – 13 June 2009 26

 Translation
Create language independent modules
INI files: UTF-8 without Byte Order Mark (BOM)
Location, for each language:
– /language/en-GB/
– /language/nl-NL/
Naming convention:
ISO tag.mod_modulename.ini
– Language files for db8weblinks Module
 en-GB.mod_db8latestweblinks.ini
 nl-NL.mod_db8latestweblinks.ini

Peter Martin – joomladays.nl – 13 June 2009 27

 Translate “parameters” file
mod_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 28

 Language file – English
en-GB.mod_db8latestweblinks.ini
COUNT = Number of weblinks
COUNTDESCR = The number of weblinks to display (default is 5)

Peter Martin – joomladays.nl – 13 June 2009 29

 Language file – English (corrected)
en-GB.mod_db8latestweblinks.ini
COUNTLINKS = Number of weblinks
COUNTDESCR = The number of weblinks to display (default is 5)

Peter Martin – joomladays.nl – 13 June 2009 30

 Language file – Dutch
nl-NL.mod_db8latestweblinks.ini
COUNTLINKS = Aantal weblinks
COUNTDESCR = Het aantal weblinks dat wordt getoond (standaard is 5)

Peter Martin – joomladays.nl – 13 June 2009 31

 Creating a Module (complex)

 Object-oriented programming (OOP),

seperation:
– Business logic
 easier to extend the code
– Presentation layer
 Easierto change without PHP knowledge
(webdesigners will love it)
 “Template overrides” (no more core hacks!)

 Model-View-Controller (MVC)

Peter Martin – joomladays.nl – 13 June 2009 32

 Module (simple, no MVC)
mod_db8latestweblinks.php
<?php
defined('_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
Peter Martin endforeach;
– joomladays.nl – 13 June?>
2009 33
 Module - MVC style: overview
1 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 34

 Module - MVC style: 1. root file
mod_db8latestweblinks.php
<?php
defined('_JEXEC') or die('Restricted access');

//Trigger Helper file

require_once (dirname(__FILE__).DS.'helper.php');
$list = modDB8LatestWeblinksHelper::getItems($params);

//Trigger Layout file mod_db8latestweblinks/tmpl/default.php

require(JModuleHelper::getLayoutPath('mod_db8latestweblinks'));

Peter Martin – joomladays.nl – 13 June 2009 35

 Module - MVC style: 2. helper file
helper.php - shown in 3 parts: overview

class modDB8LatestWeblinksHelper
{
// [retrieve parameters]

// [retrieve database records]

// [return data]
}

Peter Martin – joomladays.nl – 13 June 2009 36

 Module - MVC style: 2. helper file
helper.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 37

 Module - MVC style: 2. helper file
helper.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();
Peter Martin – joomladays.nl – 13 June 2009 38
 Module - MVC style: 2. helper file
helper.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 39
 Module - MVC style: 3. installer file
mod_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>joomla@db8.nl</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"
Peter Martin – joomladays.nl – 13 June
description="COUNTDESCR" /> 2009 40
 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
Peter Martin endforeach;
– joomladays.nl – 13 June 2009 ?> 41
 Module Diagram: 1. root file

0. Joomla 1. Root file

mod_db8latestweblinks.php

//Trigger Helper file

require_once
(dirname(__FILE__).DS.'helper.php');
$list =
modDB8LatestWeblinksHelper::getItems($params);

Peter Martin – joomladays.nl – 13 June 2009 42

 Module Diagram: 2. helper file

0. Joomla 1. Root file 2. Helper file 0. Joomla

helper.php
class modDB8LatestWeblinksHelper
{
jos_modules
function &getItems(&$params){
// [retrieve parameters]

// [retrieve database records] jos_weblinks

// [return data]
}
Peter Martin – joomladays.nl – 13 June 2009 43
 Module Diagram: 3. installer file
 not used during process
0. Joomla
 only for installing & configuration

jos_modules

Peter Martin – joomladays.nl – 13 June 2009 44

 Module Diagram: 4. screen output

0. Joomla 1. Root file 2. Helper file 0. Joomla

3. Layout file

mod_db8latestweblinks.php jos_modules

//Trigger Layout file

mod_db8latestweblinks/tmpl/default.php
require(JModuleHelper::getLayoutPath( jos_weblinks

'mod_db8latestweblinks'));

Peter Martin – joomladays.nl – 13 June 2009 45

 Module Diagram: 4. screen output

0. Joomla 1. Root file 2. Helper file 0. Joomla

3. Layout file
/tmpl/default.php
<ul> jos_modules
<?php foreach ($list as $item) : ?>
<li>
<a href="<?php echo $item->url; ?>"
title="<?php echo $item->description; ?>"
jos_weblinks
target="_blank">
<?php echo $item->title; ?></a>
</li>
<?php
Peter Martin – endforeach; ?>
joomladays.nl – 13 June 2009 46
 Distribution – packaging 1/2
mod_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="en-GB">en-GB.mod_db8latestweblinks.ini</language>
<language tag="nl-NL">nl-NL.mod_db8latestweblinks.ini</language>
</languages>

Peter Martin – joomladays.nl – 13 June 2009 47

 Distribution – packaging 2/2
mod_db8latestweblinks.php
mod_db8latestweblinks.xml
helper.php
index.html
tmpl/index.html
tmpl/default.php
en-GB.mod_db8latestweblinks.ini
nl-NL.mod_db8latestweblinks.ini

mod_db8latestweblinks.zip

Peter Martin – joomladays.nl – 13 June 2009 48

 Possible improvements 1

Peter Martin – joomladays.nl – 13 June 2009 49

 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 50

 Possible improvements 2

Peter Martin – joomladays.nl – 13 June 2009 51

 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 52

 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 53

 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 54

 Questions ?
 Thanks for your attention!
 Presentation & module will be available at
www.db8.nl

Peter Martin
e-mail: info at db8.nl
website: www.db8.nl

Peter Martin – joomladays.nl – 13 June 2009 55