Mer 06 Oct |
|
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 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.'); ?>
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"?>
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:   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:   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:   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/
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" moduleOne 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>
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{
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">
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/
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">
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:
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:   Joomla! 1.5 JavaScript jQuery
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="http://www.gjcwebdesign.com/fr/" 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="http://www.gjcwebdesign.com/fr/" 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(' Cette adresse email est protégée contre les robots des spammeurs, vous devez activer Javascript pour la voir. ', 'Wayofthewebninja'); $mail->setSubject('Contact from our site'); $mail->addRecipient(' Cette adresse email est protégée contre les robots des spammeurs, vous devez activer Javascript pour la voir. '); $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(' Cette adresse email est protégée contre les robots des spammeurs, vous devez activer Javascript pour la voir. ', 'Wayofthewebninja'); Now, write the subject: $mail->setSubject('Contact from our site'); And, finally, add the recipient: $mail->addRecipient(' Cette adresse email est protégée contre les robots des spammeurs, vous devez activer Javascript pour la voir. '); 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(' Cette adresse email est protégée contre les robots des spammeurs, vous devez activer Javascript pour la voir. ', 'Wayofthewebninja'); $mail->setSubject('Contact from our site'); $mail->addRecipient(' Cette adresse email est protégée contre les robots des spammeurs, vous devez activer Javascript pour la voir. '); $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. Joomla! 1.5 JavaScript jQuery
Add this page to your favorite Social Bookmarking websites                      |
||||
| LAST_UPDATED2 |
