View source for Over/Step by step to a Joomla Module - Basic

If you

* have some interest in understanding the Joomla! Cms a little under the hood.
* are new to Joomla and want to be able to modify your site more than per option settings.
* have knowledge in web development but not with the Joomla! Cms

this is something for you.

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== Introduction ===

The first step will show you how to get your own custom module running in just a few minutes. Well, you have of course to subtract the time it takes to read and follow this text from the total time.

If you run into problems, you can´t solve yourself, ask on the various Joomla developer communication channels.

=== Requirements ===

Before we start, some words about the requirements. You need access to a system with version 3.x of Joomla! installed. This with a web server - PHP, MySQL and Apache ( or a Microsoft IIS server ). A very good idea is to install a server on your local system. It will allow you to test any future changes, before you implement it on your live server. You can find documentation and hints how to do that by searching the www for Joomla and WAMP, LAMP, XAMPP, MAMP ...

Example, without preference, from the Joomla! Community Magazine [http://magazine.joomla.org/issues/issue-mar-2013/item/1110-free-e-book-%E2%80%93-introducing-joomla-30-made-easy Installing Joomla 3.0 on local host using XAMPP] There are many users that find MAMP for Mac or WAMP for Windows easier to install and run.

For the coding you need an editor. If you plan to develop in a larger scale you probably want to use an IDE, integrated development enviroment, or already have one. You can find information on alternatives elsewhere. If you only want to follow this tutorial and later make some minor changes (overrides) you can use a simpler editor. Search one for your local system. For Windows is Notepad++ an example. IMPORTANT! The Editor must be able to save the files with Unix type end of line (EOL) and character set UTF-8 w/o BOM (without byte order mark). You have to set this in the settings of the editor you use. This is a Joomla! requirement and may leave you with some surprises, if you don't follow it.

[[Setting_up_your_workstation_for_Joomla_development|More technical documentation]]

=== Prepare files ===

Be sure that you have set error reporting to Development on your development system. {{rarr|System,Global,Server Settings,Error Reporting}} -> Development. Always None on a live system.

OK! If you now have got it all together, let's start. There are some zipped files available. We'll use them as skeletons for the code we create. Download [http://github.com/schnuti/module-tutorial/zipball/master/ !!! replace with Joomla download !!!] to a new folder you can easily find. e.g. 'somewhere'/j3_module_tutorial. Unzip it. As we are in the mood of creating folders add another subfolder e.g. 'somewhere'/j3_module_tutorial/new_module. We will use that in a next tutorial to create the installation file for your module.

Something like this:
<pre>
...
/'somewhere'
  /j3_module_tutorial        *new directory*
    /'unpacked zip'      
      ...                    *the files*
  /new_module                *new directory*
    ...                      *your own module files*
  downloaded.zip          
  mod_yourmodule_x_y_z.zip   *created during tutorial*

</pre>

You should choose another name for your custom module. Development in a FOSS enviroment, free open source software, is not much about entering code. You use available code, copy/paste and make some modifications. At the end of this tutorial you'll have your own module, that you can use as "framework" for your next "module idea". You only have to replace the name you gave the module with a new name.  We'll use "Yourmodule" throughout the tutorial. Always substitute this with your chosen name! Most of the times you have to use lower case as now with the directories and filenames. You do not have to understand every detail of the code lines. Just copy/paste and change the module name. You can for sure find deeper information about your special interests in web development in other sources. 

Look up the Joomla! root directory on your test system. It depends on your server and Joomla! installation. For Wamp it might be c:\wamp\www\joomla. For XAMPP c:\xampp\htdocs\joomla. Here you'll find a modules directory where you create a subdirectory mod_yourmodule. Don't forget to use your own name! We also need a mod_yourmodule/tmpl directory.

In this step we'll only use 3 files. mod_yourmodule.xml - the so called manifest file that controls the installation and in the module case holds any configuration options, mod_yourmodule.php is the start up file / entry point. default.php holds the code for output. The latter can be named otherwise and is also called template or layout. Somewhat confusing as template and layout is used also in other contexts.

Now you copy mod_yourmodule.xml and mod_yourmodule.php to your path/to/joomla/modules/mod_yourmodule directory. Rename! You copy default.php to path/to/joomla/modules/mod_yourmodule/tmpl.

After you created the 2 new directories and copied the 3 new files your Joomla path should look like below.
<pre>
...
/media
/modules
  ...
  /mod_yourmodule          *new directory*
    /tmpl                  *new directory*
      default.php          *new file*
    mod_yourmodule.php     *new file*
    mod_yourmodule.xml     *new file*
  ...
/plugins
...
</pre>

=== The modules xml file ===

Open mod_yourmodule.xml with your editor. We'll have a look at what we have there and make some modifications.

More information about [[Manifest_files|Manifest files]]. We will come back to this file more than once to add more tags and definitions.

===== mod_yourmodule.xml =====

<source lang="xml">

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.3.0" client="site" method="upgrade">
    <name>mod_yourmodule</name>
    <version>1.0.0</version>
	<creationDate>August 2014</creationDate>
    <author>Joomla Doe</author>
	<authorUrl>www.yourmodule.org</authorUrl>
 	<authorEmail>joomla.doe@yourmodule.org</authorEmail>
	<copyright>Copyright (C) 2014 Joomla Doe</copyright>
	<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
    <description>Your own first custom module.</description>
    <files>
        <filename>mod_yourmodule.xml</filename>
        <filename module="mod_yourmodule">mod_yourmodule.php</filename>
        <folder>tmpl</folder>
    </files>
    <config>
    </config>
</extension>

</source>

The content of the xml file is almost self explaining. We define the extension as a module for Joomla! versions 3.3.0 and above. 3.3.3 is the latest version at the time of creating the tutorial Upgrade means that we leave to the installer program to decide, if it is a new installation or an update/upgrade. The name, the version and the date of the extension. Be extra careful with the module name. Any errors will stop the installation. We use mod_yourmodule as name and will come back to the reason in a later part. Information about the author with contact data. Copyright and license. If the module will be for your own private use only, you don't need all of it. It is however a good practice to include it.

In the description you obviously explain what the module is supposed to do.

In the files part you define what files and folders are included in your module. folder has the effect that all included files will be copied from your packed installation file to that directory (=folder). You don't have to include mod_yourmodule.xml here as it always will be copied.

Comment: We did not include any index.html files. These were used to prevent users to attempt to list the content by pointing their browser to these folders. Joomla! has dropped this requirement. Acces is blocked by your .htaccess / web.config file if properly set up. The default of those files include the needed settings.

We'll come back to &lt;config&gt; when we extend the functionality. It stays empty for now.

Edit this file and replace the data with your own name/modulename.

Save and close mod_yourmodule.xml

=== The start up file ===

Now we'll have a look at the entry point file mod_yourmodule.php.

===== mod_yourmodule.php =====
<source lang="php">

<?php
/**
 * package     Your module
 * copyright   Copyright (C) 2014 Joomla Doe
 * license     GNU General Public License version 2 or later; see LICENSE.txt
 */

defined('_JEXEC') or die( 'Restricted access' );

require JModuleHelper::getLayoutPath('mod_yourmodule', $params->get('layout', 'default'));

</source>

Not more than this is needed for the most basic module we develop in this first tutorial part.

You tell the system that this is php code and write a comment. You can find example comments in any Joomla! core php file or any 3.d party extension. You can add more information if you like but do not overdo. If you use functionality from another developers in the code it's a nice practice to mention that. Something like : this is a fork of mod_yourmodule by Joomla Doe. 

The line defined(... has to be included! It prevents users from running this php code from outside of Joomla!.

The last line calls the default.php file that includes the output commands ( name without php ending ). You can see that the confusing word layout is used. Here it means a file in the tmpl folder.

{{Tip|Do not add a php closing tag ' ?>' at the end of a php file. Add an empty line at the end of files.}}

Edit the module name and save. Do not close it if your editor allows to hold two or more files open.

If you want to know more about Joomla! coding standards: [http://joomla.github.io/coding-standards/ joomla coding-standards] Contibutions to Joomla! core development must follow those standards.

More for advanced developers: [[Joomla_CodeSniffer|Joomla CodeSniffer]] and [https://github.com/joomla/coding-standards/tree/master/IDE joomla/ coding-standards - IDE]

=== The output/template/layout file ===

The last file to edit before we enable the module for the frontend pages is the default.php

===== default.php =====
<source lang="php">

<?php
/**
 * package     Your module
 * copyright   Copyright (C) 2014 Joomla Doe
 * license     GNU General Public License version 2 or later; see LICENSE.txt
 */

defined('_JEXEC') or die( 'Restricted access' );
?>
<h3>From your first module</h3>
<p>This is the content</p>

</source>

Copy the comments part - that you changed - from the former php file and paste it here, replacing the comment. After the obligatory defined(... line we close the php part with ?>. The rest is at your disposal. Use the knowledge you have of html code to show text on the frontpage. Alternatively you can write a very short article in the Joomla! backend, toggle the editor and copy the source code to the php file. If you do, save the article and note the article. We'll use an article as source in a later step.

After saving the file we are ready to enable your custom module on the frontend.

=== Install and enable the module ===

{{Tip|Before you proceed it might be a good idea to backup your test site. Well, only in case of ...}}
The most simple way to backup your local server is to copy the whole web directory. It includes both your local site and the database. See path examples above. 

We do not need to create a compressed installation file (.zip) to install an extension. We'll use the Discover method.

Go to {{rarr|Extensions,Extension Manager,Click on Discover}}, in the Extension Manager:Discover menu you click on the Discover button

Mark your module in the list and click on the Install button. If everything went well, you'll get a message that tells you that the module was installed.

At last you enable the module in the Module Manager. Click on New and find it in the the list. As difference to "normal" module installation the Discover method probably did not add an entry to the module instances list. The name is mod_yourmodule so you'll find it lower case sorted to the end of the list . We'll fix that in the next tutorial part.

Info for new Joomla! users: You can create multiple instances/copies of a module. Each with different option settings. That is what you do when you click on the New button.

Add a title, choose a module position and publish. Go to the frontend and see your first module creation. You can now modify the default.php file to get something fancy before you go on to the next step in the tutorial.

{{Tip|To remember for ever. Do not forget to click the Menu Assignment tab in the Module Manager. Promised: You will! }}

More about [[Module|Joomla! Modules]]