Creating a Site Module for Joomla 3.x - Part 6
Increasing Module Versatility
Sometimes you want your module to be able to display information in different ways and rather than writing different versions of the module to do this, we can use parameters that the administrator can set on the module to do this for us. Parameters make a module more user friendly by adding versatility to it. For example, if you wanted to give the user the option of laying out the information in a bulleted list or a group of paragraphs, you can do this with a parameter. Or maybe you want to give the administrator the ability to show more information in one instance of the module than in another instance, you can do this with parameters.
So, what is a module parameter really? A module parameter is a way to allow you to set variables on your module that the administrator can manipulate when they create an instance of the module that you can access programmatically. By examining the value of the parameters at runtime, we can make decisions based on what the values are.
Let’s create a simple parameter for our Random Quote module so that we can lay some groundwork that we will build on later. We will add a parameter that will allow the administrator to set the title of the module to the Author of the Quotes name. If this parameter is set to yes, then we will programmatically replace the module title with the Authors name and then omit the name from the body of the module, otherwise, we will display the module normally. We will accomplish this by using different views. Let’s get started.
It all starts with Form Fields
Joomla supports parameters for your extension through the use of form fields. Because of this, Joomla has a great number of form fields that are built in and available to the user. Form fields can be used in quite a number of places in your extension. To give you a couple examples, form fields can be used in the edit screen of a component allowing a user to enter in information that Joomla can then use or save to the database, and they can be used as part of your extension as parameters. The administrator can manipulate or set values to these parameters to make your extension more extensible and robust.
If you are familiar with HTML forms, then form fields should be old hat to you. Form fields are used extensively and Joomla is no exception. Joomla uses them, as stated above, in a lot of places. So useful are form fields that Joomla has a class devoted to them and extends their use to make things like validation much easier. To see a complete list of the form fields that Joomla supports please see the following web page.
https://docs.joomla.org/Form_field
Of this extensive list, the fields that would be most useful in our case would be either a select list or a radio button. I think since we are only talking about the choice of yes or no, the the radio field type will suit us just fine.
To add the parameter open the modules XML file and add the lines marked in red. To save space some of the file has been left out, marked by the ellipse you see just before the <files> tag. We will discuss these below.
<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.5" client="site" method="upgrade">
<name>MOD_RANDOM_QUOTE</name>
<author>Joe Hildreth</author>
<creationDate>05 JUL 2016</creationDate>
...
<files>
<folder>language</folder>
<folder>tmpl</folder>
<folder>sql</folder>
<filename>helper.php</filename>
<filename>index.html</filename>
<filename module="mod_random_quote">mod_random_quote.php</filename>
<filename>mod_random_quote.xml</filename>
</files>
<config>
<fields name="params">
<fieldset name = "basic">
<field type = "radio"
name = "authortitle"
label = "MOD_RANDOM_QUOTE_PARAM_AUTHORTITLE"
default = "0"
description = "MOD_RANDOM_QUOTE_PARAM_AUTHORTITLE_DESC"
class = "btn-group btn-group-yesno">
<option value = "authortitle">JYES</option>
<option value = "0">JNO</option>
</field>
</fieldset>
</fields>
</config>
</extension>
Notice we have a whole new section added to the XML file all contained within the <config> tags. The <config> tag will hold all the fields associated with our parameters and is required for us to be able to use them. Next comes the <fields> tag. The <fields> tag takes one attribute called name. I am unsure of what the name tag is for. I think it either represents the params column in the modules table or perhaps it represents the $params variable to access the values. I will clarify this in the future if I am able to find out. The only thing I know for sure is that the name=”params” has to be there for parameters to work correctly in Joomla.
Next we come to the <fieldset> tag. Fieldsets allow us to break our parameters into logical groups and the name attribute of the tag tells Joomla where to place the fields on the manage module screen. If you use the attribute of name=”basic” the fields will be placed on the module tab of the module screen. If you use name=”advanced” the fields will be place on the Advanced tab of the module screen. Using any other value for this parameter causes Joomla to create a new tab in the module screen. If you do this, Joomla will look for a language string of COM_MODULES_<name>_FIELDSET_LABEL for the text to place on the tab. If the language string is not found, it will place the language string text on the tab in its place. The <name> portion of the language string will have the name that you put in the name attribute of the fieldset. For example if you used a fieldset tag that looks like the following:
<fieldset name=”myfieldset”>
Joomla will look for and use the language string of COM_MODULES_MYFIELDSET_FIELDSET_LABEL. To use this language string, you would place it in the language.ini file in your modules language folder.
Within the fieldset you will place all the fields that you wish to use. Remember, there are a bunch available to use, but in our case we are using a radio button. Each field has a number of attributes associated with it. Some attributes are required while others are not. To get the details for a particular field, go to the page listed above and on that page click the field you are interested in. In our case we want to use a radio button and if we click on the link we will be taken to the following page:
https://docs.joomla.org/Radio_form_field_type
On this page we see the all the requirements of using radio button form fields on our module. Take the time to look at the pages for different fields to get an idea of how they work. I will cover the radio button attributes now.
type=”radio” – The type attribute is mandatory and for a radio button must be set to radio to work.
name=”authortitle” – The name parameter is required and is the unique name of the field. This name will be used to store the parameter to the module table and will be used to access the value of the parameter.
label="MOD_RANDOM_QUOTE_PARAM_AUTHORTITLE" – The label is a mandatory attribute and is used to display the field’s label to the user. Like a lot of things with Joomla, the text of this attribute is translatable, so we use a language string here that will be translated in the language file. If no language string can be found it will use the text that it finds here as the label to the radio button.
default="0" – The default attribute is not mandatory but if used will tell Joomla which of the options is the default value and preselect it for the user.
description="MOD_RANDOM_QUOTE_PARAM_AUTHORTITLE_DESC" – The description attribute is an optional one and if used will be a description of what the parameter is used for. This is another attribute that is translatable and again we use a language string. If Joomla cannot find the language string it will use what ever text you place here.
class="btn-group btn-group-yesno" – The class attribute is optional but if used allows you to apply a CCS class to the form field. Joomla comes with bootstrap and in this case we are using two classes supplied with bootstrap to style our radio buttons. These styles place them in a button group and styles them with the Yes / No style. Using these styles allow our extension to have the same look and feel other Joomla extensions have.
<option> - The option tags of the radio button holds the values and the text of the selections we wish to present to the user. In our case there are only two, either they want to replace the module title with the author name or they do not. See below.
<option value = "authortitle">JYES</option>
<option value = "0">JNO</option>
The first line above gives the option of Yes. Again we see that the text to be displayed to the user is translatable. Here we are using a Language string that is built in with Joomla for Yes. The value attribute of the option tag will be the value that will be stored in the params field of the module table when the module is saved and will be the value that we check for in our code. The second line is similar to the first except we are using Joomla’s No language string and will store the value of 0.
Now that we have our parameter field in place in the manifest file, we need to add some translations to our language file so the end user can read the label and description. Save and close the manifest file and open the language INI file for editing. If you are following the tutorial as written this will be the language/en-GB/en-GB.mod_random_quote.ini file located in your project directory. Add the following text marked in red to the file.
; Translation strings for the Joomla system to use for user interface
; Translation strings for module in Admin area: Extensions | Modules
MOD_RANDOM_QUOTE="Random Quote"
MOD_RANDOM_QUOTE_DESCRIPTION="Displays a Random Quote."
; Translation Strings for module parameters
MOD_RANDOM_QUOTE_PARAM_AUTHORTITLE="Replace title with author?"
MOD_RANDOM_QUOTE_PARAM_AUTHORTITLE_DESC="Replace the title of the module with the Authors name."
Here we add a comment and two language strings to the INI language file. Recall the the INI language file holds the strings that the user will see during normal use of the Module, while the SYS.INI file holds strings that are used in certain parts of the administrator section of the module. The two language strings that we add here are the strings we placed in the radio field above.
(NOTE: If you have been following this tutorial as it has progressed your INI language file will be empty. I neglected to add the first two language stings when I done that tutorial. If your file does not have these, please add them now. These language strings are used when you are managing the module through the Extension | Manage area of the back end. Please accept my apologies.)
Checking our work
With the parameter and language stings added to the project I think it is a good time to check our work. Zip up the module and install it. When it has been installed click Extensions | Modules to get a list of the modules installed and then click on the Random Quote module. If all went well you should see the following.
On the edit screen of the Random Quote module, you will notice on the module tab that our radio button giving the user the selection of replacing the module title with the Author’s name is there. That’s great news, we also know that the translation strings are working because we are getting the string we provided for the label and the built in Joomla strings for Yes and No. But wait a minute, we wanted radio buttons and these look nothing like what we are used to. Well that is because we placed a class on the radio button using the available bootstrap classes. Looks pretty nice, don’t you think? To check that the description language tag is being translated, mouse over the label and look at the tooltip that pops up. You will see it there. Now, if you change the value of the parameter and save the changes, they will be written to the params field of Joomla’s module table for our module. Pretty cool, huh?
Accessing our parameter from code
Well, being able to create parameters that Joomla can save and give us access to is great but we need to be able to see what that value is and act upon it. Now we need to write the code that will allow us to do just that. However, before we do that we need to make a design decision.
In my mind, the user will decide whether they want the quote module to have the title they assigned it or it will be replaced with the author’s name. This will create two different ways of viewing the information we are wanting to show. So, to implement this, we will create an additional view called authortitle to go along with our already present default view. To decide which one to use, we will examine the authortitle parameter we set up and if the user selected yes, then we know that is the view we want to show. I will talk a little more on this when I get to the code.
The second option would be to access the parameter in the view and change it accordingly. This would work but I think it makes it a little more difficult for a person to style if there is more code in the view than really needs to be. Keep in mind though, either way will work just fine.
Picking at the entrails
When Joomla runs it creates the application object and a number of other useful objects that we can leverage to our own will. If in the modules PHP file we were to write a line like the one below, we would get a rather long list of variables that have been created and are accessible by our module.
var_dump(get_defined_vars());
Two of the objects created that are useful to us is a JRegistry object called $params and a PHP stdClass object called $module. So let’s take a look at them in turn.
$params – JRegistry Object
Joomla has a class called JRegistry that is a data store to hold application data and provides a number of methods to easily access the data contained in it. The JRegistry Class is used throughout Joomla to hold certain types of information. For example, the configuration file for Joomla can be accessed through the JRegistry Class. In our example, when the module is created, Joomla will create a new JRegistry object to hold the parameters of our module and assign it to the $params variable. To access the values stored in the $params variable we will need to use the Class Methods that JRegistry provides for us.
$module – stdClass Object
In addition to the $params variable above, Joomla will also create a PHP stdClass object and place in it information about our module. For example it will contain the title, the name of the module the position and other information. We are most interested in the title variable, as it holds the title assigned to the module and we can leverage this to change it if we want to.
If you are interested in exploring this more read on, otherwise skip to the next section. Go to your module and set the position to something like myposition, then create an article and place in the body of the article the following text.
Save the article and create a menu entry for it. When you load this article by clicking the menu link for it, it will load the module in the component area. We are doing this so that we have more room for the output of the module to display. Finally, in the modules PHP file add the line var_dump(get_defined_vars()); somewhere near the top. When the module runs you will see the list of defined variables that are available.
Putting it all together
At this point we have enough information to put it all to use. First we will create the new view. In the tmpl folder of your project directory create a file named authortitle.php and place the following code in it.
<?php
defined('_JEXEC') or die;
echo "<p>"{$quote->quote}"</p>";
echo "<p><em>— {$quote→source}</em></p>";
If you examine this file you will see that it is the same as the default.php file for the default view except we are not printing the author’s name. We only print the quote and the source. This is all we need to do here. Save and close the file.
Next open the components PHP file from your project directory and add the following code marked in red. I will cover what this does below.
<?php
defined('_JEXEC') or die;
// Include the mod_random_quote helper functions only once
require_once __DIR__ . '/helper.php';
$quote = ModRandomQuoteHelper::getRandomQuote();
// Determine which view to use, if no view is stored in the parameter we
// will set the value to 'default'
$view = $params->get('authortitle','default');
// If the view is set to authortitle, make some changes
if ($view == "authortitle") {
// Set the title of the module to the Author's Name
$module->title = $quote->name;
// Change the size of the header tag to prevent line wrapping
$params->set('header_tag','h4');
}
// If the authortitle was set to No, then the value of the parameter
// will be '0'. In this case we want to set the view to 'default'
if ($view == "0") {
$view = "default";
}
require JModuleHelper::getLayoutPath('mod_random_quote', $view);
I have commented the code above but we will cover it in detail.
$view = $params->get('authortitle','default');
First we get the view from our parameter. Remember, when we created the parameter we gave it a name of authortitle, and its value will be either authortitle or 0. If the module was installed but the user did not specifically set this parameter it will not be in the params field on the module table in the database. So to prevent something from going awry we use the JRegistry::get() method passing a second parameter. This parameter tells the method that if this variable does not exist then return the following value. In this case, if authortitle is not there it will return the value of default which is the name of the view we want to use if the module has not been set to replace the title with the author’s name.
if ($view == "authortitle") {
Next we check to see if our $view variable has the value of authortitle. If it does then we know that user wants to show the author’s name in the title.
$module->title = $quote->name;
Using the $module stdClass Object that Joomla provides us we set the module’s title to the author’s name we received from the database when we grabbed the random quote.
$params->set('header_tag','h4');
Finally, we use one of the other modules parameters and reduce the header tag from h3 to h4. This is only for aesthetics. When a longer name is printed using the h3 tag it will break across two lines. Reducing the size of the header helps prevent this from happening. Remember that the $params variable is a JRegistry object so we use the JRegistry::set() method to set the value of the header_tag variable to h4. If you are wondering were these other parameters are coming from, they are picked up in the Extension | Module area of the back end where you can set them for the module. Joomla makes it easy to change these parameters on the fly.
if ($view == "0") {
Next we check to see if the view is set to 0. Remember that if athortitle is turned off, the value saved is 0. I done this because for the bootstrap Yes/No class to work, the No value has to be 0. If we would have used a value of default, for example, both of our buttons would have been green. I only done it this way for appearance sake on the back end.
$view = "default";
If the value of authortitle was 0 then we know this is the default view, so we assign default to the variable.
require JModuleHelper::getLayoutPath('mod_random_quote', $view);
Lastly, we call the view. This code is identical to our last version except instead of calling a specific view on the second parameter, we instead use our $view variable. Now, it will get either the default view or the authortitle view based on the value of the $view variable which was set in the code above.
Testing our code
With the edits done to the modules PHP file, we can save and close it. Zip the project up and install it.
Go to Extensions | Modules and click on the Random Quote module. Make sure the Replace Title with Author parameter is set to No and click save. Now go to the front end and take a look. The title of the module should look normal with the title being set to Random Quote. Now go back to the back end and change the option to Yes and save it. Go to the front end and refresh the screen. You should now see the title of the module has been replaced with the name of the Author. See the image below.
Notice that the name is smaller that the other module titles. Remember we set it smaller by changing the header_tag parameter to a h4.
Giving our extensions parameters gives us a lot of flexibility for our projects. Joomla makes it easy to add and access these parameters through fields added to the XML file and the $params JRegistry object that it creates for us when our module runs.
In the next module episode we will talk about versioning our module and how upgrades work. Thank you for taking the time and if you have any questions, feel free to go to http://www.myheap.com and use the contact link to send me a message. I will do my best to answer them.
END OF TUTORIAL
