Joomla 1.5 modules - Joomla!Days NL 2009 #jd09nl

             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 (nl­NL)– 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 + “mouse­over” description for 

the latest 3 weblink entries

Peter Martin – joomladays.nl – 13 June 2009   13

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   14

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.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>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   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 back­end

Peter Martin – joomladays.nl – 13 June 2009   22

Store parameters in jos_modulesIn phpMyAdmin:

Peter Martin – joomladays.nl – 13 June 2009   23

Result in Front­end

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/2Back­end > Module Parameters

Front­end

Storage in jos_modules

Peter Martin – joomladays.nl – 13 June 2009   27

TranslationCreate language independent modulesINI 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 Moduleen­GB.mod_db8latestweblinks.ininl­NL.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)

en­GB.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)

en­GB.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)

nl­NL.mod_db8latestweblinks.ini

Peter Martin – joomladays.nl – 13 June 2009   32

Creating a Module (complex)

Object­oriented 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!)

Model­View­Controller (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>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" 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="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   48

Distribution – packaging 2/2

mod_db8latestweblinks.zip

mod_db8latestweblinks.phpmod_db8latestweblinks.xmlhelper.phpindex.htmltmpl/index.htmltmpl/default.phpen­GB.mod_db8latestweblinks.ininl­NL.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 Martine­mail: info at db8.nlwebsite: www.db8.nl