The Basics of Joomla! Module Creation and Creating a "Send us a question" Module

Exclusive offer: get 50% off this eBook here
Joomla! 1.5 JavaScript jQuery

Joomla! 1.5 JavaScript jQuery — Save 50%

Enhance your Joomla! Sites with the power of jQuery extensions, plugins, and more

$23.99    $12.00
by Jose Argudo Blanco | July 2010 | Joomla! Open Source

To date, Joomla! has been well known as a great content management system (CMS). There are many sites using it throughout the world, some of them having great features that impress their visitors. Most of the time, these appealing and powerful features work thanks to JavaScript.

In this article by Jose Argudo Blanco, author of the book Joomla! 1.5 JavaScript jQuery, we will:

  • Learn the basics of Joomla! module creation
  • Create a "Send us a question" module

(For more resources on Joomla!, see here.)

Building a basic Joomla! module is not that difficult. In fact it's quite easy. Just stay with me, and we will divide the task into some easy-to-follow steps. First of all, we need to create a folder for our module, for example, mod_littlecontact. This folder is where we will place all the files necessary for our module.

For example, one of the files we are going to need is the mod_littlecontact.php file, which is named exactly the same as the folder, but with a .php extension. Let's see what we need to put in it:

<?php
defined('_JEXEC') or die('Direct Access to this location is not
allowed.');
?>
<h1>Just a simple contact form!</h1>

We will look at just the basics. First, defined('_JEXEC') checks whether the file has been included by Joomla! instead of being called directly. If it has been included by Joomla!, the _JEXEC constant would have been defined.

With this PHP file created we need to create another file, an XML one this time. We will call it mod_littlecontact.xml; notice that, again, the name is the same as the folder one. Just create the file, and after that we will place the following contents in it:

<?xml version="1.0" encoding="utf-8"?>
<install type="module" version="1.5.0">

<name>Little Contact Form</name>
<author>Jose Argudo Blanco</author>
<creationDate>2010</creationDate>
<copyright>All rights reserved by Jose Argudo
Blanco.</copyright>
<license>GPL 2.0</license>
<authorEmail>jose@joseargudo.com</authorEmail>
<authorUrl>www.joseargudo.com</authorUrl>
<version>1.0.0</version>
<description>A simple contact form</description>
<files>
<filename module="mod_littlecontact">
mod_littlecontact.php</filename>
</files>
</install>

Most of the contents of this XML file are quite easy to follow and very self-explanatory. In the files section, we have included all the files necessary for our module. Notice that we do not include the XML file itself.

With these two files created, we can give a try to this simple module. Copying this folder into our Joomla! modules folder won't work, as Joomla! requires us to install the extension through the Extensions | Install/Uninstall menu. So, what do we need to do? Just compress these two files into a ZIP file by using any tool of your liking. At the end we will need to have a mod_littlecontact.zip file with the following two files inside:

  • mod_littlecontact.php
  • mod_littlecontact.xml

Installing our module is done exactly as with any other modules. Go to the administrator screen of our site, then go to the Extensions | Install/Uninstall menu, search and select the file, and then click on Upload File & Install button.

If all goes OK, and it really should, we will be able to find our module listed in Extensions | Module Manager, as seen in the following screenshot:

The Basics of Joomla! Module Creation and Creating a "Send us a question" Module

We can click in the module name, just as we would do with any of the others. If we enter the administration panel of the module we will see a screen very much like the other modules, as Joomla! standardizes this screen. Just take a look at the Details zone, which will look like the next screenshot:

The Basics of Joomla! Module Creation and Creating a "Send us a question" Module

He re we can select the parameters we want, and enable the module. This time we will place it in the module_7 position of our template. Also note that the description is the one that we place in the module XML file:

<description>A simple contact form</description>

After we have enabled the module, we will be able to see it in the frontend, in the module position we have selected:

The Basics of Joomla! Module Creation and Creating a "Send us a question" Module

There's not too much for now, but it's working! Now we will enhance it and convert it into a contact form.

Note that now that we have installed our module, a new folder will have been created into our Joomla! installation. We can find this folder in the modules folder, it will be called mod_littlecontact.

So now we have this structure on our Joomla! Site:

modules/
mod_littlecontact/
mod_littlecontact.php
mod_littlecontact.xml

As the module is already installed, we can modify these files, and we will be able to see the changes without needing to reinstall it.

We have just accomplished our first step; the basics are there, and now we can concentrate on making our modifications.

Creating a "Send us a question" module

One of the first things we are going to create is an empty index.html file; this will be used so that no one can take a look at the folder structure for the module. For example, imagine that our site is installed in http://wayofthewebninja.com. If we go to http://wayofthewebninja.com/modules/mod_littlecontact/ we will see something like the next image:

The Basics of Joomla! Module Creation and Creating a "Send us a question" Module

If we try to click on mod_littlecontact.php, we will see the following phrase:

Direct Access to this location is not allowed.

That's because the code we added to our file is as follows:

<?php
defined('_JEXEC') or die('Direct Access to this location is not
allowed.');
?>

Of course, we don't want people to be able to see which files we are using for our module. For this place, we used the empty index.html file mentioned in the modules/mod_littlecontact folder.

This way, if anyone tries to go to http://wayofthewebninja.com/modules/mod_ littlecontact/, they will see only an empty screen.

Good, now note that when we add any file, we need to reflect it on the mod_littlecontact.xml file in the files section:


<files>
<filename
module="mod_littlecontact">mod_littlecontact.php</filename>
<filename>index.html</filename>
</files>

This way, when we pack the file for install, the installation process will take this file into account, otherwise it will be left out.

Once we have done this, we are going to create another file, a CSS one this time, so we can put our styles in it. For this we are going to first create a new folder, also called css. It will be placed in modules/mod_littlecontact/. Inside that folder we will create a file called styles.css; this file also needs to be declared in the XML:

<filename>css/styles.css</filename>

In this modules/mod_littlecontact/css/styles.css file we are going to place the following code:

#littlecontact h1{
font-size: 18px;
border-bottom: 1px solid #ffffff;
}

But then, if we are to apply these styles, we need to load this CSS file. How are we going to do this? Open the modules/mod_littlecontact/mod_littlecontact.php file and modify it as follows:

<?php
defined('_JEXEC') or die('Direct Access to this location is not
allowed.');

JHTML::stylesheet('styles.css','modules/mod_littlecontact/css/');

?>
<div id="littlecontact">
<h1>Just a simple contact form!</h1>
</div>

There's not much change here; we have enveloped our previous content in a DIV, with the littlecontact ID, so that we can target our styles. This is the easy part, but there's also an important one, shown as follows:

JHTML::stylesheet('styles.css','modules/mod_littlecontact/css/');

We are using the JHTML::stylesheet method to create a link, in our header section, to our CSS file. In fact, if we check the source code on our frontend, we will see:

<link rel="stylesheet" href="/modules/mod_littlecontact/css/
styles.css" type="text/css" />

This way our stylesheet will be loaded, and our module will look like the next screenshot:

The Basics of Joomla! Module Creation and Creating a "Send us a question" Module

As we can see, our styles have been applied. The JHTML::stylesheet method is quite easy to use, the first parameter being the file and the second one being the path to the file.

Now we are going to prepare our simple form. Again we will modify our mod_littlecontact.php file, and now it will look more like the following:

<?php
defined('_JEXEC') or die('Direct Access to this location is not
allowed.');

JHTML::stylesheet('styles.css','modules/mod_littlecontact/css/');

?>
<div id="littlecontact">
<h1>Just a simple contact form!</h1>

<form action="index.php" method="post" id="sc_form">

<label>Your name:</label><br/>
<input type="text" name="your_name" value="" size="40"
class="sc_input"/><br/><br/>

<label>Your question:</label><br/>
<textarea name="your_question" class="sc_input" rows="5"
cols="30"></textarea><br/><br/>

<input type="submit" name="send" value="Send"
class="sc_button" />

</form>
</div>

This is a common HTML form. We need some styling here, just to make it look good. Let's make the following minimal changes to our styles.css file:

#littlecontact h1{
font-size: 18px;
border-bottom: 1px solid #ffffff;
margin-bottom: 15px;
}

.sc_input{
border: 1px solid #3A362F;
}

.sc_button{
background-color: #3A362F;
border: 0;
color: #ffffff;
padding: 5px;
}

Most styles are new, and modifications to previous h1 styling have been marked. With this minimal change our module looks a bit better.

You can see it in the following screenshot:

The Basics of Joomla! Module Creation and Creating a "Send us a question" Module

Joomla! 1.5 JavaScript jQuery Enhance your Joomla! Sites with the power of jQuery extensions, plugins, and more
Published: July 2010
eBook Price: $23.99
Book Price: $39.99
See more
Select your format and quantity:

(For more resources on Joomla!, see here.)

Good, now we are going to prepare the send part. Don't worry, this is not going to be hard. But first we will try to separate the logic from the presentation. This is just to have the PHP code and the HTML code separated—much like the way we separated the CSS and HTML.

In order to do this we are going to create another folder, this time called tmpl, the short form of templates. This way we will have modules/mod_littlecontact/tmpl.

Inside that folder we are going to create two files:

  • modules/mod_littlecontact/tmpl/default_tmpl.php
  • modules/mod_littlecontact/tmpl/sendok_tmpl.php

Let's start with the first one, default_tmpl.php:

<?php
defined('_JEXEC') or die('Direct Access to this location is not
allowed.');
?>
<div id="littlecontact">
<h1>Just a simple contact form!</h1>

<form action="index.php" method="post" id="sc_form">

<label>Your name:</label><br/>
<input type="text" name="your_name" value="" size="40"
class="sc_input"/><br/><br/>

<label>Your question:</label><br/>
<textarea name="your_question" class="sc_input" rows="5"
cols="30"></textarea><br/><br/>

<input type="submit" name="send" value="Send"
class="sc_button" />

</form>
</div>

We have just placed the form's HTML code in this file. What about the content of the sendok_tmpl.php file? Place the following code:

<?php
defined('_JEXEC') or die('Direct Access to this location is not
allowed.');
?>
<div id="littlecontact">
<h1>The form has been sent ok</h1>
</div>

This displays a message if everything is OK when the form is sent. Now don't forget to add the following files to our XML file:

<filename>tmpl/default_tmpl.php</filename>
<filename>tmpl/sendok_tmpl.php</filename>

Things are going well, and now we need to decide when to show which template. Just check the mod_littlecontact.php file and remove everything but the following code:

<?php
defined('_JEXEC') or die('Direct Access to this location is not
allowed.');

JHTML::stylesheet('styles.css','modules/mod_littlecontact/css/');
?>

Now add the following code to the previous code:

JHTML::stylesheet('styles.css','modules/mod_littlecontact/css/');

$form_send = JRequest::getVar('form_send', 'notsend');

switch($form_send){

case 'send':
require(JModuleHelper::getLayoutPath('mod_littlecontact',
'sendok_tmpl'));
break;

default:
require(JModuleHelper::getLayoutPath('mod_littlecontact',
'default_tmpl'));

}

?>

There are some interesting things happening here; first we will try to retrieve a variable:

$form_send = JRequest::getVar('form_send', 'notsend');

The JRequest::getVar method tries to get a variable from the $_GET, $_POST, $_REQUEST, $_FILES, or $_COOKIE arrays. The first parameter is the variable name we are expecting, and the second parameter is a default value. In the case that the variable is not set it will be initialized with the value we define here.

Once we have this variable we can use it as a switch to decide which template to load. But how is a template loaded? Very easily, as is shown here:

require(JModuleHelper::getLayoutPath('mod_littlecontact',
'default_tmpl'));

The first parameter is the module name, and the second parameter is the template name. Just remember three things:

  1. If there's no second parameter, the template loaded will be the one named default.php.

    Note that we are using default_tmpl.php, so we need to pass it as the second parameter.

  2. Templates need to be in the tmpl folder.
  3. We don't need to put the .php extension, but only the file name, as the extension is PHP by default. If we were using another extension, such as .php5, then it would be necessary to place it.

With all this in place we need to make one little change to our default_tmpl.php file. We need to add a hidden file to our form, just after the form declaration:

<form action="index.php" method="post" id="sc_form">
<input type="hidden" name="form_send" value="send" />

This will send the form_send variable that we ha ve been talking about with a value of "send". Then the switch will load our sendok_tmpl.php template instead of our default_tmpl.php one.

Go try it out! Now our module is fully functional—well, it doesn't send an e-mail, but it behaves as if it does.

Once you have given it a try, you can continue. We are now going to send an e-mail. We will place the necessary code inside the mod_littlecontact.php file's switch sentence. It will be placed exactly in the send case:

case 'send':

$your_name = JRequest::getVar('your_name', 'No name');
$your_question = JRequest::getVar('your_question',
'No question');

$mail =& JFactory::getMailer();
$mail->setSender('demo@sender.com', 'Wayofthewebninja');
$mail->setSubject('Contact from our site');
$mail->addRecipient('demo@recipient.com');

$body = "Contact form send by user<br/>";
$body.= "-------------------------<br/>";
$body.= "Username: ".$your_name."<br/>";
$body.= "Question: ".$your_question."<br/>";

$mail->setBody($body);
$mail->IsHTML(true);

$send =& $mail->Send();
if ( $send !== true ) {
echo 'Error sending email: ' . $send->message;
}

require(JModuleHelper::getLayoutPath('mod_littlecontact',
'sendok_tmpl'));
break;

This code is quite easy to understand; let's take a look together. First we take the variables sent by the form:

$your_name = JRequest::getVar('your_name', 'No name');
$your_question = JRequest::getVar('your_question',
'No question');

Our next step is to initialize the mailer:

$mail =& JFactory::getMailer();

Set the sender, as follows:


$mail->setSender('demo@sender.com', 'Wayofthewebninja');

Now, write the subject:

$mail->setSubject('Contact from our site');

And, finally, add the recipient:

$mail->addRecipient('demo@recipient.com');

Then we prepare the content for our message, as follows:

$body = "Contact form send by user<br/>";
$body.= "-------------------------<br/>";
$body.= "Username: ".$your_name."<br/>";
$body.= "Question: ".$your_question."<br/>";

$mail->setBody($body);
$mail->IsHTML(true);

Note that if you don't want to send the message as HTML, and instead you want to send it as plain text, don't set the IsHTML value. And try to send the message, showing errors if any occur, as follows:

$send =& $mail->Send();
if ( $send !== true ) {
echo 'Error sending email: ' . $send->message;
}

That's it. Now when we send the form, an e-mail will also be sent. Of course, this is very basic; you can read more about sending e-mails with Joomla! at the following link:

http://docs.joomla.org/How_to_send_email_from_components

Now we will place this e-mail code in another file, just to organize it a bit. We will create a helper file, this way our mod_littlecontact.php won't be crowded. This will work in a similar fashion to our template files.

This file will be placed in modules/mod_littlecontact and will be named helper.php. For now only create the file; we will work with it shortly.

But before doing so, we are going to add this file to our mod_littlecontact.xml file, just to ensure that we don't forget about it:

<filename>helper.php</filename>

The content of the helper.php will be as follows:

<?php
defined('_JEXEC') or die('Direct Access to this location is not
allowed.');

class ModLittleContactHelper{
public function SendMail($your_name, $your_question){

$mail =& JFactory::getMailer();
$mail->setSender('josemanises@gmail.com',
'Wayofthewebninja');
$mail->setSubject('Contact from our site');
$mail->addRecipient('josemanises@gmail.com');

$body = "Contact form send by user<br/>";
$body.= "-------------------------<br/>";
$body.= "Username: ".$your_name."<br/>";
$body.= "Question: ".$your_question."<br/>";

$mail->setBody($body);
$mail->IsHTML(true);

$send =& $mail->Send();

return $send;
}
}
?>

After taking a look at this code, you will notice that it's our old, small piece of code that sent the form. It has been placed inside a method called SendMail, which takes two parameters. And everything is placed inside a class called ModLittleContactHelper.

We could have given any name we liked to this class and method, but these names look fine. And now that our helper file is ready, we are going to make good use of it.

For this we are going to return to the mod_littlecontact.php file. I'm going to place it in full here, so that we can take a detailed look at it:

<?php
defined('_JEXEC') or die('Direct Access to this location is not
allowed.');

require_once(dirname(__FILE__).DS.'helper.php');

JHTML::stylesheet('styles.css','modules/mod_littlecontact/css/');

$form_send = JRequest::getVar('form_send', 'notsend');

switch($form_send){

case 'send':

$your_name = JRequest::getVar('your_name', 'No name');
$your_question = JRequest::getVar('your_question',
'No question');

$send = ModLittleContactHelper::SendMail($your_name,
$your_question);

if ( $send !== true ) {
echo 'Error sending email: ' . $send->message;
}

require(JModuleHelper::getLayoutPath('mod_littlecontact',
'sendok_tmpl'));
break;

default:
require(JModuleHelper::getLayoutPath('mod_littlecontact',
'default_tmpl'));
}

?>

The first difference is in the following line:

require_once(dirname(__FILE__).DS.'helper.php');

With this line we include our helper file. Our next step is to make use of it by calling the method that we have just created, as follows:

$send = ModLittleContactHelper::SendMail($your_name, $your_question);

We also save the result to the $send variable so that we can check later if the e-mail has been sent.

We are done! Well at least in a very simple way. Sure we could do lots of things to enhance this little module, but we are going to concentrate on only two of them: sending the mail without needing to reload the page, and checking some required fields.

Summary

In this article, we learnt the basics of Joomla! module creation and also created a simple module. In the next article, we will add some new features to our module, which are intended to make a better form.


Further resources on this subject:


Joomla! 1.5 JavaScript jQuery Enhance your Joomla! Sites with the power of jQuery extensions, plugins, and more
Published: July 2010
eBook Price: $23.99
Book Price: $39.99
See more
Select your format and quantity:

About the Author :


Jose Argudo Blanco

Jose Argudo Blanco is a web developer from Valencia, Spain. After finishing his studies he started working for a web design company. After working for six years for that company and some others, he decided to work as a freelance.

Now, after some years have passed, he thinks it's the best decision he has ever takena decision that let him work with the tools he likes, such as CodeIgniter, Joomla!, CakePHP, JQuery, and other well-known open source technologies.

For the past few months he has also reviewed some books for Packt Publishing, such as Magento 1.3 Theme Design, Magento: Beginner's Guide, Joomla! 1.5 SEO, Symfony 1.3 Web Application Development, and Joomla! with Flash. The one yet to be published is Magento Development with PHP.

Books From Packt

Joomla! Social Networking with JomSocial
Joomla! Social Networking with JomSocial

Joomla! 1.5 Site Blueprints
Joomla! 1.5 Site Blueprints

Joomla! 1.5 Templates Cookbook
Joomla! 1.5 Templates Cookbook

jQuery 1.4 Reference Guide
jQuery 1.4 Reference Guide

jQuery UI 1.7: The User Interface Library for jQuery
jQuery UI 1.7: The User Interface Library for jQuery

jQuery 1.3 with PHP
jQuery 1.3 with PHP

Nginx HTTP Server
Nginx HTTP Server

NetBeans Platform 6.9 Developer's Guide
NetBeans Platform 6.9 Developer's Guide

Your rating: None Average: 5 (3 votes)
Awsome article dude by
I think that you should improve blog graphics
Great Help! by
Thank you!

Post new comment

CAPTCHA
This question is for testing whether you are a human visitor and to prevent automated spam submissions.
k
4
6
x
5
Z
Enter the code without spaces and pay attention to upper/lower case.
Code Download and Errata
Packt Anytime, Anywhere
Register Books
Print Upgrades
eBook Downloads
Video Support
Contact Us
Awards Voting Nominations Previous Winners
Judges Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software
Resources
Open Source CMS Hall Of Fame CMS Most Promising Open Source Project Open Source E-Commerce Applications Open Source JavaScript Library Open Source Graphics Software