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:

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:

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!