Simple module Development in Joomla! 2.5

Simple Module Development in Joomla! 2.5

Vishwash Gaur

© 2012 Vishwash Gaur. All rights reserved. All registered trademarks, logos, products and service names belong to their

respective owners.Image Credit: http://ayadipro.com/blog/high-tech-education/25-improvements-in-joomla-2-5/

Disclaimer: Images used on this slide are for representative purposes only and belong to their respective owners.

Pre-requisites Basic knowledge of HTML, PHP and MySQL Interest in MVC and CMS frameworks to reduce

development time A web server with PHP/MySQL installed on it Joomla! 2.5 package downloaded and installed

◦ it can be downloaded from http://www.joomla.org/download.html

NOTE: This presentation is focused for the beginners in Joomla! and would cover only a basic overview due to limited time. Further details can be discussed separately later.

Extension Development in

Joomla!Hands on workshop to develop a basic Joomla! Module and component

Let’s create a module called “Reviews” for this workshop which will display customer reviews on the web page

It will allow us to display a simple text in a pre-defined Joomla module position

Once this is done, we will fetch data for the module from DB

Hands-on Module Development

modules>mod_reviews◦ mod_reviews.php◦ mod_reviews.xml◦ helper.php◦ index.html◦ tmpl/default.php◦ tmpl/index.html

Module Folder Structure

mod_modulename.php<?php//license details here

// no direct accessdefined( '_JEXEC' ) or die( 'Restricted access' ); // Include the syndicate functions only oncerequire_once( dirname(__FILE__).DS.'helper.php' ); //load helper class and function$reviews = modReviewsHelper::getReviews( $params );

//load the layout file from template viewsrequire( JModuleHelper::getLayoutPath( 'mod_reviews' ) );?>

// no direct accessdefined( '_JEXEC' ) or die( 'Restricted access' );

As it suggests, this line checks to make sure that this file is being included from the Joomla! application.

It is necessary to prevent variable injection and other potential security concerns.

// Include the syndicate functions only oncerequire_once( dirname(__FILE__).DS.'helper.php' );The helper class is defined in our helper.php file.

This file is included with a require_once statement.

It allows to include necessary functions for the module functionality. Helper file may include basic calculations, DB connection and query code.

//load helper class and function$reviews = modReviewsHelper::getReviews( $params );

This line allows to invoke the appropriate helper class method to retrieve the data.

Currently, we do not use any parameters but it is allowed in this module for future extensibility.

//load the layout file from template viewsrequire( JModuleHelper::getLayoutPath( 'mod_reviews' ) );

This line includes the template to display the output.

<?xml version="1.0" encoding="utf-8"?><extension

type="module"version="2.5"client="site"method="upgrade">

<name>Reviews</name> <author>Vishwash Gaur</author> <version>2.5.0</version> <description>An review module.</description> <files> <filename module="mod_reviews">mod_reviews.php</filename> <filename>index.html</filename> <filename>helper.php</filename>

<folder>tmpl</folder><filename>mod_reviews.xml</filename>

</files></extension>

mod_reviews.xml

This file is used to specify which files the installer needs to copy and is used by the Module Manager to determine which parameters are used to configure the module.

<extension type="module“ version="2.5“ client="site“ method="upgrade">

This line tells to Joomla! that selected extension type is module and compatible with Joomla version 2.5.

Extension type is also defined for site which means it will be available for front-end.

<name>Reviews</name><author>Vishwash Gaur</author><version>2.5.0</version><description>An review module.</description>

<files> <filename

module="mod_reviews">mod_reviews.php</filename> <filename>index.html</filename> <filename>helper.php</filename>

<folder>tmpl</folder><filename>mod_reviews.xml</filename>

</files>

<?xml version="1.0" encoding="utf-8"?><install type="module" version="1.5.0"> <name>Hello, World!</name> <author>John Doe</author> <version>1.5.0</version> <description>A simple Hello, World! module.</description> <files> <filename>mod_reviews.xml</filename> <filename module="mod_reviews">mod_reviews.php</filename> <filename>index.html</filename> <filename>helper.php</filename> <filename>tmpl/default.php</filename> <filename>tmpl/index.html</filename> </files> <params> </params></install>

Difference in Joomla 1.5

<?php//license details here

class modReviewsHelper{ /** * Retrieves the reviews * * @param array $params An object containing the module parameters * @access public */ function getReviews( $params ) { return 'I am a happy user!'; }}?>

helper.php

<html><body bgcolor="#FFFFFF"></body></html>

This file is included to prevent directory browsing. It can be event left blank and whenever someone will access the directory then this file will be default loaded.

Index.html

<?php // no direct accessdefined( '_JEXEC' ) or die( 'Restricted access' );//print user reviewsecho $reviews; ?>

tmpl/default.php

<html><body bgcolor="#FFFFFF"></body></html>

This file is included to prevent directory browsing. It can be event left blank and whenever someone will access the directory then this file will be default loaded.

tmpl/index.html

Once a base module is ready, we can start using it immediately in Joomla.

In Joomla 1.5, it was auto-detected but in Joomla 2.5, we would need to discover a newly developed extension from admin panel.

For this, please login to admin panel and go to Top menu>extensions>extension manager

Click on the discover tab and refresh the data

Discover module in Joomla

Go tot extension manager

Click on the discover button to find newly developed extensions

If your programming is correct, it will find your newly developed extension.Select the extension and click on install button to setup the extension.

Once a module is added in the Joomla! System, it has to be defined on a position using module manager.

