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:
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:
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:
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:
default.php
.
tmpl
folder.
.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 have 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('[email protected]', 'Wayofthewebninja'), $mail->setSubject('Contact from our site'), $mail->addRecipient('[email protected]'), $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('[email protected]', 'Wayofthewebninja'),
Now, write the subject:
$mail->setSubject('Contact from our site'),
And, finally, add the recipient:
$mail->addRecipient('[email protected]'),
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
Or you could also read the book "Mastering Joomla! 1.5", available from Packt. Each one of these is a good option for learning more.
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('[email protected]', 'Wayofthewebninja'), $mail->setSubject('Contact from our site'), $mail->addRecipient('[email protected]'), $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. Keep reading!
18.191.168.203