Creating a Site Module

Creating a Site Module for Joomla 3.x – Part 1

When and how is the module run?

If you watched the Joomla 3.x Execution Cycle video, or read the web page, you learned that after Joomla creates the JApplicationSite object that several methods are called to initialize, route, dispatch and finally render the application document for the end user. It is during the render method that modules will be run.

To determine which modules will be run, Joomla will load the template assigned to the current menu link and get a list of all the module positions by gathering up the <jdoc:include ... > tags with the attribute of module set on them. These tags let Joomla know what module positions are available for the template it has loaded and what the module positions are called.

For each module position in the template file, Joomla will look at the current menu selection, identified by an itemid, and look for a list of modules that are enabled for that menu selection for the current module position. Once Joomla has the modules that are published it can execute the module.

Folder layout for a Module.

If you watched the video on the Joomla file system layout, you learned that Joomla organizes itself in a series of folders, where each folder holds a specific type of information. For example, when you look at a newly installed copy of Joomla’s root folder, you see the files and folders that make up the ‘Site’ application or sometimes called the front end.

Modules written for the front end or site application, are located in a folder named modules. When we write our own modules we have to store them in this folder. Joomla “knows” that this is where the module extensions are stored and to put them anywhere else will not work.

If you examine the modules folder, you will see a list of folders under it. Notice all the folder names start with “mod_”. This is yet another convention that Joomla uses to locate the modules. Each module that has been installed on the front end of Joomla will be located in one of these folders. Which one? Well, the mod_ is followed by the name of the module. So looking at the list of installed modules you will see, for example, mod_menu. This folder contains all the code needed to run the Menu Module that you see on your web page.

When we write our own modules, we must follow the same convention in order for Joomla to be able to execute the code for our module. So if we were to write a module called Random Quotes, it would be stored in a folder under modules named mod_random_quotes. Likewise, if we were to write a module called Lucky Number that displays a random lucky number to the user, it would reside in a folder called mod_lucky_number inside the modules folder.

Lastly, if you look in one of these mod_ folders, you will see a php script of the same name. For example, looking inside the mod_menu folder reveals that a mod_menu.php file exists. It is this file that Joomla will execute when the module is run. In our example modules above, the Random Quotes module will contain the file named mod_random_quotes.php inside the mod_random_quotes folder all located in the modules folder in the sites root folder.

Understanding this hierarchy is important to creating modules for Joomla. Joomla expects that these files and folders are laid out in a certain way, and if they are not, your code will not be executed.

As a final note, you will see an index.html file in most every folder in Joomla’s file system. This file exists to prevent the web server from displaying a list of files given in a certain folder. The included html file need not contain much code. For example when looking at the index.html files that are installed with Joomla, they contain only:

<!DOCTYPE html><title></title>

This is enough information to allow the web server to send something to the end user and prevent a directory listing. For additional security, we will follow the same example.

Minimum requirements to install a Module.

So, what is the absolute least amount work required to install a module into Joomla? Believe it or not, it isn’t much. In order to install a module in Joomla, only two files are needed and they are rather simple to create. We will have to create a manifest file and the main php file for the module. Let’s start with the simplest of the two, the module’s php file. But first, we need to determine what we plan to call the module. Since this is only a demonstration of how to write the smallest amount of code to create a module, I think I will call my module Smallest. Feel free to call yours anything you like, just remember to insert the name you came up with where it is required.

Let’s get started. Create a folder somewhere on your computer to hold your project. I will create a folder called “Joomla Projects” on my desktop as a general container to hold my Joomla extension projects. Inside this folder I will create a mod_smallest folder to keep the code for my module. By using Joomla’s naming convention for my project folder, I know at a glance that this folder contains a module and the particular module is called smallest.

Once you have created your project folder, navigate into it and create an new file called mod_smallest.php, or in the event that you called your module something else you will want to name the file mod_<your-module-name>.php. Remember, this file will get installed into Joomla and we have to use the naming conventions that Joomla requires.

Now, open your php file up in a text editor. Since I run Ubuntu Linux, I will be using gedit to edit my file. With the file open, type the following code.

<?php
echo ‘Hello from my module!’;

That’s all you need, so save and close the file. After we install and set up the module in Joomla’s back end and the module gets executed, it will display the message to us, “Hello from my module!”

Next create another file in your project folder named mod_<your-module-name>.xml. In my case, the file will be called mod_smallest.xml. This file is what is usually referred to as the manifest file or install file. When you create an extension, Joomla reads this file to determine what kind of extension it is, and where is should get installed. It contains all the information that Joomla needs to get your code copied, database tables created, language strings and much more. But don’t worry about all that for now. Remember, we want the least amount of code to get our module to install and work.

Open your xml file with your editor and enter the following code:

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.5" client="site" method="upgrade">

   <name>Smallest Module</name>

   <files>
      <filename module="mod_smallest">mod_smallest.php</filename>
      <filename>mod_smallest.xml</filename>
   </files>

</extension>

With the code entered, save the file. With your file saved, let’s talk just a little about this file and what it means. The first line of code:

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