It will allow module to display in the front-end.

Display module in front-end

Go to module manager and click on “New” button

Select your newly developed module

Define module position in active template and set other parameters and pages to display the module.I give it position 6 in Beez_20 template.

Module successfully saved, now move to front-end to check this.

You can see user review here

I can’t see the module◦ Check if you have selected correct position in the

active template

Troubleshooting

With the previous example, you can display one static customer review but what if there are many customer reviews which should be dynamically loaded on the page.

Let’s do that!

Module with DB support - Advanced

Using phpMyAdmin or any other DB management tool, create a table called __reviews in the Joomla DB

Add required fields i.e. id, name, city and feedback in the table

Kindly note this example is meant to be very basic for easy understanding

Create table and add fields in the database.Note: Ideally, it is the part of component.

I have done some entries in the DB directly for the demo purpose. It should happen via a back-end component in real environment.

Now, since we are not doing any static code and want to load reviews dynamically from the database, we need to make some changes in below files:◦ mod_reviews.php – minor change◦ helper.php – major change for DB connection and

query◦ tmpl/default.php – minor change◦ tmpl/reviews.php – new template file added

Changes in the code

<?php//license details here

// no direct accessdefined( '_JEXEC' ) or die( 'Restricted access' ); // Include the syndicate functions only oncerequire_once( dirname(__FILE__).DS.'helper.php' ); //load helper class and function//$reviews = modReviewsHelper::getReviews( $params );$rows = modReviewsHelper::getReviews( $params );

//load the layout file from template viewsrequire( JModuleHelper::getLayoutPath( 'mod_reviews' ) );?>

mod_reviews.php

<?xml version="1.0" encoding="utf-8"?><extension

type="module"version="2.5"client="site"method="upgrade">

<name>Reviews</name> <author>Vishwash Gaur</author> <version>2.5.0</version> <description>An review module.</description> <files> <filename module="mod_reviews">mod_reviews.php</filename> <filename>index.html</filename> <filename>helper.php</filename>

<folder>tmpl</folder><filename>mod_reviews.xml</filename>

</files></extension>

mod_reviews.xml

<?php//license details here

class modReviewsHelper{ /** * Retrieves the reviews * * @param array $params An object containing the module parameters * @access public */ function getReviews( $params ) { return 'I am a happy user!'; }}?>

helper.php - old

<?php//license details here

class modReviewsHelper{ /** * Retrieves the reviews * @param array $params An object containing the module parameters * @access public */ function getReviews( $params ) { //return 'I am a happy user!';

//limit the number of items to load from DB$items = $params->get('items', 10);

//make DB connection $db=& JFactory::getDBO(); $result= null;

//run db query $query = 'SELECT * FROM #__reviews'; $db->setQuery($query, 0, $items); $rows = $db->loadObjectList();

//display and handle error warning if ($db->getErrorNum()) { JError::raiseWarning( 500, $db->stderr(true) ); }

return $rows; }

helper.php – Updated Part 1

For the demonstration purpose, kindly understand and note that Joomla! uses it’s own code conventions to make DB connections and to run a query. It allows in less code and standardized approach.

/** * Function to display rating and reviews via views * @param array $params An object containing the module

parameters * @access public */ function renderReviews(&$reviews, &$params) { //variable to store db value of a particular record link to open in detailed view

$link = JRoute::_('index.php?option=com_reviews&id='.$reviews->id.'&task=view');

//call template view for display

require(JModuleHelper::getLayoutPath('mod_reviews' , 'reviews'));

}}?>

helper.php – Part 2

This component doesn’t exists in the system but we have planned it for future use or next demo of component development.

<?php // no direct accessdefined( '_JEXEC' ) or die( 'Restricted access' );//print user reviews//echo $reviews; foreach($rows as $row){ modReviewsHelper::renderReviews($row, $params);}?>

tmpl/default.php

<?php // no direct accessdefined( '_JEXEC' ) or die( 'Restricted access' ); ?><table width="95%"><tr><td><strong><?php echo ucwords(strtolower($reviews->name)); ?></strong><br /><span style="font-size:9px; margin-top:-5px;"><?php echo ucwords(strtolower($reviews->city));?></span><br /></td></tr><tr><td><?php echo wordwrap($reviews->feedback,130, "<br />\n");?></td></tr></table>

tmpl/reviews.php

Display in front-end

Dynamic records from DB

Get your XAMP, LAMP, MAMP or WAMP environment ready

Install and experiment Joomla! Locally Checkout online references Get a book Visit Joomla! JED, Forums and user groups Help each other and learn from experiences

Next Steps

Thank you! I look forward to learn and share more with you in

future too.

I can be reached easily at my blog www.vishwashgaur.com and/or using twitter @vishwashgaur

XAMP: http://www.apachefriends.org/en/xampp.html Joomla!: http://www.joomla.org/ JED: http://extensions.joomla.org/ Joomla! Forum: http://forum.joomla.org/ Joomla! Magazine: http://magazine.joomla.org/authors/itemlist/user/65-Nicholas-G-Antimisiaris Joomla documentation: http://docs.joomla.org/ Joomla 2.5 essential training: http://www.lynda.com/Joomla-tutorials/Joomla-Essential-Training/95699-2.html Joomla! For beginners guide 2012: http://www.danconia.com/joomla-for-beginners-guide-2012.html Joomla! Developers guide: http://cocoate.com/sites/cocoate.com/files/private/jdev.pdf

References