Presentation on Joomla!Days Netherlands by Peter Martin

1. 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

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 2

3. Joomla Extensions
Extend functionality of
Content Management System:
 Components
 Modules
 Plugins
 Languages
 Templates
Peter Martin – joomladays.nl – 13 June 2009 3

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 4

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 5

6. Plugins
 Supporting
 “Listening” in background
 Different types, e.g.:
– System
– WYSIWYG editors
– Search
Peter Martin – joomladays.nl – 13 June 2009 6

7. “Cooperation” of Extensions
 Search Module
C Form M Form
 Search Component
– Result Form
– Search Form
P Search
 Search Plugin
database table
– Articles P Search
C Processing
– Categories database table
P Search
– Sections
database table
– Contacts
C Show results
Peter Martin – joomladays.nl – 13 June 2009 7

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 8

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 9

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 10

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 11

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 12

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 13

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.xml
mod_db8latestweblinks.zip
 mod_db8latestweblinks.php
Peter Martin – joomladays.nl – 13 June 2009 14

15. 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

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 16

17. It's working, but...
What if you want 4?
>>> Parameters <<<
Peter Martin – joomladays.nl – 13 June 2009 17

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 18

19. 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

20. 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/>
<?php endforeach; ?>
Peter Martin – joomladays.nl – 13 June 2009 20

21. Configure parameters in back­end
Peter Martin – joomladays.nl – 13 June 2009 21

22. Store parameters in jos_modules
In phpMyAdmin:
Peter Martin – joomladays.nl – 13 June 2009 22

23. 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

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 24

25. 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

26. Module Layout ­ Class Suffix 2/2
Back­end > Module Parameters
Front­end
Storage in jos_modules
Peter Martin – joomladays.nl – 13 June 2009 26

27. 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

28. 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

29. 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

30. 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

31. 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

32. Creating a Module (complex)
 Object­oriented programming (OOP),
seperation:
– Business logic
 easier to extend the code
– Presentation layer
 Easier 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 32

33. 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 endforeach; ?>
Peter Martin – joomladays.nl – 13 June 2009 33

34. 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

35. 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

36. 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

37. 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

38. 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();
// [return data]
}
}
Peter Martin – joomladays.nl – 13 June 2009 38

39. 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

40. 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"
description="COUNTDESCR" />
</params>
Peter Martin – joomladays.nl – 13 June 2009 40

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 41

42. 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

43. Module Diagram: 2. helper file
0. Joomla 1. Root file 2. Helper file 0. Joomla
helper.php
class modDB8LatestWeblinksHelper
{
function &getItems(&$params){ jos_modules
// [retrieve parameters]
// [retrieve database records]
jos_weblinks
// [return data]
}
}
Peter Martin – joomladays.nl – 13 June 2009 43

44. 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

45. 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(
'mod_db8latestweblinks')); jos_weblinks
Peter Martin – joomladays.nl – 13 June 2009 45

46. 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; ?>"
target="_blank">
<?php echo $item->title; ?></a> jos_weblinks
</li>
<?php endforeach; ?>
</ul>
Peter Martin – joomladays.nl – 13 June 2009 46

47. 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

48. 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

49. Possible improvements 1
Peter Martin – joomladays.nl – 13 June 2009 49

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 50

51. Possible improvements 2
Peter Martin – joomladays.nl – 13 June 2009 51

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 52

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 53

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 54

55. 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