This line of code defines the context of the file. This tells the reading application that this is an xml file, using version 1.0 of the protocol and that the file is encoded in utf-8. UTF-8 is a type of character encoding that uses 8 bits to define a character. The thing to take away here is that all xml files for Joomla will require this line at the top. The next line of code:

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

The <extension></extension> tags inform Joomla of what type of extension is being installed. Joomla uses the attributes contained inside the extension tag to control the location and what type of extension is being installed. In our case the attribute of type is set to module, letting Joomla know that it is to install a module. The next attribute, version, tells Joomla which version of Joomla the extension was developed for. We are using the value of 3.5 here because that is the version of Joomla we are developing for. The client attribute comes next and it informs Joomla where the extension is to be installed. In our case, we are telling Joomla that this extension is a site, or front end extension. If we were developing an extension for the administrator application or back end, we would set this value to administrator. Finally, the last attribute is called method. We have this set to upgrade meaning that if the extension is already installed it will perform an upgrade to it. The other option would be to set this attribute to install. When setting to install, if the extension already exists, Joomla will exit the install process. Using upgrade, even with the same version of the extension will cause Joomla to overwrite the files with the files contained in the file list. Generally speaking, it would be best to set this attribute to upgrade.

The next line:

<name>Smallest Module</name>

The name element is not strictly required, but if you don’t supply it, when Joomla installs your extension, it will have no name listed in the title field on the back end making it difficult to manage your module. The name you supply inside the name tags will be used to populate the name of the module in the back end where you would manage it. Later we will learn that the name you use here becomes important when we start internationalizing our extensions with language strings.

Finally we have the following lines:

<files>
   <filename module="mod_smallest">mod_smallest.php</filename>
   <filename>mod_smallest.xml</filename>
</files>

The <files></files> tags tell Joomla what files will need to be copied to the server to execute the module. Inside the files block will be a list of files that Joomla will copy to the extension’s folder under the modules folder in the site root with each file enclosed in a <filename></filename> tag. In this example, we only have two files; mod_smallest.php and mod_smallest.xml. You will notice that the modules php filename tag has an attribute of module=mod_smallest. This attribute tells Joomla a few things.

Joomla will use the value of this attribute to name the folder the module will be located in under the modules folder. In this example it will be named mod_smallest
Joomla uses this value to access the XML file when managing the module. If we used the value of mod_smallest, Joomla will expect the XML file to be named mod_smallest.xml.
Finally, it tells Joomla that this is the file that should be executed when the module is called on. Again, it expects the name to be the same as the value set on this attribute and in our example that would be mod_smallest.php

Now I must make a couple of clarifications. I told you earlier that we must name our module mod_<module-name>, but this isn’t exactly true. In the above example, I could have named the module smallest, but in doing so, I would have to call the entry php file smallest.php, the manifest file would have to be named smallest.xml and the filename module attribute would have to be set to smallest. This will work and your module will still run, but what you will discover is that the folder created for your module in the modules folder will be called smallest. I think it is best practice to follow conventions used in Joomla, and prefix these files with mod_.

The next thing to clarify is the XML manifest file. You will have noticed that it is included in the files section of the manifest file with <filename>mod_smallest.xml</filename>. Technically, you do not have to include the manifest file in the files list because Joomla will copy it over anyway. To include it does no harm and I think it makes it clear that the file will be copied over on the install.

Installing your Module

With the basic files created for the module, we are now in the position to install it to Joomla. To do so, all we need to do is to zip these two files together. It does not matter what you name this zip file, but generally I name mine the extension type with the version number. We will discuss versioning your extension later. I named my zip file mod_smallest.zip.

With your archive created you can now install it in Joomla by going to the back end and selecting Extensions | Manage | Install from the main menu. In the section that reads Upload & Install Joomla Extension click the Browse button and select the zip archive you made above. Finally, click the Upload & Install button to install your module.

If all went well you will get a message informing you that the installation of the module was successful. If you received an error, double check your filenames and particularly your XML file. If you copied and pasted from this documents, check that your XML file contains single quotes and not something else.

To see our work in action we need to enable the module, assign it to a module position and finally give it a menu assignment. To do this, select Extensions | Modules from the main menu. You should see your module in the list of installed modules. It will be listed with the same name that you gave it in the manifest file with the <name> tag. Click on the title of your module to open the edit page. On the Module TAB, select the position in the template you would like your module displayed. In my case, I am using the Protostar template so I selected position 7 which is the right hand side. Next enable your module by changing the status to published. Finally, click the Menu Assignment TAB and on the Module Assignment drop down list select “On all pages”. Click the Save & Close button to save your changes. Now go to the front end of the site and click the Home menu link. You should see your module visible on the page. If you do not see it, double check your module settings in the back end.

Some final thoughts

CONGRATULATIONS!!! You have created your very first module for Joomla. Although it is very simple, and much more can be done, it is still a module and runs in Joomla. Until the next tutorial I would suggest you play with the mod_<your-module-name>.php and put something useful in your module. In the next module tutorial we will expand on or basic knowledge by exploring the manifest file and the metadata it should contain. Additionally, I will take a more serious approach when I start the next module. In the meantime, I would suggest reading the article on manifest files located at https://docs.joomla.org/Manifest_files.

END OF TUTORIAL