Joomla! Documentation™

Articles in this Series

1. Over/Step by step to a Joomla Module - Basic
2. Over/Step by step to a Joomla Module - Installation package
3. Over/Step by step to a Joomla Module - Data retrieval and styling
4. Over/Step by step to a Joomla Module - Overrides
5. Over/Step by step to a Joomla Module - Advanced installation
6. Over/Step by step to a Joomla Module - A form and ajax

This is a multiple article series on how to develop a module for Joomla! version Joomla 3.x. We go step by step from basic functionality to some more advanced. At the end of the tutorial we'll use your custom module to show you, how you can use the powerful output override ( = change ) methods provided by Joomla!. The only prerequisite for overrides is that the module or component comply to the Joomla! best practices. Navigate the articles in this series by using the navigation box to the right (the Articles in this series). Start with the first and follow them one by one. The next article builds on the knowledge and the files from the previous.

A Tip!

Should have's to complete this tutorial

You should have some knowledge in web technology but you don't have to be an expert at all. If you want to customise or even administrate a web site you will have to learn a little of everything e.g, Html coding, Css styling, Php programming, Sql database, using Javascript and about web servers. If you want to develop extensions for Joomla!, in small or large, you better start with a module before you try a larger project with a component. It is also a nice start to get knowledge on how to modify your sites template design. A Joomla! module is similar to a widget in other contexts. Even if plugins are the shortest extension type in sake of code, they require a little more advanced system knowledge to implement.

Introduction

In this step we will extend "Your module" to become an installable extension for any Joomla! 3.x site. e.g. after testing the functionality on your local installation you can upload and install it on your live site with a few clicks.

Language files

The language files hold the textstrings that are used for descriptions, field labels, field descriptions and any other static texts. You can also translate the textstrings for any language code. The default language code is en-GB, Great Britain english. In version 3 the english "translation" is in most cases loaded before any other specific language. i.e. you should always keep those files up to date.

As in the first part of the tutorial we'll use skeleton files. In the folder, where you unzipped the downloaded file, you can find two language files, en-GB.mod_yourmodule.ini and en-GB.mod_yourmodule.sys.ini Copy those to the Joomla! en-GB language folder. path/to/joomla/language/en-GB. You can also find a language folder in the administrator/ path used for backend extensions and all plug ins.

As always, change files named ...yourmodule... to the name you did choose. Open the first file en-GB.mod_yourmodule.ini

en-GB.mod_yourmodule.ini

; Copyright (C) 2014 Joomla Doe
; Translater Joomla Doe
; License GNU General Public License version 2 or later; see LICENSE.txt, see LICENSE.php
; Note : All ini files need to be saved as UTF-8 - No BOM

MOD_YOURMODULE="Your own module"
MOD_YOURMODULE_XML_DESCRIPTION="This is the description of my module. This one in .ini is shown when editing the module in the Module Manager. Yoü can e.g. add some tips to the confuguration and a link to a help page on your site"

At the top we find some comments. As you see, you have to use ; in front of the comments. If you have friendly helpers that translate your extension, it's nice to have a line with the translators name. The use of character set UTF-8 is noted. For the language string constants you should follow the Joomla! best practice i.e. start all language constants with the extension name. The language constants have to be in upper case with _ (underscore) as divider ending with a =. The text has to be within " double quote. Do not use double quote within the text or you will have to find out how to use __QQ__. No line break is allowed!

; An example with double quote
MOD_YOURMODULE_MY_QUOTE="My value is "_QQ_"great!"_QQ_". I like it"

There is no good reference available at the time of writing. Please change this link if a better is found. Specification of language files

Change the two MOD_YOURMODULE, change the first text to a "human" name of your module and change the description. Again: in one line! no line break is allowed!. If you add e.g. a link remeber "_QQ_" for double quotes. Save this file and copy the text except the description content. The second file has almost the same content at this stage. Open en-GB.mod_yourmodule.sys.ini and paste the copied text replacing the text i.e. not the description text.

MOD_YOURMODULE_XML_DESCRIPTION="This is the description of your module. This one in .sys.ini is shown when choosing a new module in the module manager and in the extension manager. Keep this shorter."

Edit the description and save.

The difference between those is that the .sys.ini file is loaded in cases like module lists where no module fields are shown. We´ll see another use of the .sys.ini below.

As promised in the first part of the tutorial, you can now see the reason for using mod_yourmodule as module name in the xml file. Go to Module Manager, click on new. You will find your module with the name from the language file. Next we will fix the description. Before you close the files copy the constant MOD_YOURMODULE_XML_DESCRIPTION-

Open mod_yourmodule.xml from the server and find the description line. Replace the description with your copied language constant MOD_YOURMODULE_XML_DESCRIPTION.

mod_yourmodule.xml - Description

	<description>MOD_YOURMODULE_XML_DESCRIPTION</description>

You can make the same test as before in the Module Manager and you'll see that the description comes from the language files.

Parameters - Options

If you choose your enabled module for edit in the Module Manager you'll se some default options under the advanced tab. Let's add some more options in the xml file and add the used language strings before we create the first installable package.

Add the following where you find the config part. We will see more around form fields in a later tutorial part.

mod_yourmodule.xml - Config

   <config>
      <fields name="params">
         <fieldset name="options" label="COM_MODULES_BASIC_FIELDSET_LABEL"
            addfieldpath="/administrator/components/com_content/models/fields/modal"
	 >
            <field
               name="article_id"
               type="modal_article"
               default=""
               label="MOD_YOURMODULE_FIELD_ARTICLE_LABEL"
               description="MOD_YOURMODULE_FIELD_ARTICLE_DESC" >
            </field>
         </fieldset>
         <fieldset name="advanced">
            <field
               name="load_css"
               type="radio"
               class="btn-group"
               default="1"
               label="MOD_YOURMODULE_FIELD_LOAD_CSS_LABEL"
               description="MOD_YOURMODULE_FIELD_LOAD_CSS_DESC">
                  <option value="0">JNO</option>
                  <option value="1">JYES</option>
            </field>
            <field
               name="load_js"
               type="radio"
               class="btn-group"
               default="1"
               label="MOD_YOURMODULE_FIELD_LOAD_JS_LABEL"
               description="MOD_YOURMODULE_FIELD_LOAD_JS_DESC">
               <option value="0">JNO</option>
               <option value="1">JYES</option>
            </field>
            <field
               name="layout"
               type="modulelayout"
               label="JFIELD_ALT_LAYOUT_LABEL"
               description="JFIELD_ALT_MODULE_LAYOUT_DESC" />
            <field
               name="moduleclass_sfx"
               type="textarea" rows="3"
               label="COM_MODULES_FIELD_MODULECLASS_SFX_LABEL"
               description="COM_MODULES_FIELD_MODULECLASS_SFX_DESC" />
            <field
               name="cache"
               type="list"
               default="1"
               label="COM_MODULES_FIELD_CACHING_LABEL"
               description="COM_MODULES_FIELD_CACHING_DESC">
               <option value="1">JGLOBAL_USE_GLOBAL</option>
               <option value="0">COM_MODULES_FIELD_VALUE_NOCACHING</option>
            </field>
            <field
               name="cache_time"
               type="text"
               default="900"
               label="COM_MODULES_FIELD_CACHE_TIME_LABEL"
               description="COM_MODULES_FIELD_CACHE_TIME_DESC" />
            <field
               name="cachemode"
               type="hidden"
               default="static">
               <option value="static"></option>
            </field>
         </fieldset>
      </fields>
   </config>

In the fieldset options we add an option field "article_id" that we will use later. This field calls a modal window where you can choose an article. Fieldset options is shown in the tab Options in the Module Manager. If you use a fieldset named basic you'll have those fields in the first tab. We also add some standard option fields to the "Advanced" tab. We do not have to add the text constants used in the Advanced part since they are standard. Remains the two strings used for the article field. Well, we added two fields in the advanced tab, load_css and load_js with language strings that need to be added. We'll come back to the use of those options later.

Follow this link to read more about Joomla modules and the Modules Manager

Add strings to language file

Save the xml file and open the language file. The one without .sys.

Add the 6 strings and save.

mod_yourmodule.ini - New strings

MOD_YOURMODULE_FIELD_ARTICLE_DESC="Choose an article to be shown by the module."
MOD_YOURMODULE_FIELD_ARTICLE_LABEL="Article"
MOD_YOURMODULE_FIELD_LOAD_CSS_DESC="You can disable the modules css"
MOD_YOURMODULE_FIELD_LOAD_CSS_LABEL="Load Css"
MOD_YOURMODULE_FIELD_LOAD_JS_DESC="You can disable the modules JavaScript"
MOD_YOURMODULE_FIELD_LOAD_JS_LABEL="Load JavaScript"

Final change to the xml file

Before we create the first installation file we will add the language tags to the xml file below the </files> tag.

mod_yourmodule.xml - Final

   <languages folder="langs">
      <language tag="en-GB">en-GB.mod_yourmodule.ini</language>
      <language tag="en-GB">en-GB.mod_yourmodule.sys.ini</language>
   </languages>

We use a folder named langs here, because we will use the folder language for a trick. If you include other language files just add lines with the correspondent language identifier.

For those of you that have some knowledge of Joomla development: Do not add the /language folder to the xml file. It is autoloaded. i.e. extracted and used in the installation process by default.

Save the xml file.

Create the compressed installation file

Now we have everything to create the first version of the installation file.

Inside the folder you created on yor local system at the start of the tutorial 'somewhere'/j_module_tutorial/new_module you add three sub directories. langs, language and tmpl. Now you copy the files in the other direction. From the web directory to the new one. It should look something like this ( remember - yourmodule - is a placeholder for your choosen module name ):

• .../new_module
  • .../new_module/langs
    • en-GB.mod_yourmodule.ini
    • en-GB.mod_yourmodule.sys.ini
    • anyother-language.mod_yourmodule.in
    • anyother-language.mod_yourmodule.sys.ini
  • .../new_module/language
    • .../new_module/language/en-GB
      • en-GB.mod_yourmodule.sys.ini
    • .../new_module/language/anyother-language
      • anyother-language.mod_yourmodule.sys.ini
  • .../new_module/tmpl
    • default.php
  • mod_yourmodule.php
  • mod_yourmodule.xml

As a last step we'll edit the .../new_module/language/en-GB/mod_yourmodule.sys.ini to show a different message at installation/upgrade.

mod_yourmodule.sys.ini - Installation message

MOD_YOURMODULE_XML_DESCRIPTION="Thank you for installing / update the Your own module. This module displays an article text in a module position. To activate you go to the module manager and edit this module or create a new entry. Select the article you want to show. Please visit www.mysite.com for more information. If you like it please add a review on JED."

If you edit the description text to include a "Thanks" and other informations only relevant directly after the installation / upgrade this is a trick to achieve this. Only .../new_module/langs/mod_yourmodule.sys.ini will be copied and used after the installation.

You can find two short descriptions of alternative handling of the language files at the end of this page.

Now we compress the files. The Zip type is recommended as it has native support by most systems. In Windows you go to the .../new_module folder. Mark the included folders and files, right click and choose Send to → ZIP compressed folder.

Rename the .zip file to mod_yourmodule_1_0_0.zip i.e. including the version number. You should better move this file to another folder. It is easy forgotten NOT to include it, the next time you create a zipped file.

You made a backup before starting the tutorial? Well, only in case of ...

First you uninstall the module to get a complete new installation Extensions → Manager → Manage Look up the module. Filter e.g. Location = Site, Type=Module and/or name.

When the module is uninstalled you go to Install, browse to your installation zip file and click the Upload & Install button. You'll see the description you edited as installation message. Go to the Module Manager. This time you should find an entry in the Module list. Choose this and enable it, as you did after the Discover in the first part of the tutorial. You can also see that the description is the one from your .ini file. To check the description from .sys.ini click on NEW module. This is not the one you saw directly after the installation.

That's it for this part of the module tutorial. The next part will show you how to retrieve data and add some Css styling to your module.

Alternative language files handling

For both alternatives you have to add all language files to subfolders in the /language folder. Be aware that the folder name is mandatory!

You can use the language files from the /langs folder in the example above. Do not add a long description to the .sys.ini files, as it will be used for the module lists. Of course you have to remove the /langs folder, if you want to test by changing the example above.

Resulting folder:

• /language
  • /language/en-GB
    • en-GB.mod_yourmodule.ini
    • en-GB.mod_yourmodule.sys.ini
  • /language/anyother-language
    • anyother-language.mod_yourmodule.ini
    • anyother-language.mod_yourmodule.sys.ini

1. Easiest way

Add a folder tag to the files area in the xml file.

<folder>language</folder>

The folder will be stored in the extensions folder and no files in the core language folder.

2. Traditional way

Add all single language files to the languages tag in the xml file. Be aware of the extra folder name required (= language tag).

   <languages folder="language">
      <language tag="en-GB">en-GB/en-GB.mod_yourmodule.ini</language>
      <language tag="en-GB">en-GB/en-GB.mod_yourmodule.sys.ini</language>
      <language tag="xx-YY">xx-YY/xx-YY.mod_yourmodule.ini</language>
      <language tag="xx-YY">xx-YY/xx-YY.mod_yourmodule.sys.ini</language> 
  </languages>

The files are saved to the core language folder in the traditional way.