Joomla! Documentation - User contributions [en]

User:Over/Step by step to a Joomla Module - A form and ajax

2014-09-10T16:22:06Z

Over: /* mod_yourmodule.php Use a model */

{{underconstruction}}

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== Introduction ===

In this part of the tutorial we will use the form functionality of Joomla!. In a second step we'll add the Joomla! Ajax functionality to the module. If you want to keep the custom module you created up till now, you should use the knowledge you've got from this tutorial and fork it. i.e. you copy all the files to a new local folder and change all filenames to a new name. Then you change all texts in the files including the old module name to a new at your choise, create an installation file and install the new module. We will still use yourmodule as name, so you'll have to adopt your own as before.

Ajax = short for asynchronous JavaScript + XML
{{Tip|We will not mention the name adoption anymore and be less specific about file update.}}

If you have a MVC component related to your module, it's easier and recommended to include the form functionality a.k.a. JForm by using the components methods. We'll add it without a component in this example.

Why use JForm for html forms? You get a lot for "free", like fields html code, client and server side validation.

We first need a xml form declaration. In the folder where you unzipped the downloaded file you can find a models folder. Copy this to your modules web 'root' folder. A module doesn't follow the MVC pattern, but let us use models as folder name. For a component you'll find forms, fields and rules in this path. You can find examples of custom fields and rules in those folders.

=== The form ===
Open models/forms/yourmodule_form.xml for edit.

==== message.xml ====

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<form>
<fieldset addfieldpath="modules/mod_yourmodule/models/fields"
addrulepath="modules/mod_yourmodule/models/rules">
<field name="subject"
type="text"
size="60"
description="MOD_YOURMODULE_MESSAGE_SUBJECT_DESC"
label="MOD_YOURMODULE_MESSAGE_SUBJECT_LABEL"
filter="string"
validate="yourmessagesubject"
required="true"/>
<field name="message"
type="textarea"
cols="50"
rows="10"
description="MOD_YOURMODULE_ENTER_MESSAGE_DESC"
label="MOD_YOURMODULE_ENTER_MESSAGE_LABEL"
filter="safehtml"
validate="yourmessage"
required="true"/>
</fieldset>
</form>

</source>

To be able to use our own fields and rules we add 'addfieldpath' and 'addrulepath'. Explaning the details of the declarations is outside the scope of this tutorial. Only so far: we add two fields 'subject' and 'message'. As you can see we use the same xml pattern as is used for the module options. Change the labels and descriptions. Do '''NOT''' change 'your' in the validate lines or you have to edit the rules files.

More about [[Form_field|Form fields]]

You can find examples of form declarations in the core components. e,g. /administrator/com_content/models/forms/article.xml

=== The language strings ===

We have to add the language strings to the .ini file

==== en-GB.mod_yourmodule.ini Form texts ====

<source>

MOD_YOURMODULE_MESSAGE_SUBJECT_DESC="The subject of yor message"
MOD_YOURMODULE_MESSAGE_SUBJECT_LABEL="Subject"
MOD_YOURMODULE_ENTER_MESSAGE_DESC="Add your message"
MOD_YOURMODULE_ENTER_MESSAGE_LABEL="Message"

</source>

=== Add the form to the output ===

==== default.php With a form ====

<source lang="php">
defined('_JEXEC') or die('Restricted access');
?>
<h3>A form your module</h3>

<form id="mod_yourmodule_<?php echo $module->id;?>" action="<?php echo JRoute::_('index.php'); ?>" method="post" class="form-validate">
<fieldset class="well">
<?php
echo $form->renderField('subject');
echo $form->renderField('message');

if (!$messageSent)
{
echo '<button class="btn btn-primary validate" type="submit">'.JText::_('JSUBMIT').'</button>';
echo '<input type="hidden" name="mod_yourmodule" value="1" />';
echo JHtml::_('form.token');
}
?>

</fieldset>
</form>

</source>

We will make some changes to this code, when we add Ajax handling to the module. Add this if you first want to test the form without Ajax.

=== Load and use the model ===

We load the message model and use it to get our form.

==== mod_yourmodule.php Use a model ====

<source lang="php">
defined('_JEXEC') or die('Restricted access');

//the class suffix from parameter
$moduleclass_sfx = htmlspecialchars($params->get('moduleclass_sfx'));

$jinput = JFactory::getApplication()->input;

$messageSent = $jinput->post->get( 'mod_yourmodule', 0, 'INT');

if ($messageSent)
{
//check the security token
JSession::checkToken() or jexit(JText::_( 'JINVALID_TOKEN' ));

$data = $jinput->post->get( 'jform', array(), 'ARRAY' );
}

// Include the helper that handles the data
JLoader::import( 'helper',JPATH_ROOT .'/modules/mod_yourmodule' );

// Include the model that provide the form functionality
JLoader::import( 'message',JPATH_ROOT .'/modules/mod_yourmodule/models' );

$model = JModelLegacy::getInstance( 'Message', 'YourmoduleModel', array('ignore_request' => true));

$form = $model->getForm( array() , $loadData = true);

if ($messageSent)
{

// Test whether the data is valid.
$validData = $model->validate( $form, $data );

// Check for validation errors.
if ( $validData === false )
{
JFactory::getApplication()->enqueueMessage($model->getError(), 'error');
}
else
{
JFactory::getApplication()->enqueueMessage('Thanks for sending us a message');
}
}

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

</source>

Note the lines:
<source>
$jinput = JFactory::getApplication()->input;

and

$data = $jinput->post->get( 'jform', array(), 'ARRAY' );
</source>

That is the way you get data more secure from the HTTP request with Joomla . In this case an array variable named jform from the $_POST. Default is an empty array. Do not use $_REQUEST directly.
See [[Retrieving_request_data_using_JInput|Retrieving request data using JInput]]

We will make some changes to this code as well, when we add Ajax handling to the module. Add this if you first want to test the form without Ajax.

If you chose to change the code, you should now see a submitable form in your module position.

=== Add Ajax functionality ===

We remind you of the best practice to use a component for Ajax response. Since Joomla! version 3.2 a new component com_ajax is included in the Joomla! package. If you don't have a component, you can use that to get more secure handling for modules and plugins. We will use this interface here.

Read more [[Using_Joomla_Ajax_Interface|Using Joomla Ajax Interface]]. You can also follow the examples from that document.

User:Over/Step by step to a Joomla Module - A form and ajax

2014-09-10T16:20:12Z

Over: /* mod_yourmodule.php Use a model */

{{underconstruction}}

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== Introduction ===

In this part of the tutorial we will use the form functionality of Joomla!. In a second step we'll add the Joomla! Ajax functionality to the module. If you want to keep the custom module you created up till now, you should use the knowledge you've got from this tutorial and fork it. i.e. you copy all the files to a new local folder and change all filenames to a new name. Then you change all texts in the files including the old module name to a new at your choise, create an installation file and install the new module. We will still use yourmodule as name, so you'll have to adopt your own as before.

Ajax = short for asynchronous JavaScript + XML
{{Tip|We will not mention the name adoption anymore and be less specific about file update.}}

If you have a MVC component related to your module, it's easier and recommended to include the form functionality a.k.a. JForm by using the components methods. We'll add it without a component in this example.

Why use JForm for html forms? You get a lot for "free", like fields html code, client and server side validation.

We first need a xml form declaration. In the folder where you unzipped the downloaded file you can find a models folder. Copy this to your modules web 'root' folder. A module doesn't follow the MVC pattern, but let us use models as folder name. For a component you'll find forms, fields and rules in this path. You can find examples of custom fields and rules in those folders.

=== The form ===
Open models/forms/yourmodule_form.xml for edit.

==== message.xml ====

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<form>
<fieldset addfieldpath="modules/mod_yourmodule/models/fields"
addrulepath="modules/mod_yourmodule/models/rules">
<field name="subject"
type="text"
size="60"
description="MOD_YOURMODULE_MESSAGE_SUBJECT_DESC"
label="MOD_YOURMODULE_MESSAGE_SUBJECT_LABEL"
filter="string"
validate="yourmessagesubject"
required="true"/>
<field name="message"
type="textarea"
cols="50"
rows="10"
description="MOD_YOURMODULE_ENTER_MESSAGE_DESC"
label="MOD_YOURMODULE_ENTER_MESSAGE_LABEL"
filter="safehtml"
validate="yourmessage"
required="true"/>
</fieldset>
</form>

</source>

To be able to use our own fields and rules we add 'addfieldpath' and 'addrulepath'. Explaning the details of the declarations is outside the scope of this tutorial. Only so far: we add two fields 'subject' and 'message'. As you can see we use the same xml pattern as is used for the module options. Change the labels and descriptions. Do '''NOT''' change 'your' in the validate lines or you have to edit the rules files.

More about [[Form_field|Form fields]]

You can find examples of form declarations in the core components. e,g. /administrator/com_content/models/forms/article.xml

=== The language strings ===

We have to add the language strings to the .ini file

==== en-GB.mod_yourmodule.ini Form texts ====

<source>

MOD_YOURMODULE_MESSAGE_SUBJECT_DESC="The subject of yor message"
MOD_YOURMODULE_MESSAGE_SUBJECT_LABEL="Subject"
MOD_YOURMODULE_ENTER_MESSAGE_DESC="Add your message"
MOD_YOURMODULE_ENTER_MESSAGE_LABEL="Message"

</source>

=== Add the form to the output ===

==== default.php With a form ====

<source lang="php">
defined('_JEXEC') or die('Restricted access');
?>
<h3>A form your module</h3>

<form id="mod_yourmodule_<?php echo $module->id;?>" action="<?php echo JRoute::_('index.php'); ?>" method="post" class="form-validate">
<fieldset class="well">
<?php
echo $form->renderField('subject');
echo $form->renderField('message');

if (!$messageSent)
{
echo '<button class="btn btn-primary validate" type="submit">'.JText::_('JSUBMIT').'</button>';
echo '<input type="hidden" name="mod_yourmodule" value="1" />';
echo JHtml::_('form.token');
}
?>

</fieldset>
</form>

</source>

We will make some changes to this code, when we add Ajax handling to the module. Add this if you first want to test the form without Ajax.

=== Load and use the model ===

We load the message model and use it to get our form.

==== mod_yourmodule.php Use a model ====

<source lang="php">
defined('_JEXEC') or die('Restricted access');

//the class suffix from parameter
$moduleclass_sfx = htmlspecialchars($params->get('moduleclass_sfx'));

$jinput = JFactory::getApplication()->input;

$messageSent = $jinput->post->get( 'mod_yourmodule', 0, 'INT');

if ($messageSent)
{
//check the security token
JSession::checkToken() or jexit(JText::_( 'JINVALID_TOKEN' ));

$data = $jinput->post->get( 'jform', array(), 'ARRAY' );
}

// Include the helper that handles the data
JLoader::import( 'helper',JPATH_ROOT .'/modules/mod_yourmodule' );

// Include the model that provide the form functionality
JLoader::import( 'message',JPATH_ROOT .'/modules/mod_yourmodule/models' );

$model = JModelLegacy::getInstance( 'Message', 'YourmoduleModel', array('ignore_request' => true));

$form = $model->getForm( array() , $loadData = true);

if ($messageSent)
{

// Test whether the data is valid.
$validData = $model->validate( $form, $data );

// Check for validation errors.
if ( $validData === false )
{
JFactory::getApplication()->enqueueMessage($model->getError(), 'error');
}
else
{
JFactory::getApplication()->enqueueMessage('Thanks for sending us a message');
}
}

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

</source>

Note the lines:
<source>
$jinput = JFactory::getApplication()->input;

and

$data = $jinput->post->get( 'jform', array(), 'ARRAY' );
</source>

That is the way you get data more secure from the HTTP request with Joomla . In this case an array variable named jformfrom the $_POST. Default is an empty array. Do not use $_REQUEST directly.
See [[Retrieving_request_data_using_JInput|Retrieving request data using JInput]]

We will make some changes to this code as well, when we add Ajax handling to the module. Add this if you first want to test the form without Ajax.

If you chose to change the code, you should now see a submitable form in your module position.

=== Add Ajax functionality ===

We remind you of the best practice to use a component for Ajax response. Since Joomla! version 3.2 a new component com_ajax is included in the Joomla! package. If you don't have a component, you can use that to get more secure handling for modules and plugins. We will use this interface here.

Read more [[Using_Joomla_Ajax_Interface|Using Joomla Ajax Interface]]. You can also follow the examples from that document.

User:Over/Step by step to a Joomla Module - Data retrieval and styling

2014-09-10T15:42:12Z

Over: /* Use a component for data retrieval */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== Introduction ===

In this step we will extend "Your module" to retrieve data from a database table in two ways, direct access to a table and using a components methods. You have to have installed the module you created in former parts of the tutorial, before you start to follow this part.

=== Data retrieval ===

As in the previous parts you copy a skeleton file to your module folder in your Joomla path of the server. This time you copy the helper.php file to the "root" of the module.

==== helper.php ====

<source type="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' );

abstract class ModYourmoduleHelper
{
/**
* Get data from table
* @return array
*/
public static function getData($params)
{
//we will add some code here
}
}

</source>

The top of the file looks like any other of our php files. Copy your own comment lines from one of the php files you have edited in the former parts of the tutorial. Then we have a class definition with a name following a convention you as well should follow. Mod + The module name + Helper. A comment block follows describing what the following function does. We will add our code within the function ( in developer language called method ). You have to read the coding standards or have a look in any Joomla! core php file to learn more about coding and commenting conventions.

We will use an article to have a litle more dynamic data example. If you didn't create an article earlier in this tutorial series do that now. Keep it short as it's only an example. In the Module Manager you open your module and under the option tab you choose your article example. You see the title but actually the article id number is stored as parameter value.

In the first example we'll get the article text by sending sql statements to the Joomla! database API.

==== helper.php - The sql commands ====
<source type="php">

/**
* Get data from table
* @return array
*/
public static function getData($params)
{
//get article id from module parameter
$id = $params->get('article_id', 0);
if ( !$id )
{
return false;
}
//get the users authorisations
$user = JFactory::getUser();
$groups = implode(',', $user->getAuthorisedViewLevels());

$db = JFactory::getDbo();
//get a db query object
$query = $db->getQuery(true);
//select article id, title and introtext
$query->select(
array(
$db->quoteName('a.id'),
$db->quoteName('a.title'),
$db->quoteName('a.introtext'),
)
);
//from the article table
$query->from($db->quoteName('#__content', 'a'));
//id from parameter, we cast to integer
$query->where($db->quoteName('id') . ' = '. (int) $id);
// Only return if published
$query->where($db->quoteName('a.state') . ' = 1 ');
//and user is authorised to read
$query->where($this->db->quoteName('a.access') . ' IN (' . $groups . ')');

//uncomment this line to see the query string
//echo $query;

$db->setQuery($query);
try
{
//get the article
$result = $db->loadObject();
}
//check error
catch (RuntimeException $e)
{
//this is a module so we skip it if there are errors
// in other cases we would show a message
//$app = JFactory::getApplication();
//$app->enqueueMessage($e->getMessage(), 'error');

return false;
}

return $result;

}

</source>

See the brief comments in the text about what we are doing here.

Important security issue: use $db->quote($field_value) to avoid so called "sql-injections" for none integer or float variables. Use (int) and (float) for those. Be very careful when you build sql queries.

db->quoteName('field_name') escapes the name database dependent. We can't describe more details to Joomla! sql queries within this tutorial. More in [http://docs.joomla.org/Accessing_the_database_using_JDatabase Accessing the database using JDatabase]

As this is a module we don't show errormessages to the user. If there are errors the page will still be ok.

Copy the code to your helper.php replacing the method ( = function ) getData.

The helper file is loaded and run from mod_yourmodule.php. Open it and add the following between defined(... and require.

==== mod_yourmodule.php - Load helper class ====

<source type="php">

// Include the helper file that provide the data
require __DIR__ . '/helper.php';

//the class suffix from parameter
$moduleclass_sfx = htmlspecialchars($params->get('moduleclass_sfx'));

if ( !$article = ModYourmoduleHelper::getData($params))
{
//if error or article not found skip this module
return false;
}

//uncomment this line to see the available fields
//var_dump($article);

</source>

At the same time we get the class suffix from the parameter. Explained below.
Now that you have the article data, we will change the output file to show it. Remember? /tmpl/default.php

==== default.php - Show article ====

<source type="php">

defined('_JEXEC') or die('Restricted access');
?>
<div class="yourmodule<?php echo $moduleclass_sfx ?>">

<h4><?php echo $article->title; ?></h4>

<div><?php echo $article->introtext; ?></div>

</div>
</source>

After defined(... and the php closing tab we change the html. We use embedded php code to echo the title and the introtext. We add a module specific class $moduleclass sfx to the div tag. $moduleclass sfx is the class suffix the user can add in the Module Manager -> tab Advanced. This can be used for Css styling if multiple instances of the same module are enabled. e.g. you can test to reuse your module by choosing another article. We will style them in the next step.

You can test your module before adding the Css.

=== Css styling ===
Best practice on a website is to '''try''' to keep all css styling in one file. As you don't know if the users template shows your module as designed, you have to include a css file. Not really for what we have above, but in a tutorial we do as if. You should use the parameters we created in a former part, to let the user of the module exclude your css. Described in the Overrides part of the tutorial.

We will not only prepare for loading css but also for images and javascript. Best practice is to store those files in subfolders of the Joomla media folder. Please don't ask why this folder was named media.

Create folder path/to/your/joomla/media/mod_yourmodule. In the folder where you unpacked the tutorial zip file you'll find a media folder. Open this and copy all three subfolders to the new folder in your web folder. It should result in something like this

<pre>
...
/logs
/media
...
/mod_yourmodule *new directory*
/css *new directory*
yourmodule.css *new file*
/images *new directory*
doc.png *new file*
yourmodule-logo.png *new file*
/js *new directory*
yourmodule.js *new file*
yourmodule_ajax.js *new file*
...
/modules
...
</pre>

Did you use your module name? You don´t have to, but it´s a good practice to use distinct names.

=== Add Css file ===

We include the module specific css file to the header of the html document.

==== default.php - Include Css file and image ====

<source>

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

JHtml::stylesheet('mod_yourmodule/yourmodule.css', false, true, false);
?>
<div class="yourmodule<?php echo $moduleclass_sfx ?>">

<div class="row text-center">
<?php echo JHtml::image('mod_yourmodule/yourmodule-logo.png', 'Yourmodule logo', '', true, false );?>
</div>

<h4><?php echo $article->title; ?></h4>

<div><?php echo $article->introtext; ?></div>

</div>

</source>

With this code added yourmodule.css will be loaded from the path media/mod_yourmodule/css/
Be aware of the missing /css/ ! This is added by Joomla. The image will be loaded from the path media/mod_yourmodule/images/.

Let's test that the css is working by adding a few lines to the yourmodule.css file. Open it with the editor and add e.g. those lines that change text color. Do we have to mention the module name that was used as css class?

==== yourmodule.css ====
<source>
.yourmodule h4{
color: #08c;
}
.yourmodule p {
color: #005580;
}
</source>

On your frontend page the colors should have changed and an image added. Have a look! Be aware that your browser may have cached the css.

=== Update the xml and the zip file ===

Now we have to add the new files to the xml file and create an updated installation zip file.

Add the helper.php and the special media tag to the xml file.

==== mod_yourmodule.xml - Add helper.php ====

Add helper.php to the files tag.

<source>

<files>
<filename>helper.php</filename>
<filename>mod_yourmodule.xml</filename>
<filename module="mod_yourmodule">mod_yourmodule.php</filename>
<folder>tmpl</folder>
</files>

</source>

==== mod_yourmodule.xml - Add media folder ====

Add the media tag between files and languages.

<source>

</files>
<media destination="mod_yourmodule" folder="media">
<folder>css</folder>
<folder>images</folder>
<folder>js</folder>
</media>
<languages folder="langs">

</source>

=== Create the installation file ===

Now you copy '''all''' module files from the server to the path 'somewhere'/j_module_tutorial/new_module as in the 'Installation package' part of this tutorial.
Create a new folder 'media' and copy the three folders from media/mod_yourmodule.

<pre>
.../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
/language
/en-GB
en-GB.mod_yourmodule.sys.ini
/anyother-language
anyother-language.mod_yourmodule.sys.ini
/media
/css
yourmodule.css
/images
doc.png
yourmodule-logo.png
/js
yourmodule.js
/tmpl
default.php
mod_yourmodule.php
mod_yourmodule.xml
</pre>

Create the compressed installation zip file as described in the 'Installation package' part of this tutorial.

That's it for this tutorial part. Below we describe an alternative for data retrieval.

=== Use a component for data retrieval ===

Below is an alternative to using direct sql. You can use the methods provided by a component to retrieve the data. If you develop your own component, you can prepare methods for reuse, otherwise you can try to find a method in a components models to retrieve the data you want. Here we reuse the getItem method of the content component ( articles ). In this case you get all article data returned. If you use a lot of modules of this type on the same page, be a little aware of memory usage. If you want to test it, you only have to replace the getData method in helper.php.

To see the data available you can uncomment the var_dump line in mod_yourmodule.php.

==== helper.php Use of component ====

<source lang="php">
public static function getData($params)
{
//get article id from module parameter
$id = $params->get('article_id', 0);
if ( !$id )
{
return false;
}

$model = JModelLegacy::getInstance('Article', 'ContentModel', array('ignore_request' => true));

$app = JFactory::getApplication('site');

$model->setState('article.id', $id);
$model->setState('list.offset', 0);

// Load the parameters.
$params = $app->getParams('com_content');
$model->setState('params', $params);

$user = JFactory::getUser();

if ((!$user->authorise('core.edit.state', 'com_content')) && (!$user->authorise('core.edit', 'com_content')))
{
$model->setState('filter.published', 1);
$model->setState('filter.archived', 2);
}

$model->setState('filter.language', JLanguageMultilang::isEnabled());

return $model->getItem($id);;

</source>

=== Add javascript to the module ===

If you want to use javascript for yourmodule, here is an example. It loads the javascript file in the media/mod_yourmodule/js path and adds a script to the header of the html document.

Read more [[J3.x:Javascript_Frameworks|J3.x:Javascript Frameworks]]

==== default.php Javascript ====
<source>
JHtml::_('bootstrap.framework');

JHtml::script('mod_yourmodule/yourmodule.js', false, true, false, false, false);

$document = JFactory::getDocument();
$document->addScriptDeclaration('jQuery( document ).ready(function()
{
alert(\'I am an alert box!\');});'
);
</source>

Add this code below the line that loads the css file if you want to test it.

* We use jQuery so we have to load it '''before''' our own modules script. Here we load the Bootstrap framework that also includes jQuery. Use JHtml::_('jquery.framework') if you only need this.
* We add our scriptfile "relative" to the media folder.
* We add the script declaration directly to the document object. It gets added to the header in the html document.

User:Over/Step by step to a Joomla Module - Data retrieval and styling

2014-09-10T15:40:26Z

Over: /* Create the installation file */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== Introduction ===

In this step we will extend "Your module" to retrieve data from a database table in two ways, direct access to a table and using a components methods. You have to have installed the module you created in former parts of the tutorial, before you start to follow this part.

=== Data retrieval ===

As in the previous parts you copy a skeleton file to your module folder in your Joomla path of the server. This time you copy the helper.php file to the "root" of the module.

==== helper.php ====

<source type="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' );

abstract class ModYourmoduleHelper
{
/**
* Get data from table
* @return array
*/
public static function getData($params)
{
//we will add some code here
}
}

</source>

The top of the file looks like any other of our php files. Copy your own comment lines from one of the php files you have edited in the former parts of the tutorial. Then we have a class definition with a name following a convention you as well should follow. Mod + The module name + Helper. A comment block follows describing what the following function does. We will add our code within the function ( in developer language called method ). You have to read the coding standards or have a look in any Joomla! core php file to learn more about coding and commenting conventions.

We will use an article to have a litle more dynamic data example. If you didn't create an article earlier in this tutorial series do that now. Keep it short as it's only an example. In the Module Manager you open your module and under the option tab you choose your article example. You see the title but actually the article id number is stored as parameter value.

In the first example we'll get the article text by sending sql statements to the Joomla! database API.

==== helper.php - The sql commands ====
<source type="php">

/**
* Get data from table
* @return array
*/
public static function getData($params)
{
//get article id from module parameter
$id = $params->get('article_id', 0);
if ( !$id )
{
return false;
}
//get the users authorisations
$user = JFactory::getUser();
$groups = implode(',', $user->getAuthorisedViewLevels());

$db = JFactory::getDbo();
//get a db query object
$query = $db->getQuery(true);
//select article id, title and introtext
$query->select(
array(
$db->quoteName('a.id'),
$db->quoteName('a.title'),
$db->quoteName('a.introtext'),
)
);
//from the article table
$query->from($db->quoteName('#__content', 'a'));
//id from parameter, we cast to integer
$query->where($db->quoteName('id') . ' = '. (int) $id);
// Only return if published
$query->where($db->quoteName('a.state') . ' = 1 ');
//and user is authorised to read
$query->where($this->db->quoteName('a.access') . ' IN (' . $groups . ')');

//uncomment this line to see the query string
//echo $query;

$db->setQuery($query);
try
{
//get the article
$result = $db->loadObject();
}
//check error
catch (RuntimeException $e)
{
//this is a module so we skip it if there are errors
// in other cases we would show a message
//$app = JFactory::getApplication();
//$app->enqueueMessage($e->getMessage(), 'error');

return false;
}

return $result;

}

</source>

See the brief comments in the text about what we are doing here.

Important security issue: use $db->quote($field_value) to avoid so called "sql-injections" for none integer or float variables. Use (int) and (float) for those. Be very careful when you build sql queries.

db->quoteName('field_name') escapes the name database dependent. We can't describe more details to Joomla! sql queries within this tutorial. More in [http://docs.joomla.org/Accessing_the_database_using_JDatabase Accessing the database using JDatabase]

As this is a module we don't show errormessages to the user. If there are errors the page will still be ok.

Copy the code to your helper.php replacing the method ( = function ) getData.

The helper file is loaded and run from mod_yourmodule.php. Open it and add the following between defined(... and require.

==== mod_yourmodule.php - Load helper class ====

<source type="php">

// Include the helper file that provide the data
require __DIR__ . '/helper.php';

//the class suffix from parameter
$moduleclass_sfx = htmlspecialchars($params->get('moduleclass_sfx'));

if ( !$article = ModYourmoduleHelper::getData($params))
{
//if error or article not found skip this module
return false;
}

//uncomment this line to see the available fields
//var_dump($article);

</source>

At the same time we get the class suffix from the parameter. Explained below.
Now that you have the article data, we will change the output file to show it. Remember? /tmpl/default.php

==== default.php - Show article ====

<source type="php">

defined('_JEXEC') or die('Restricted access');
?>
<div class="yourmodule<?php echo $moduleclass_sfx ?>">

<h4><?php echo $article->title; ?></h4>

<div><?php echo $article->introtext; ?></div>

</div>
</source>

After defined(... and the php closing tab we change the html. We use embedded php code to echo the title and the introtext. We add a module specific class $moduleclass sfx to the div tag. $moduleclass sfx is the class suffix the user can add in the Module Manager -> tab Advanced. This can be used for Css styling if multiple instances of the same module are enabled. e.g. you can test to reuse your module by choosing another article. We will style them in the next step.

You can test your module before adding the Css.

=== Css styling ===
Best practice on a website is to '''try''' to keep all css styling in one file. As you don't know if the users template shows your module as designed, you have to include a css file. Not really for what we have above, but in a tutorial we do as if. You should use the parameters we created in a former part, to let the user of the module exclude your css. Described in the Overrides part of the tutorial.

We will not only prepare for loading css but also for images and javascript. Best practice is to store those files in subfolders of the Joomla media folder. Please don't ask why this folder was named media.

Create folder path/to/your/joomla/media/mod_yourmodule. In the folder where you unpacked the tutorial zip file you'll find a media folder. Open this and copy all three subfolders to the new folder in your web folder. It should result in something like this

<pre>
...
/logs
/media
...
/mod_yourmodule *new directory*
/css *new directory*
yourmodule.css *new file*
/images *new directory*
doc.png *new file*
yourmodule-logo.png *new file*
/js *new directory*
yourmodule.js *new file*
yourmodule_ajax.js *new file*
...
/modules
...
</pre>

Did you use your module name? You don´t have to, but it´s a good practice to use distinct names.

=== Add Css file ===

We include the module specific css file to the header of the html document.

==== default.php - Include Css file and image ====

<source>

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

JHtml::stylesheet('mod_yourmodule/yourmodule.css', false, true, false);
?>
<div class="yourmodule<?php echo $moduleclass_sfx ?>">

<div class="row text-center">
<?php echo JHtml::image('mod_yourmodule/yourmodule-logo.png', 'Yourmodule logo', '', true, false );?>
</div>

<h4><?php echo $article->title; ?></h4>

<div><?php echo $article->introtext; ?></div>

</div>

</source>

With this code added yourmodule.css will be loaded from the path media/mod_yourmodule/css/
Be aware of the missing /css/ ! This is added by Joomla. The image will be loaded from the path media/mod_yourmodule/images/.

Let's test that the css is working by adding a few lines to the yourmodule.css file. Open it with the editor and add e.g. those lines that change text color. Do we have to mention the module name that was used as css class?

==== yourmodule.css ====
<source>
.yourmodule h4{
color: #08c;
}
.yourmodule p {
color: #005580;
}
</source>

On your frontend page the colors should have changed and an image added. Have a look! Be aware that your browser may have cached the css.

=== Update the xml and the zip file ===

Now we have to add the new files to the xml file and create an updated installation zip file.

Add the helper.php and the special media tag to the xml file.

==== mod_yourmodule.xml - Add helper.php ====

Add helper.php to the files tag.

<source>

<files>
<filename>helper.php</filename>
<filename>mod_yourmodule.xml</filename>
<filename module="mod_yourmodule">mod_yourmodule.php</filename>
<folder>tmpl</folder>
</files>

</source>

==== mod_yourmodule.xml - Add media folder ====

Add the media tag between files and languages.

<source>

</files>
<media destination="mod_yourmodule" folder="media">
<folder>css</folder>
<folder>images</folder>
<folder>js</folder>
</media>
<languages folder="langs">

</source>

=== Create the installation file ===

Now you copy '''all''' module files from the server to the path 'somewhere'/j_module_tutorial/new_module as in the 'Installation package' part of this tutorial.
Create a new folder 'media' and copy the three folders from media/mod_yourmodule.

<pre>
.../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
/language
/en-GB
en-GB.mod_yourmodule.sys.ini
/anyother-language
anyother-language.mod_yourmodule.sys.ini
/media
/css
yourmodule.css
/images
doc.png
yourmodule-logo.png
/js
yourmodule.js
/tmpl
default.php
mod_yourmodule.php
mod_yourmodule.xml
</pre>

Create the compressed installation zip file as described in the 'Installation package' part of this tutorial.

That's it for this tutorial part. Below we describe an alternative for data retrieval.

=== Use a component for data retrieval ===

Below is an alternative to using direct sql. You can use the methods provided by a component to retrieve the data. If you develop your own component, you can prepare methods for reuse, otherwise you can try to find a method in a components models to retrieve the data you want. Here we reuse the getItem method of the content component ( articles ). In this case you get all article data returned. If you use a lot of modules of this type on the same page, be a little aware of momory usage. If you want to test it, you only have to replace the getData method in helper.php.

To see the data available you can uncomment the var_dump line in mod_yourmodule.php.

==== helper.php Use of component ====

<source lang="php">
public static function getData($params)
{
//get article id from module parameter
$id = $params->get('article_id', 0);
if ( !$id )
{
return false;
}

$model = JModelLegacy::getInstance('Article', 'ContentModel', array('ignore_request' => true));

$app = JFactory::getApplication('site');

$model->setState('article.id', $id);
$model->setState('list.offset', 0);

// Load the parameters.
$params = $app->getParams('com_content');
$model->setState('params', $params);

$user = JFactory::getUser();

if ((!$user->authorise('core.edit.state', 'com_content')) && (!$user->authorise('core.edit', 'com_content')))
{
$model->setState('filter.published', 1);
$model->setState('filter.archived', 2);
}

$model->setState('filter.language', JLanguageMultilang::isEnabled());

return $model->getItem($id);;

</source>

=== Add javascript to the module ===

If you want to use javascript for yourmodule, here is an example. It loads the javascript file in the media/mod_yourmodule/js path and adds a script to the header of the html document.

Read more [[J3.x:Javascript_Frameworks|J3.x:Javascript Frameworks]]

==== default.php Javascript ====
<source>
JHtml::_('bootstrap.framework');

JHtml::script('mod_yourmodule/yourmodule.js', false, true, false, false, false);

$document = JFactory::getDocument();
$document->addScriptDeclaration('jQuery( document ).ready(function()
{
alert(\'I am an alert box!\');});'
);
</source>

Add this code below the line that loads the css file if you want to test it.

* We use jQuery so we have to load it '''before''' our own modules script. Here we load the Bootstrap framework that also includes jQuery. Use JHtml::_('jquery.framework') if you only need this.
* We add our scriptfile "relative" to the media folder.
* We add the script declaration directly to the document object. It gets added to the header in the html document.

User:Over/Step by step to a Joomla Module - Data retrieval and styling

2014-09-10T15:35:09Z

Over: /* default.php - Show article */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== Introduction ===

In this step we will extend "Your module" to retrieve data from a database table in two ways, direct access to a table and using a components methods. You have to have installed the module you created in former parts of the tutorial, before you start to follow this part.

=== Data retrieval ===

As in the previous parts you copy a skeleton file to your module folder in your Joomla path of the server. This time you copy the helper.php file to the "root" of the module.

==== helper.php ====

<source type="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' );

abstract class ModYourmoduleHelper
{
/**
* Get data from table
* @return array
*/
public static function getData($params)
{
//we will add some code here
}
}

</source>

The top of the file looks like any other of our php files. Copy your own comment lines from one of the php files you have edited in the former parts of the tutorial. Then we have a class definition with a name following a convention you as well should follow. Mod + The module name + Helper. A comment block follows describing what the following function does. We will add our code within the function ( in developer language called method ). You have to read the coding standards or have a look in any Joomla! core php file to learn more about coding and commenting conventions.

We will use an article to have a litle more dynamic data example. If you didn't create an article earlier in this tutorial series do that now. Keep it short as it's only an example. In the Module Manager you open your module and under the option tab you choose your article example. You see the title but actually the article id number is stored as parameter value.

In the first example we'll get the article text by sending sql statements to the Joomla! database API.

==== helper.php - The sql commands ====
<source type="php">

/**
* Get data from table
* @return array
*/
public static function getData($params)
{
//get article id from module parameter
$id = $params->get('article_id', 0);
if ( !$id )
{
return false;
}
//get the users authorisations
$user = JFactory::getUser();
$groups = implode(',', $user->getAuthorisedViewLevels());

$db = JFactory::getDbo();
//get a db query object
$query = $db->getQuery(true);
//select article id, title and introtext
$query->select(
array(
$db->quoteName('a.id'),
$db->quoteName('a.title'),
$db->quoteName('a.introtext'),
)
);
//from the article table
$query->from($db->quoteName('#__content', 'a'));
//id from parameter, we cast to integer
$query->where($db->quoteName('id') . ' = '. (int) $id);
// Only return if published
$query->where($db->quoteName('a.state') . ' = 1 ');
//and user is authorised to read
$query->where($this->db->quoteName('a.access') . ' IN (' . $groups . ')');

//uncomment this line to see the query string
//echo $query;

$db->setQuery($query);
try
{
//get the article
$result = $db->loadObject();
}
//check error
catch (RuntimeException $e)
{
//this is a module so we skip it if there are errors
// in other cases we would show a message
//$app = JFactory::getApplication();
//$app->enqueueMessage($e->getMessage(), 'error');

return false;
}

return $result;

}

</source>

See the brief comments in the text about what we are doing here.

Important security issue: use $db->quote($field_value) to avoid so called "sql-injections" for none integer or float variables. Use (int) and (float) for those. Be very careful when you build sql queries.

db->quoteName('field_name') escapes the name database dependent. We can't describe more details to Joomla! sql queries within this tutorial. More in [http://docs.joomla.org/Accessing_the_database_using_JDatabase Accessing the database using JDatabase]

As this is a module we don't show errormessages to the user. If there are errors the page will still be ok.

Copy the code to your helper.php replacing the method ( = function ) getData.

The helper file is loaded and run from mod_yourmodule.php. Open it and add the following between defined(... and require.

==== mod_yourmodule.php - Load helper class ====

<source type="php">

// Include the helper file that provide the data
require __DIR__ . '/helper.php';

//the class suffix from parameter
$moduleclass_sfx = htmlspecialchars($params->get('moduleclass_sfx'));

if ( !$article = ModYourmoduleHelper::getData($params))
{
//if error or article not found skip this module
return false;
}

//uncomment this line to see the available fields
//var_dump($article);

</source>

At the same time we get the class suffix from the parameter. Explained below.
Now that you have the article data, we will change the output file to show it. Remember? /tmpl/default.php

==== default.php - Show article ====

<source type="php">

defined('_JEXEC') or die('Restricted access');
?>
<div class="yourmodule<?php echo $moduleclass_sfx ?>">

<h4><?php echo $article->title; ?></h4>

<div><?php echo $article->introtext; ?></div>

</div>
</source>

After defined(... and the php closing tab we change the html. We use embedded php code to echo the title and the introtext. We add a module specific class $moduleclass sfx to the div tag. $moduleclass sfx is the class suffix the user can add in the Module Manager -> tab Advanced. This can be used for Css styling if multiple instances of the same module are enabled. e.g. you can test to reuse your module by choosing another article. We will style them in the next step.

You can test your module before adding the Css.

=== Css styling ===
Best practice on a website is to '''try''' to keep all css styling in one file. As you don't know if the users template shows your module as designed, you have to include a css file. Not really for what we have above, but in a tutorial we do as if. You should use the parameters we created in a former part, to let the user of the module exclude your css. Described in the Overrides part of the tutorial.

We will not only prepare for loading css but also for images and javascript. Best practice is to store those files in subfolders of the Joomla media folder. Please don't ask why this folder was named media.

Create folder path/to/your/joomla/media/mod_yourmodule. In the folder where you unpacked the tutorial zip file you'll find a media folder. Open this and copy all three subfolders to the new folder in your web folder. It should result in something like this

<pre>
...
/logs
/media
...
/mod_yourmodule *new directory*
/css *new directory*
yourmodule.css *new file*
/images *new directory*
doc.png *new file*
yourmodule-logo.png *new file*
/js *new directory*
yourmodule.js *new file*
yourmodule_ajax.js *new file*
...
/modules
...
</pre>

Did you use your module name? You don´t have to, but it´s a good practice to use distinct names.

=== Add Css file ===

We include the module specific css file to the header of the html document.

==== default.php - Include Css file and image ====

<source>

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

JHtml::stylesheet('mod_yourmodule/yourmodule.css', false, true, false);
?>
<div class="yourmodule<?php echo $moduleclass_sfx ?>">

<div class="row text-center">
<?php echo JHtml::image('mod_yourmodule/yourmodule-logo.png', 'Yourmodule logo', '', true, false );?>
</div>

<h4><?php echo $article->title; ?></h4>

<div><?php echo $article->introtext; ?></div>

</div>

</source>

With this code added yourmodule.css will be loaded from the path media/mod_yourmodule/css/
Be aware of the missing /css/ ! This is added by Joomla. The image will be loaded from the path media/mod_yourmodule/images/.

Let's test that the css is working by adding a few lines to the yourmodule.css file. Open it with the editor and add e.g. those lines that change text color. Do we have to mention the module name that was used as css class?

==== yourmodule.css ====
<source>
.yourmodule h4{
color: #08c;
}
.yourmodule p {
color: #005580;
}
</source>

On your frontend page the colors should have changed and an image added. Have a look! Be aware that your browser may have cached the css.

=== Update the xml and the zip file ===

Now we have to add the new files to the xml file and create an updated installation zip file.

Add the helper.php and the special media tag to the xml file.

==== mod_yourmodule.xml - Add helper.php ====

Add helper.php to the files tag.

<source>

<files>
<filename>helper.php</filename>
<filename>mod_yourmodule.xml</filename>
<filename module="mod_yourmodule">mod_yourmodule.php</filename>
<folder>tmpl</folder>
</files>

</source>

==== mod_yourmodule.xml - Add media folder ====

Add the media tag between files and languages.

<source>

</files>
<media destination="mod_yourmodule" folder="media">
<folder>css</folder>
<folder>images</folder>
<folder>js</folder>
</media>
<languages folder="langs">

</source>

=== Create the installation file ===

Now you copy '''all''' module files from the server to the path 'somewhere'/j_module_tutorial/new_module as in the 'Installation package' part of this tutorial.
Create a new folder 'media' and copy the three folders from media/mod_yourmodule.

<pre>
.../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
/language
/en-GB
en-GB.mod_yourmodule.sys.ini
/anyother-language
anyother-language.mod_yourmodule.sys.ini
/media
/css
yourmodule.css
/images
doc.png
yourmodule-logo.png
/js
yourmodule.js
/tmpl
default.php
mod_yourmodule.php
mod_yourmodule.xml
</pre>

Create the compressed installation zip file as described in the 'Installation package' part of this tutorial.

That's it for this tutorial. Below we describe an alternative for data retrieval.

=== Use a component for data retrieval ===

Below is an alternative to using direct sql. You can use the methods provided by a component to retrieve the data. If you develop your own component, you can prepare methods for reuse, otherwise you can try to find a method in a components models to retrieve the data you want. Here we reuse the getItem method of the content component ( articles ). In this case you get all article data returned. If you use a lot of modules of this type on the same page, be a little aware of momory usage. If you want to test it, you only have to replace the getData method in helper.php.

To see the data available you can uncomment the var_dump line in mod_yourmodule.php.

==== helper.php Use of component ====

<source lang="php">
public static function getData($params)
{
//get article id from module parameter
$id = $params->get('article_id', 0);
if ( !$id )
{
return false;
}

$model = JModelLegacy::getInstance('Article', 'ContentModel', array('ignore_request' => true));

$app = JFactory::getApplication('site');

$model->setState('article.id', $id);
$model->setState('list.offset', 0);

// Load the parameters.
$params = $app->getParams('com_content');
$model->setState('params', $params);

$user = JFactory::getUser();

if ((!$user->authorise('core.edit.state', 'com_content')) && (!$user->authorise('core.edit', 'com_content')))
{
$model->setState('filter.published', 1);
$model->setState('filter.archived', 2);
}

$model->setState('filter.language', JLanguageMultilang::isEnabled());

return $model->getItem($id);;

</source>

=== Add javascript to the module ===

If you want to use javascript for yourmodule, here is an example. It loads the javascript file in the media/mod_yourmodule/js path and adds a script to the header of the html document.

Read more [[J3.x:Javascript_Frameworks|J3.x:Javascript Frameworks]]

==== default.php Javascript ====
<source>
JHtml::_('bootstrap.framework');

JHtml::script('mod_yourmodule/yourmodule.js', false, true, false, false, false);

$document = JFactory::getDocument();
$document->addScriptDeclaration('jQuery( document ).ready(function()
{
alert(\'I am an alert box!\');});'
);
</source>

Add this code below the line that loads the css file if you want to test it.

* We use jQuery so we have to load it '''before''' our own modules script. Here we load the Bootstrap framework that also includes jQuery. Use JHtml::_('jquery.framework') if you only need this.
* We add our scriptfile "relative" to the media folder.
* We add the script declaration directly to the document object. It gets added to the header in the html document.

User:Over/Step by step to a Joomla Module - Basic

2014-09-10T15:07:37Z

Over: /* Prepare files */

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 <config> 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]]

User:Over/Step by step to a Joomla Module - Advanced installation

2014-09-09T10:13:51Z

Over: /* Add a table for the module */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== Introduction ===

In this step we add the advanced installation possibilities 'Installation script', 'Update server' and 'Table creation'. You should have some deeper knowledge of Php or follow the [[J3.x:Developing_a_MVC_Component/Introduction|J3.x:Developing a MVC Component/Introduction]] before adding those to your module.

=== Installation script ===

You can find a script.php in the downloaded tutorial zip file. It includes the same methods as installation scripts for components and other extensions. It lets you add extra functionality. You can use another name for this file. As an example - you can create a folder in images/ and copy some default images to this new folder.

* install : executes when extension gets installed
* uninstall : executes when extension gets uninstalled
* update : executes when extension gets updated
* preflight : executes before install/uninstall/update
* postflight : executes after install/update

You add it to the xml file with
==== mod_yourmodule.xml Installation script ====
<source>

<scriptfile>script.php</scriptfile>
</source>

You of course add the physical file to the folder you use to create the zip installation file.

=== Update server ===

If you publish your module to other users as on the JED [http://extensions.joomla.org/ extensions.joomla.org/], it's recommended that you supply automatic updates on a server of your choise. Here we only show you one example of the code in the xml file. Please read more here [[Deploying_an_Update_Server|Deploying an update server]]

==== mod_yourmodule.xml Update server ====

<source>
...
<updateservers>
<server type="extension" priority="1" name="Your Module Update Site">http://www.myserver.xy/updates/yourmodule.xml</server>
</updateservers>
</extension>

</source>

Add the update information at the bottom of the xml file. In addition you have to add the xml and update zip files on the update server. An example xml is included in the tutorial example data. The zip file is the latest of the installation zip of your module.

=== Add a table for the module ===

You should consider a small backend component as soon as you want to use a table with your module. You shouldn't force users to maintain the table with a database tool. It is realy easy to create a single list view to allow the user to see the entries and delete any unwanted entries. You can also provide methods to retrieve and store the data from the module.
Just follow the component tutorial. The use of a component for data retrieval was explaind in another part of this tutorial.

In case you have reasons not to provide a component, we add some tips here.

You can find a sql folder in the zip file you downloaded. Copy this to your modules 'root' folder where you create the installation zip file. You have to include this for the new installation. It's hard to install and update a database table if the code wasn't executad at installation. Any update sql file is additionaly executed at new installation.
{{Tip|You have to supply an empty update sql file for your first version!}}

This example only includes the MySql database.

<pre>
...
/media
/sql *new directory*
/updates *new directory*
/mysql *new directory*
1.0.0.sql *new file*
install.mysql.sql *new file*
uninstall.mysql.sql *new file*
/tmpl
...
</pre>

* In install.mysql.sql you create the table(s).
* In uninstall.mysql.sql you delete the table(s).
* In the folder /updates/mysql you add the empty sql with a version number. The version number has no relation to the modules number! It's up to you. Here 1.0.0.sql
* In the folder /updates/mysql you add updates to the table(s). Increase the version number. The next would in this case be 1.0.1.sql

Include the sql in the xml file.

==== mod_yourmodule.xml Include the sql ====

<source>

<files>
...
<folder>sql</folder>
</files>
<languages folder="langs">
...
</languages>
<install>
<sql>
<file charset="utf8" driver="mysql">sql/install.mysql.sql</file>
</sql>
</install>
<uninstall>
<sql>
<file charset="utf8" driver="mysql">sql/uninstall.mysql.sql</file>
</sql>
</uninstall>
<update>
<schemas>
<schemapath type="mysql">sql/updates/mysql</schemapath>
</schemas>
</update>
<config>

</source>

* Edit the install.mysql.sql and the uninstall.mysql.sql with your table definitions.
* Add the sql folder to the files tag and the install, uninstall, update tags as above.
* Create the installation zip file.
* Uninstall the module if it is previously installed.
* Install with the new installation file.

User:Over/Step by step to a Joomla Module - Advanced installation

2014-09-09T10:12:35Z

Over: /* Update server */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== Introduction ===

In this step we add the advanced installation possibilities 'Installation script', 'Update server' and 'Table creation'. You should have some deeper knowledge of Php or follow the [[J3.x:Developing_a_MVC_Component/Introduction|J3.x:Developing a MVC Component/Introduction]] before adding those to your module.

=== Installation script ===

You can find a script.php in the downloaded tutorial zip file. It includes the same methods as installation scripts for components and other extensions. It lets you add extra functionality. You can use another name for this file. As an example - you can create a folder in images/ and copy some default images to this new folder.

* install : executes when extension gets installed
* uninstall : executes when extension gets uninstalled
* update : executes when extension gets updated
* preflight : executes before install/uninstall/update
* postflight : executes after install/update

You add it to the xml file with
==== mod_yourmodule.xml Installation script ====
<source>

<scriptfile>script.php</scriptfile>
</source>

You of course add the physical file to the folder you use to create the zip installation file.

=== Update server ===

If you publish your module to other users as on the JED [http://extensions.joomla.org/ extensions.joomla.org/], it's recommended that you supply automatic updates on a server of your choise. Here we only show you one example of the code in the xml file. Please read more here [[Deploying_an_Update_Server|Deploying an update server]]

==== mod_yourmodule.xml Update server ====

<source>
...
<updateservers>
<server type="extension" priority="1" name="Your Module Update Site">http://www.myserver.xy/updates/yourmodule.xml</server>
</updateservers>
</extension>

</source>

Add the update information at the bottom of the xml file. In addition you have to add the xml and update zip files on the update server. An example xml is included in the tutorial example data. The zip file is the latest of the installation zip of your module.

=== Add a table for the module ===

You should consider a small backend component as soon as you want to use a table with your module. You shouldn't force users to maintain the table with a database tool. It is realy easy to create a single list view to allow the user to see the entries and delete any unwanted entries. You can also provide methods to retrive and store the data from the module.
Just follow the component tutorial. The use of a component for data retrieval was explaind in another part of this tutorial.

In case you have reasons not to provide a component, we add some tips here.

You can find a sql folder in the zip file you downloaded. Copy this to your modules 'root' folder where you create the installation zip file. You have to include this for the new installation. It's hard to install and update a database table if the code wasn't executad at installation. Any update sql file is additionaly executed at new installation.
{{Tip|You have to supply an empty update sql file for your first version!}}

This example only includes the MySql database.

<pre>
...
/media
/sql *new directory*
/updates *new directory*
/mysql *new directory*
1.0.0.sql *new file*
install.mysql.sql *new file*
uninstall.mysql.sql *new file*
/tmpl
...
</pre>

* In install.mysql.sql you create the table(s).
* In uninstall.mysql.sql you delete the table(s).
* In the folder /updates/mysql you add the empty sql with a version number. The version number has no relation to the modules number! It's up to you. Here 1.0.0.sql
* In the folder /updates/mysql you add updates to the table(s). Increase the version number. The next would in this case be 1.0.1.sql

Include the sql in the xml file.

==== mod_yourmodule.xml Include the sql ====

<source>

<files>
...
<folder>sql</folder>
</files>
<languages folder="langs">
...
</languages>
<install>
<sql>
<file charset="utf8" driver="mysql">sql/install.mysql.sql</file>
</sql>
</install>
<uninstall>
<sql>
<file charset="utf8" driver="mysql">sql/uninstall.mysql.sql</file>
</sql>
</uninstall>
<update>
<schemas>
<schemapath type="mysql">sql/updates/mysql</schemapath>
</schemas>
</update>
<config>

</source>

* Edit the install.mysql.sql and the uninstall.mysql.sql with your table definitions.
* Add the sql folder to the files tag and the install, uninstall, update tags as above.
* Create the installation zip file.
* Uninstall the module if it is previously installed.
* Install with the new installation file.

User:Over/Step by step to a Joomla Module - Advanced installation

2014-09-09T10:03:53Z

Over: /* Introduction */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== Introduction ===

In this step we add the advanced installation possibilities 'Installation script', 'Update server' and 'Table creation'. You should have some deeper knowledge of Php or follow the [[J3.x:Developing_a_MVC_Component/Introduction|J3.x:Developing a MVC Component/Introduction]] before adding those to your module.

=== Installation script ===

You can find a script.php in the downloaded tutorial zip file. It includes the same methods as installation scripts for components and other extensions. It lets you add extra functionality. You can use another name for this file. As an example - you can create a folder in images/ and copy some default images to this new folder.

* install : executes when extension gets installed
* uninstall : executes when extension gets uninstalled
* update : executes when extension gets updated
* preflight : executes before install/uninstall/update
* postflight : executes after install/update

You add it to the xml file with
==== mod_yourmodule.xml Installation script ====
<source>

<scriptfile>script.php</scriptfile>
</source>

You of course add the physical file to the folder you use to create the zip installation file.

=== Update server ===

If you publish your module to other users as on the JED [http://extensions.joomla.org/ extensions.joomla.org/], it's recommended that you supply automatic updates on a server of your choise. Here we only show you one example of the code in the xml file. Please read more here [[Deploying_an_Update_Server|Deploying an update server]]

==== mod_yourmodule.xml Update server ====

<source>
...
<updateservers>
<server type="extension" priority="1" name="Your Module Update Site">http://www.myserver.xy/updates/yourmodule.xml</server>
</updateservers>
</extension>

</source>

Add the update information at the bottom of the xml file. In addition you have to create the xml and update files on the server.

=== Add a table for the module ===

You should consider a small backend component as soon as you want to use a table with your module. You shouldn't force users to maintain the table with a database tool. It is realy easy to create a single list view to allow the user to see the entries and delete any unwanted entries. You can also provide methods to retrive and store the data from the module.
Just follow the component tutorial. The use of a component for data retrieval was explaind in another part of this tutorial.

In case you have reasons not to provide a component, we add some tips here.

You can find a sql folder in the zip file you downloaded. Copy this to your modules 'root' folder where you create the installation zip file. You have to include this for the new installation. It's hard to install and update a database table if the code wasn't executad at installation. Any update sql file is additionaly executed at new installation.
{{Tip|You have to supply an empty update sql file for your first version!}}

This example only includes the MySql database.

<pre>
...
/media
/sql *new directory*
/updates *new directory*
/mysql *new directory*
1.0.0.sql *new file*
install.mysql.sql *new file*
uninstall.mysql.sql *new file*
/tmpl
...
</pre>

* In install.mysql.sql you create the table(s).
* In uninstall.mysql.sql you delete the table(s).
* In the folder /updates/mysql you add the empty sql with a version number. The version number has no relation to the modules number! It's up to you. Here 1.0.0.sql
* In the folder /updates/mysql you add updates to the table(s). Increase the version number. The next would in this case be 1.0.1.sql

Include the sql in the xml file.

==== mod_yourmodule.xml Include the sql ====

<source>

<files>
...
<folder>sql</folder>
</files>
<languages folder="langs">
...
</languages>
<install>
<sql>
<file charset="utf8" driver="mysql">sql/install.mysql.sql</file>
</sql>
</install>
<uninstall>
<sql>
<file charset="utf8" driver="mysql">sql/uninstall.mysql.sql</file>
</sql>
</uninstall>
<update>
<schemas>
<schemapath type="mysql">sql/updates/mysql</schemapath>
</schemas>
</update>
<config>

</source>

* Edit the install.mysql.sql and the uninstall.mysql.sql with your table definitions.
* Add the sql folder to the files tag and the install, uninstall, update tags as above.
* Create the installation zip file.
* Uninstall the module if it is previously installed.
* Install with the new installation file.

User:Over/Step by step to a Joomla Module - Basic

2014-09-09T09:35:54Z

Over: /* Prepare files */

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.

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 <config> 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]]

User:Over/Step by step to a Joomla Module - Basic

2014-09-09T09:33:29Z

Over: /* Prepare files */

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. Never 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.

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 <config> 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]]

User:Over/Step by step to a Joomla Module - Overrides

2014-09-09T09:17:41Z

Over: /* Overriding */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== Introduction ===
In this step we'll use your custom module to show you how you can use the powerful Joomla! methods to override ( = change ) the output. The same possibilities are valid for all modules and components that follows the Joomla! best practice.

=== Your site template directory ===

As you probably know, your template is found under the templates/ folder in your Joomla! directory. The folders important for our overrides are:

<pre>
...
/templates
...
/mytemplate
/css
/mod_yourmodule
yourmodule.css
...
/html
...
/com_mycomponent
/view1
default.php
/view2
default.php
...
/layouts
/joomla
/content
/info_block
/mod_yourmodule
default.php
alternative.php
...
/images
/mod_yourmodule
yourmodule-logo.png
...
/js
/mod_yourmodule
yourmodule.js
...
...
</pre>

The illustration above shows the paths and some of the files in your templates folder.
If we add files in those directories, they will be used instead of the extensions original files.
You can use the Template Manager to easily create overrides in the html path. [[J3.x:How_to_use_the_Template_Manager|J3.x:How to use the Template Manager]]

Be aware of that if you use a template including overrides, you have to find a way to protect your custom overrides when the template is updated. e.g. if you use the Beez3 template, you can create a copy of this template. See the Template Manager.

We can also override css, images and javascripts that are loaded with the JHtml functions and 'relative' to the media/ folder. We'll show this with the custom module you have created in this tutorial.

=== Overriding ===

Use the Template Manager or your file manager to copy the default.php from the /tmpl folder in your module to yourtemplate/html/mod_yourmodule/ as shown above. Open the copy with your editor and make some visual changes. Maybe you want to replace the Bootstrap classes if your template is not loading the Bootstrap Css. If you now refresh the browser page you'll see the changes.

You can create a second override for your module with another name. e.g. alternative.php and change some visible content. Now you click New in the Module Manager and choose your module. Edit the new copy of the module and choose the second override in the Advanced tab / Alternative Layout. Enable and have a look what happend.

Note: You can add alternative layouts for your own extension by adding e.g. an alternative1.php and an alternative2.php to the /tmpl folder. Do not use a lot of parameters and alternatives. The experience shows, that it is harder for users to get the right set up and the maintenance is more complex.

You can do the same with components. As shown above, you have to add one folder per component view, where you add the output file. The name is not always default.php. It´s also possible to create menu xml files for components alternative layouts.

Copy the yourmodule.css file from media/mod_yourmodule/css to yourtemplate/css/mod_yourmodule/. Open this file and change css classes e.g. text to another color. Reload the page in the browser. Be aware of the browser cache. It can be, that you have to clear it to get the changed css loaded.

Copy an image to yourtemplate/images/mod_yourmodule/ and rename it to the same name as used in the default.php. Reload the page and you'll see your image.

The same possibility is valid for javascript. If they are loaded 'relative' to the media/ path you can copy them to yourtemplate/js/mod_yourmodule/ and change them.

As you remember we added two options to the module settings, load_css and load_js. A administrator/user may want to load css and/or javascript in other ways. If you use those parameters, the administrator can turn off the loading of your modules css and/or javacript without overriding the default.php. This is more important for components as css and javascript normaly not is loaded in overridable code.

=== Examples - optional exclusion of css and javascript===

==== default.php Css parameter ====
<source>

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

if ($params->get('load_css', 1))
{
JHtml::stylesheet('mod_yourmodule/yourmodule.css', false, true, false);
}
?>

</source>

==== default.php Javascript parameter ====
<source>

if ($params->get('load_js', 1))
{
JHtml::_('bootstrap.framework');

JHtml::script('mod_yourmodule/yourmodule.js', false, true, false, false, false);

$document = JFactory::getDocument();
$document->addScriptDeclaration('jQuery( document ).ready(function()
{
alert(\'I am an alert box!\');});'
);

}

</source>

=== The html/layouts path ===

A new possibility to Joomla! output is the reuse of parts of a view ( JLayout ). An example is the use of the same 'layout' in many of the different article views. JLayout files use the layout paths. In the Joomla! root you can find a /layouts folder that include the core JLayout files. Have a look at the available ones. Third party components usually use an own folder in their backend path.

To override those reused 'layouts' you copy them to the corresponding path in your templates directory and make the changes. They will be automaticly loaded instead of the original one.

It's not likely that you can reuse a JLayout file in a module, but it is possible.

=== Language string overrides ===

We will not describe this type of overrides here. We only want to remind you of the possibility to change language strings in extensions that are not your own or add languga constants for your overrides. Do not change the original files.

Go to {{rarr|Extensions,Language Manager,Overrides}} to create overrides that change texts.

User:Over/Step by step to a Joomla Module - Data retrieval and styling

2014-09-08T15:28:09Z

Over: /* helper.php - The sql commands */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== Introduction ===

In this step we will extend "Your module" to retrieve data from a database table in two ways, direct access to a table and using a components methods. You have to have installed the module you created in former parts of the tutorial, before you start to follow this part.

=== Data retrieval ===

As in the previous parts you copy a skeleton file to your module folder in your Joomla path of the server. This time you copy the helper.php file to the "root" of the module.

==== helper.php ====

<source type="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' );

abstract class ModYourmoduleHelper
{
/**
* Get data from table
* @return array
*/
public static function getData($params)
{
//we will add some code here
}
}

</source>

The top of the file looks like any other of our php files. Copy your own comment lines from one of the php files you have edited in the former parts of the tutorial. Then we have a class definition with a name following a convention you as well should follow. Mod + The module name + Helper. A comment block follows describing what the following function does. We will add our code within the function ( in developer language called method ). You have to read the coding standards or have a look in any Joomla! core php file to learn more about coding and commenting conventions.

We will use an article to have a litle more dynamic data example. If you didn't create an article earlier in this tutorial series do that now. Keep it short as it's only an example. In the Module Manager you open your module and under the option tab you choose your article example. You see the title but actually the article id number is stored as parameter value.

In the first example we'll get the article text by sending sql statements to the Joomla! database API.

==== helper.php - The sql commands ====
<source type="php">

/**
* Get data from table
* @return array
*/
public static function getData($params)
{
//get article id from module parameter
$id = $params->get('article_id', 0);
if ( !$id )
{
return false;
}
//get the users authorisations
$user = JFactory::getUser();
$groups = implode(',', $user->getAuthorisedViewLevels());

$db = JFactory::getDbo();
//get a db query object
$query = $db->getQuery(true);
//select article id, title and introtext
$query->select(
array(
$db->quoteName('a.id'),
$db->quoteName('a.title'),
$db->quoteName('a.introtext'),
)
);
//from the article table
$query->from($db->quoteName('#__content', 'a'));
//id from parameter, we cast to integer
$query->where($db->quoteName('id') . ' = '. (int) $id);
// Only return if published
$query->where($db->quoteName('a.state') . ' = 1 ');
//and user is authorised to read
$query->where($this->db->quoteName('a.access') . ' IN (' . $groups . ')');

//uncomment this line to see the query string
//echo $query;

$db->setQuery($query);
try
{
//get the article
$result = $db->loadObject();
}
//check error
catch (RuntimeException $e)
{
//this is a module so we skip it if there are errors
// in other cases we would show a message
//$app = JFactory::getApplication();
//$app->enqueueMessage($e->getMessage(), 'error');

return false;
}

return $result;

}

</source>

See the brief comments in the text about what we are doing here.

Important security issue: use $db->quote($field_value) to avoid so called "sql-injections" for none integer or float variables. Use (int) and (float) for those. Be very careful when you build sql queries.

db->quoteName('field_name') escapes the name database dependent. We can't describe more details to Joomla! sql queries within this tutorial. More in [http://docs.joomla.org/Accessing_the_database_using_JDatabase Accessing the database using JDatabase]

As this is a module we don't show errormessages to the user. If there are errors the page will still be ok.

Copy the code to your helper.php replacing the method ( = function ) getData.

The helper file is loaded and run from mod_yourmodule.php. Open it and add the following between defined(... and require.

==== mod_yourmodule.php - Load helper class ====

<source type="php">

// Include the helper file that provide the data
require __DIR__ . '/helper.php';

//the class suffix from parameter
$moduleclass_sfx = htmlspecialchars($params->get('moduleclass_sfx'));

if ( !$article = ModYourmoduleHelper::getData($params))
{
//if error or article not found skip this module
return false;
}

//uncomment this line to see the available fields
//var_dump($article);

</source>

At the same time we get the class suffix from the parameter. Explained below.
Now that you have the article data, we will change the output file to show it. Remember? /tmpl/default.php

==== default.php - Show article ====

<source type="php">

defined('_JEXEC') or die('Restricted access');
?>
<div class="yourmodule<?php echo $moduleclass_sfx ?>">

<h4><?php echo $article->title; ?></h4>

<div><?php echo $article->introtext; ?></div>

</div>
</source>

After defined(... and the php closing tab we change the html. We use embedded php code to echo the title and the introtext. We add a module specific class $moduleclass sfx to the div tag. $moduleclass sfx is the class suffix the user can add in the Module Manager -> tab Advanced. This can be used for Css styling if multiple instances of the same module are enabled. e.g. you can test to reuse your module by choosing another article. We will style them in the next step.

=== Css styling ===
Best practice on a website is to '''try''' to keep all css styling in one file. As you don't know if the users template shows your module as designed, you have to include a css file. Not really for what we have above, but in a tutorial we do as if. You should use the parameters we created in a former part, to let the user of the module exclude your css. Described in the Overrides part of the tutorial.

We will not only prepare for loading css but also for images and javascript. Best practice is to store those files in subfolders of the Joomla media folder. Please don't ask why this folder was named media.

Create folder path/to/your/joomla/media/mod_yourmodule. In the folder where you unpacked the tutorial zip file you'll find a media folder. Open this and copy all three subfolders to the new folder in your web folder. It should result in something like this

<pre>
...
/logs
/media
...
/mod_yourmodule *new directory*
/css *new directory*
yourmodule.css *new file*
/images *new directory*
doc.png *new file*
yourmodule-logo.png *new file*
/js *new directory*
yourmodule.js *new file*
yourmodule_ajax.js *new file*
...
/modules
...
</pre>

Did you use your module name? You don´t have to, but it´s a good practice to use distinct names.

=== Add Css file ===

We include the module specific css file to the header of the html document.

==== default.php - Include Css file and image ====

<source>

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

JHtml::stylesheet('mod_yourmodule/yourmodule.css', false, true, false);
?>
<div class="yourmodule<?php echo $moduleclass_sfx ?>">

<div class="row text-center">
<?php echo JHtml::image('mod_yourmodule/yourmodule-logo.png', 'Yourmodule logo', '', true, false );?>
</div>

<h4><?php echo $article->title; ?></h4>

<div><?php echo $article->introtext; ?></div>

</div>

</source>

With this code added yourmodule.css will be loaded from the path media/mod_yourmodule/css/
Be aware of the missing /css/ ! This is added by Joomla. The image will be loaded from the path media/mod_yourmodule/images/.

Let's test that the css is working by adding a few lines to the yourmodule.css file. Open it with the editor and add e.g. those lines that change text color. Do we have to mention the module name that was used as css class?

==== yourmodule.css ====
<source>
.yourmodule h4{
color: #08c;
}
.yourmodule p {
color: #005580;
}
</source>

On your frontend page the colors should have changed and an image added. Have a look! Be aware that your browser may have cached the css.

=== Update the xml and the zip file ===

Now we have to add the new files to the xml file and create an updated installation zip file.

Add the helper.php and the special media tag to the xml file.

==== mod_yourmodule.xml - Add helper.php ====

Add helper.php to the files tag.

<source>

<files>
<filename>helper.php</filename>
<filename>mod_yourmodule.xml</filename>
<filename module="mod_yourmodule">mod_yourmodule.php</filename>
<folder>tmpl</folder>
</files>

</source>

==== mod_yourmodule.xml - Add media folder ====

Add the media tag between files and languages.

<source>

</files>
<media destination="mod_yourmodule" folder="media">
<folder>css</folder>
<folder>images</folder>
<folder>js</folder>
</media>
<languages folder="langs">

</source>

=== Create the installation file ===

Now you copy '''all''' module files from the server to the path 'somewhere'/j_module_tutorial/new_module as in the 'Installation package' part of this tutorial.
Create a new folder 'media' and copy the three folders from media/mod_yourmodule.

<pre>
.../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
/language
/en-GB
en-GB.mod_yourmodule.sys.ini
/anyother-language
anyother-language.mod_yourmodule.sys.ini
/media
/css
yourmodule.css
/images
doc.png
yourmodule-logo.png
/js
yourmodule.js
/tmpl
default.php
mod_yourmodule.php
mod_yourmodule.xml
</pre>

Create the compressed installation zip file as described in the 'Installation package' part of this tutorial.

That's it for this tutorial. Below we describe an alternative for data retrieval.

=== Use a component for data retrieval ===

Below is an alternative to using direct sql. You can use the methods provided by a component to retrieve the data. If you develop your own component, you can prepare methods for reuse, otherwise you can try to find a method in a components models to retrieve the data you want. Here we reuse the getItem method of the content component ( articles ). In this case you get all article data returned. If you use a lot of modules of this type on the same page, be a little aware of momory usage. If you want to test it, you only have to replace the getData method in helper.php.

To see the data available you can uncomment the var_dump line in mod_yourmodule.php.

==== helper.php Use of component ====

<source lang="php">
public static function getData($params)
{
//get article id from module parameter
$id = $params->get('article_id', 0);
if ( !$id )
{
return false;
}

$model = JModelLegacy::getInstance('Article', 'ContentModel', array('ignore_request' => true));

$app = JFactory::getApplication('site');

$model->setState('article.id', $id);
$model->setState('list.offset', 0);

// Load the parameters.
$params = $app->getParams('com_content');
$model->setState('params', $params);

$user = JFactory::getUser();

if ((!$user->authorise('core.edit.state', 'com_content')) && (!$user->authorise('core.edit', 'com_content')))
{
$model->setState('filter.published', 1);
$model->setState('filter.archived', 2);
}

$model->setState('filter.language', JLanguageMultilang::isEnabled());

return $model->getItem($id);;

</source>

=== Add javascript to the module ===

If you want to use javascript for yourmodule, here is an example. It loads the javascript file in the media/mod_yourmodule/js path and adds a script to the header of the html document.

Read more [[J3.x:Javascript_Frameworks|J3.x:Javascript Frameworks]]

==== default.php Javascript ====
<source>
JHtml::_('bootstrap.framework');

JHtml::script('mod_yourmodule/yourmodule.js', false, true, false, false, false);

$document = JFactory::getDocument();
$document->addScriptDeclaration('jQuery( document ).ready(function()
{
alert(\'I am an alert box!\');});'
);
</source>

Add this code below the line that loads the css file if you want to test it.

* We use jQuery so we have to load it '''before''' our own modules script. Here we load the Bootstrap framework that also includes jQuery. Use JHtml::_('jquery.framework') if you only need this.
* We add our scriptfile "relative" to the media folder.
* We add the script declaration directly to the document object. It gets added to the header in the html document.

User:Over/Step by step to a Joomla Module - Basic

2014-09-08T15:18:30Z

Over: /* Prepare files */

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. Never 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.

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 <config> 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]]

User:Over/Step by step to a Joomla Module - Basic

2014-09-08T15:14:42Z

Over: /* Prepare files */

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. System,Global,Server Settings,Error Reporting -> Development. Never 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.

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 <config> 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]]

User:Over/Step by step to a Joomla Module - Overrides

2014-09-08T15:01:40Z

Over: /* Overriding */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== Introduction ===
In this step we'll use your custom module to show you how you can use the powerful Joomla! methods to override ( = change ) the output. The same possibilities are valid for all modules and components that follows the Joomla! best practice.

=== Your site template directory ===

As you probably know, your template is found under the templates/ folder in your Joomla! directory. The folders important for our overrides are:

<pre>
...
/templates
...
/mytemplate
/css
/mod_yourmodule
yourmodule.css
...
/html
...
/com_mycomponent
/view1
default.php
/view2
default.php
...
/layouts
/joomla
/content
/info_block
/mod_yourmodule
default.php
alternative.php
...
/images
/mod_yourmodule
yourmodule-logo.png
...
/js
/mod_yourmodule
yourmodule.js
...
...
</pre>

The illustration above shows the paths and some of the files in your templates folder.
If we add files in those directories, they will be used instead of the extensions original files.
You can use the Template Manager to easily create overrides in the html path. [[J3.x:How_to_use_the_Template_Manager|J3.x:How to use the Template Manager]]

Be aware of that if you use a template including overrides, you have to find a way to protect your custom overrides when the template is updated. e.g. if you use the Beez3 template, you can create a copy of this template. See the Template Manager.

We can also override css, images and javascripts that are loaded with the JHtml functions and 'relative' to the media/ folder. We'll show this with the custom module you have created in this tutorial.

=== Overriding ===

Use the Template Manager or your file manager to copy the default.php from the /tmpl folder in your module to yourtemplate/html/mod_yourmodule/ as shown above. Open the copy with your editor and make some visual changes. Maybe you want to replace the Bootstrap classes if your template is not loading the Bootstrap Css. If you now refresh the browser page you'll see the changes.

You can create a second override for your module with another name. e.g. alternative.php and change some visible content. Now you click New in the Module Manager and choose your module. Edit the new copy of the module and choose the second override in the Advanced tab / Alternative Layout. Enable and have a look what happend.

You can do the same with components. As shown above, you have to add one folder per component view, where you add the output file. The name is not always default.php. It´s also possible to create menu xml files for components alternative layouts.

Copy the yourmodule.css file from media/mod_yourmodule/css to yourtemplate/css/mod_yourmodule/. Open this file and change css classes e.g. text to another color. Reload the page in the browser. Be aware of the browser cache. It can be, that you have to clear it to get the changed css loaded.

Copy an image to yourtemplate/images/mod_yourmodule/ and rename it to the same name as used in the default.php. Reload the page and you'll see your image.

The same possibility is valid for javascript. If they are loaded 'relative' to the media/ path you can copy them to yourtemplate/js/mod_yourmodule/ and change them.

As you remember we added two options to the module settings, load_css and load_js. A administrator/user may want to load css and/or javascript in other ways. If you use those parameters, the administrator can turn off the loading of your modules css and/or javacript without overriding the default.php. This is more important for components as css and javascript normaly not is loaded in overridable code.

=== Examples - optional exclusion of css and javascript===

==== default.php Css parameter ====
<source>

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

if ($params->get('load_css', 1))
{
JHtml::stylesheet('mod_yourmodule/yourmodule.css', false, true, false);
}
?>

</source>

==== default.php Javascript parameter ====
<source>

if ($params->get('load_js', 1))
{
JHtml::_('bootstrap.framework');

JHtml::script('mod_yourmodule/yourmodule.js', false, true, false, false, false);

$document = JFactory::getDocument();
$document->addScriptDeclaration('jQuery( document ).ready(function()
{
alert(\'I am an alert box!\');});'
);

}

</source>

=== The html/layouts path ===

A new possibility to Joomla! output is the reuse of parts of a view ( JLayout ). An example is the use of the same 'layout' in many of the different article views. JLayout files use the layout paths. In the Joomla! root you can find a /layouts folder that include the core JLayout files. Have a look at the available ones. Third party components usually use an own folder in their backend path.

To override those reused 'layouts' you copy them to the corresponding path in your templates directory and make the changes. They will be automaticly loaded instead of the original one.

It's not likely that you can reuse a JLayout file in a module, but it is possible.

=== Language string overrides ===

We will not describe this type of overrides here. We only want to remind you of the possibility to change language strings in extensions that are not your own or add languga constants for your overrides. Do not change the original files.

Go to {{rarr|Extensions,Language Manager,Overrides}} to create overrides that change texts.

User:Over/Step by step to a Joomla Module - Overrides

2014-09-08T14:56:04Z

Over: /* Language string overrides */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== Introduction ===
In this step we'll use your custom module to show you how you can use the powerful Joomla! methods to override ( = change ) the output. The same possibilities are valid for all modules and components that follows the Joomla! best practice.

=== Your site template directory ===

As you probably know, your template is found under the templates/ folder in your Joomla! directory. The folders important for our overrides are:

<pre>
...
/templates
...
/mytemplate
/css
/mod_yourmodule
yourmodule.css
...
/html
...
/com_mycomponent
/view1
default.php
/view2
default.php
...
/layouts
/joomla
/content
/info_block
/mod_yourmodule
default.php
alternative.php
...
/images
/mod_yourmodule
yourmodule-logo.png
...
/js
/mod_yourmodule
yourmodule.js
...
...
</pre>

The illustration above shows the paths and some of the files in your templates folder.
If we add files in those directories, they will be used instead of the extensions original files.
You can use the Template Manager to easily create overrides in the html path. [[J3.x:How_to_use_the_Template_Manager|J3.x:How to use the Template Manager]]

Be aware of that if you use a template including overrides, you have to find a way to protect your custom overrides when the template is updated. e.g. if you use the Beez3 template, you can create a copy of this template. See the Template Manager.

We can also override css, images and javascripts that are loaded with the JHtml functions and 'relative' to the media/ folder. We'll show this with the custom module you have created in this tutorial.

=== Overriding ===

Use the Template Manager or your file manager to copy the default.php from the /tmpl folder in your module to yourtemplate/html/mod_yourmodule/ as shown above. Open the copy with your editor and make some visual changes. Maybe you want to replace the Bootstrap classes if your template is not loading the Bootstrap Css. If you now refresh the browser page you'll see the changes.

You can create a second override for your module with another name. e.g. alternative.php and change some visible content. Now you click New in the Module Manager and choose your module. Edit the new copy of the module and choose the second override in the Advanced tab / Alternative Layout. Enable and have a look what happend.

You can do the same with components. As shown above, you have to add one folder per component view, where you add the output file. The name is not always default.php.

Copy the yourmodule.css file from media/mod_yourmodule/css to yourtemplate/css/mod_yourmodule/. Open this file and change css classes e.g. text to another color. Reload the page in the browser. Be aware of the browser cache. It can be, that you have to clear it to get the changed css loaded.

Copy an image to yourtemplate/images/mod_yourmodule/ and rename it to the same name as used in the default.php. Reload the page and you'll see your image.

The same possibility is valid for javascript. If they are loaded 'relative' to the media/ path you can copy them to yourtemplate/js/mod_yourmodule/ and change them.

As you remember we added two options to the module settings, load_css and load_js. A administrator/user may want to load css and/or javascript in other ways. If you use those parameters, the administrator can turn off the loading of your modules css and/or javacript without overriding the default.php. This is more important for components as css and javascript normaly not is loaded in overridable code.

=== Examples - optional exclusion of css and javascript===

==== default.php Css parameter ====
<source>

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

if ($params->get('load_css', 1))
{
JHtml::stylesheet('mod_yourmodule/yourmodule.css', false, true, false);
}
?>

</source>

==== default.php Javascript parameter ====
<source>

if ($params->get('load_js', 1))
{
JHtml::_('bootstrap.framework');

JHtml::script('mod_yourmodule/yourmodule.js', false, true, false, false, false);

$document = JFactory::getDocument();
$document->addScriptDeclaration('jQuery( document ).ready(function()
{
alert(\'I am an alert box!\');});'
);

}

</source>

=== The html/layouts path ===

A new possibility to Joomla! output is the reuse of parts of a view ( JLayout ). An example is the use of the same 'layout' in many of the different article views. JLayout files use the layout paths. In the Joomla! root you can find a /layouts folder that include the core JLayout files. Have a look at the available ones. Third party components usually use an own folder in their backend path.

To override those reused 'layouts' you copy them to the corresponding path in your templates directory and make the changes. They will be automaticly loaded instead of the original one.

It's not likely that you can reuse a JLayout file in a module, but it is possible.

=== Language string overrides ===

We will not describe this type of overrides here. We only want to remind you of the possibility to change language strings in extensions that are not your own or add languga constants for your overrides. Do not change the original files.

Go to {{rarr|Extensions,Language Manager,Overrides}} to create overrides that change texts.

User:Over/Step by step to a Joomla Module - Basic

2014-09-08T14:52:31Z

Over: /* Introduction */

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 ===

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.

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 <config> 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]]

User:Over/Step by step to a Joomla Module - Installation package

2014-09-08T14:46:39Z

Over: /* mod_yourmodule.xml - Config */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== 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 =====
<source>

; 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"

</source>

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!'''

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

There is no good reference available at the time of writing. Please change this link if a better is found. [[Specification_of_language_files|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.

<code>
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."
</code>

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 ====

<source>
<description>MOD_YOURMODULE_XML_DESCRIPTION</description>
</source>

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 ====

<source>

<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>

</source>

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 [http://docs.joomla.org/Module 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 ====

<source>

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"
</source>

=== 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 ====

<source>

<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>

</source>

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.

<div class="large-12 panel radius" style="background-color:#fff; border:1px solid #aaa; margin:1em 0;">
'''''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.
</div>

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 ):

<pre>

.../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
/language
/en-GB
en-GB.mod_yourmodule.sys.ini
/anyother-language
anyother-language.mod_yourmodule.sys.ini
/tmpl
default.php
mod_yourmodule.php
mod_yourmodule.xml

</pre>

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 ====

<source>

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."

</source>

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/language-codes.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 {{rarr|Send to,ZIP compressed folder}}.

Rename the .zip file to mod_yourmodule_1_0_0-a1.zip i.e. including the version number and an arcive number. With an archive number included you can easily restore to a tutorial step. 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 {{rarr|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:
<pre>

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

</pre>

==== 1. Easiest way ====

Add a folder tag to the files area in the xml file.
<pre>
<folder>language</folder>
</pre>
The folder will be stored in the extensions folder and no files in the core language folder.
ALL files are copied, not only the ones for installed languages.

==== 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).

<source>

<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>

</source>

The files are saved to the core language folder in the traditional way.
Only the files for installed languages are copied.

User:Over/Step by step to a Joomla Module - Installation package

2014-09-08T14:36:50Z

Over: /* mod_yourmodule.sys.ini - Installation message */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== 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 =====
<source>

; 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"

</source>

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!'''

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

There is no good reference available at the time of writing. Please change this link if a better is found. [[Specification_of_language_files|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.

<code>
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."
</code>

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 ====

<source>
<description>MOD_YOURMODULE_XML_DESCRIPTION</description>
</source>

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 ====

<source>

<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>

</source>

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 [http://docs.joomla.org/Module 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 ====

<source>

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"
</source>

=== 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 ====

<source>

<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>

</source>

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.

<div class="large-12 panel radius" style="background-color:#fff; border:1px solid #aaa; margin:1em 0;">
'''''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.
</div>

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 ):

<pre>

.../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
/language
/en-GB
en-GB.mod_yourmodule.sys.ini
/anyother-language
anyother-language.mod_yourmodule.sys.ini
/tmpl
default.php
mod_yourmodule.php
mod_yourmodule.xml

</pre>

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 ====

<source>

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."

</source>

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/language-codes.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 {{rarr|Send to,ZIP compressed folder}}.

Rename the .zip file to mod_yourmodule_1_0_0-a1.zip i.e. including the version number and an arcive number. With an archive number included you can easily restore to a tutorial step. 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 {{rarr|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:
<pre>

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

</pre>

==== 1. Easiest way ====

Add a folder tag to the files area in the xml file.
<pre>
<folder>language</folder>
</pre>
The folder will be stored in the extensions folder and no files in the core language folder.
ALL files are copied, not only the ones for installed languages.

==== 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).

<source>

<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>

</source>

The files are saved to the core language folder in the traditional way.
Only the files for installed languages are copied.

User:Over/Step by step to a Joomla Module - A form and ajax

2014-09-08T14:23:42Z

Over: /* message.xml */

{{underconstruction}}

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== Introduction ===

In this part of the tutorial we will use the form functionality of Joomla!. In a second step we'll add the Joomla! Ajax functionality to the module. If you want to keep the custom module you created up till now, you should use the knowledge you've got from this tutorial and fork it. i.e. you copy all the files to a new local folder and change all filenames to a new name. Then you change all texts in the files including the old module name to a new at your choise, create an installation file and install the new module. We will still use yourmodule as name, so you'll have to adopt your own as before.

Ajax = short for asynchronous JavaScript + XML
{{Tip|We will not mention the name adoption anymore and be less specific about file update.}}

If you have a MVC component related to your module, it's easier and recommended to include the form functionality a.k.a. JForm by using the components methods. We'll add it without a component in this example.

Why use JForm for html forms? You get a lot for "free", like fields html code, client and server side validation.

We first need a xml form declaration. In the folder where you unzipped the downloaded file you can find a models folder. Copy this to your modules web 'root' folder. A module doesn't follow the MVC pattern, but let us use models as folder name. For a component you'll find forms, fields and rules in this path. You can find examples of custom fields and rules in those folders.

=== The form ===
Open models/forms/yourmodule_form.xml for edit.

==== message.xml ====

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<form>
<fieldset addfieldpath="modules/mod_yourmodule/models/fields"
addrulepath="modules/mod_yourmodule/models/rules">
<field name="subject"
type="text"
size="60"
description="MOD_YOURMODULE_MESSAGE_SUBJECT_DESC"
label="MOD_YOURMODULE_MESSAGE_SUBJECT_LABEL"
filter="string"
validate="yourmessagesubject"
required="true"/>
<field name="message"
type="textarea"
cols="50"
rows="10"
description="MOD_YOURMODULE_ENTER_MESSAGE_DESC"
label="MOD_YOURMODULE_ENTER_MESSAGE_LABEL"
filter="safehtml"
validate="yourmessage"
required="true"/>
</fieldset>
</form>

</source>

To be able to use our own fields and rules we add 'addfieldpath' and 'addrulepath'. Explaning the details of the declarations is outside the scope of this tutorial. Only so far: we add two fields 'subject' and 'message'. As you can see we use the same xml pattern as is used for the module options. Change the labels and descriptions. Do '''NOT''' change 'your' in the validate lines or you have to edit the rules files.

More about [[Form_field|Form fields]]

You can find examples of form declarations in the core components. e,g. /administrator/com_content/models/forms/article.xml

=== The language strings ===

We have to add the language strings to the .ini file

==== en-GB.mod_yourmodule.ini Form texts ====

<source>

MOD_YOURMODULE_MESSAGE_SUBJECT_DESC="The subject of yor message"
MOD_YOURMODULE_MESSAGE_SUBJECT_LABEL="Subject"
MOD_YOURMODULE_ENTER_MESSAGE_DESC="Add your message"
MOD_YOURMODULE_ENTER_MESSAGE_LABEL="Message"

</source>

=== Add the form to the output ===

==== default.php With a form ====

<source lang="php">
defined('_JEXEC') or die('Restricted access');
?>
<h3>A form your module</h3>

<form id="mod_yourmodule_<?php echo $module->id;?>" action="<?php echo JRoute::_('index.php'); ?>" method="post" class="form-validate">
<fieldset class="well">
<?php
echo $form->renderField('subject');
echo $form->renderField('message');

if (!$messageSent)
{
echo '<button class="btn btn-primary validate" type="submit">'.JText::_('JSUBMIT').'</button>';
echo '<input type="hidden" name="mod_yourmodule" value="1" />';
echo JHtml::_('form.token');
}
?>

</fieldset>
</form>

</source>

We will make some changes to this code, when we add Ajax handling to the module. Add this if you first want to test the form without Ajax.

=== Load and use the model ===

We load the message model and use it to get our form.

==== mod_yourmodule.php Use a model ====

<source lang="php">
defined('_JEXEC') or die('Restricted access');

//the class suffix from parameter
$moduleclass_sfx = htmlspecialchars($params->get('moduleclass_sfx'));

$jinput = JFactory::getApplication()->input;

$messageSent = $jinput->post->get( 'mod_yourmodule', 0, 'INT');

if ($messageSent)
{
//check the security token
JSession::checkToken() or jexit(JText::_( 'JINVALID_TOKEN' ));

$data = $jinput->post->get( 'jform', array(), 'ARRAY' );
}

// Include the helper that handles the data
JLoader::import( 'helper',JPATH_ROOT .'/modules/mod_yourmodule' );

// Include the model that provide the form functionality
JLoader::import( 'message',JPATH_ROOT .'/modules/mod_yourmodule/models' );

$model = JModelLegacy::getInstance( 'Message', 'YourmoduleModel', array('ignore_request' => true));

$form = $model->getForm( array() , $loadData = true);

if ($messageSent)
{

// Test whether the data is valid.
$validData = $model->validate( $form, $data );

// Check for validation errors.
if ( $validData === false )
{
JFactory::getApplication()->enqueueMessage($model->getError(), 'error');
}
else
{
JFactory::getApplication()->enqueueMessage('Thanks for sending us a message');
}
}

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

</source>

We will make some changes to this code as well, when we add Ajax handling to the module. Add this if you first want to test the form without Ajax.

If you chose to change the code, you should now see a submitable form in your module position.

=== Add Ajax functionality ===

We remind you of the best practice to use a component for Ajax response. Since Joomla! version 3.2 a new component com_ajax is included in the Joomla! package. If you don't have a component, you can use that to get more secure handling for modules and plugins. We will use this interface here.

Read more [[Using_Joomla_Ajax_Interface|Using Joomla Ajax Interface]]. You can also follow the examples from that document.

User:Over/Step by step to a Joomla Module - Data retrieval and styling

2014-09-08T14:11:05Z

Over: /* helper.php - The sql commands */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== Introduction ===

In this step we will extend "Your module" to retrieve data from a database table in two ways, direct access to a table and using a components methods. You have to have installed the module you created in former parts of the tutorial, before you start to follow this part.

=== Data retrieval ===

As in the previous parts you copy a skeleton file to your module folder in your Joomla path of the server. This time you copy the helper.php file to the "root" of the module.

==== helper.php ====

<source type="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' );

abstract class ModYourmoduleHelper
{
/**
* Get data from table
* @return array
*/
public static function getData($params)
{
//we will add some code here
}
}

</source>

The top of the file looks like any other of our php files. Copy your own comment lines from one of the php files you have edited in the former parts of the tutorial. Then we have a class definition with a name following a convention you as well should follow. Mod + The module name + Helper. A comment block follows describing what the following function does. We will add our code within the function ( in developer language called method ). You have to read the coding standards or have a look in any Joomla! core php file to learn more about coding and commenting conventions.

We will use an article to have a litle more dynamic data example. If you didn't create an article earlier in this tutorial series do that now. Keep it short as it's only an example. In the Module Manager you open your module and under the option tab you choose your article example. You see the title but actually the article id number is stored as parameter value.

In the first example we'll get the article text by sending sql statements to the Joomla! database API.

==== helper.php - The sql commands ====
<source type="php">

/**
* Get data from table
* @return array
*/
public static function getData($params)
{
//get article id from module parameter
$id = $params->get('article_id', 0);
if ( !$id )
{
return false;
}
//get the users authorisations
$user = JFactory::getUser();
$groups = implode(',', $user->getAuthorisedViewLevels());

$db = JFactory::getDbo();
//get a db query object
$query = $db->getQuery(true);
//select article id, title and introtext
$query->select(
array(
$db->quoteName('a.id'),
$db->quoteName('a.title'),
$db->quoteName('a.introtext'),
)
);
//from the article table
$query->from($db->quoteName('#__content', 'a'));
//id from parameter, we cast to integer
$query->where($db->quoteName('id') . ' = '. (int) $id);
// Only return if published
$query->where($db->quoteName('a.state') . ' = 1 ');
//and user is authorised to read
$query->where($this->db->quoteName('a.access') . ' IN (' . $groups . ')');

//uncomment this line to see the query string
//echo $query;

$db->setQuery($query);
try
{
//get the article
$result = $db->loadObject();
}
//check error
catch (RuntimeException $e)
{
//this is a module so we skip it if there are errors
// in other cases we would show a message
//$app = JFactory::getApplication();
//$app->enqueueMessage($e->getMessage(), 'error');

return false;
}

return $result;

}

</source>

See the brief comments in the text about what we are doing here.

Important security issue: use $db->quote($field_value) to avoid so called "sql-injections" for none integer or float variables. Be very careful when you build sql queries.

db->quoteName('field_name') escapes the name database dependent. We can't describe more details to Joomla! sql queries within this tutorial. More in [http://docs.joomla.org/Accessing_the_database_using_JDatabase Accessing the database using JDatabase]

As this is a module we don't show errormessages to the user. If there are errors the page will still be ok.

Copy the code to your helper.php replacing the method ( = function ) getData.

The helper file is loaded and run from mod_yourmodule.php. Open it and add the following between defined(... and require.

==== mod_yourmodule.php - Load helper class ====

<source type="php">

// Include the helper file that provide the data
require __DIR__ . '/helper.php';

//the class suffix from parameter
$moduleclass_sfx = htmlspecialchars($params->get('moduleclass_sfx'));

if ( !$article = ModYourmoduleHelper::getData($params))
{
//if error or article not found skip this module
return false;
}

//uncomment this line to see the available fields
//var_dump($article);

</source>

At the same time we get the class suffix from the parameter. Explained below.
Now that you have the article data, we will change the output file to show it. Remember? /tmpl/default.php

==== default.php - Show article ====

<source type="php">

defined('_JEXEC') or die('Restricted access');
?>
<div class="yourmodule<?php echo $moduleclass_sfx ?>">

<h4><?php echo $article->title; ?></h4>

<div><?php echo $article->introtext; ?></div>

</div>
</source>

After defined(... and the php closing tab we change the html. We use embedded php code to echo the title and the introtext. We add a module specific class $moduleclass sfx to the div tag. $moduleclass sfx is the class suffix the user can add in the Module Manager -> tab Advanced. This can be used for Css styling if multiple instances of the same module are enabled. e.g. you can test to reuse your module by choosing another article. We will style them in the next step.

=== Css styling ===
Best practice on a website is to '''try''' to keep all css styling in one file. As you don't know if the users template shows your module as designed, you have to include a css file. Not really for what we have above, but in a tutorial we do as if. You should use the parameters we created in a former part, to let the user of the module exclude your css. Described in the Overrides part of the tutorial.

We will not only prepare for loading css but also for images and javascript. Best practice is to store those files in subfolders of the Joomla media folder. Please don't ask why this folder was named media.

Create folder path/to/your/joomla/media/mod_yourmodule. In the folder where you unpacked the tutorial zip file you'll find a media folder. Open this and copy all three subfolders to the new folder in your web folder. It should result in something like this

<pre>
...
/logs
/media
...
/mod_yourmodule *new directory*
/css *new directory*
yourmodule.css *new file*
/images *new directory*
doc.png *new file*
yourmodule-logo.png *new file*
/js *new directory*
yourmodule.js *new file*
yourmodule_ajax.js *new file*
...
/modules
...
</pre>

Did you use your module name? You don´t have to, but it´s a good practice to use distinct names.

=== Add Css file ===

We include the module specific css file to the header of the html document.

==== default.php - Include Css file and image ====

<source>

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

JHtml::stylesheet('mod_yourmodule/yourmodule.css', false, true, false);
?>
<div class="yourmodule<?php echo $moduleclass_sfx ?>">

<div class="row text-center">
<?php echo JHtml::image('mod_yourmodule/yourmodule-logo.png', 'Yourmodule logo', '', true, false );?>
</div>

<h4><?php echo $article->title; ?></h4>

<div><?php echo $article->introtext; ?></div>

</div>

</source>

With this code added yourmodule.css will be loaded from the path media/mod_yourmodule/css/
Be aware of the missing /css/ ! This is added by Joomla. The image will be loaded from the path media/mod_yourmodule/images/.

Let's test that the css is working by adding a few lines to the yourmodule.css file. Open it with the editor and add e.g. those lines that change text color. Do we have to mention the module name that was used as css class?

==== yourmodule.css ====
<source>
.yourmodule h4{
color: #08c;
}
.yourmodule p {
color: #005580;
}
</source>

On your frontend page the colors should have changed and an image added. Have a look! Be aware that your browser may have cached the css.

=== Update the xml and the zip file ===

Now we have to add the new files to the xml file and create an updated installation zip file.

Add the helper.php and the special media tag to the xml file.

==== mod_yourmodule.xml - Add helper.php ====

Add helper.php to the files tag.

<source>

<files>
<filename>helper.php</filename>
<filename>mod_yourmodule.xml</filename>
<filename module="mod_yourmodule">mod_yourmodule.php</filename>
<folder>tmpl</folder>
</files>

</source>

==== mod_yourmodule.xml - Add media folder ====

Add the media tag between files and languages.

<source>

</files>
<media destination="mod_yourmodule" folder="media">
<folder>css</folder>
<folder>images</folder>
<folder>js</folder>
</media>
<languages folder="langs">

</source>

=== Create the installation file ===

Now you copy '''all''' module files from the server to the path 'somewhere'/j_module_tutorial/new_module as in the 'Installation package' part of this tutorial.
Create a new folder 'media' and copy the three folders from media/mod_yourmodule.

<pre>
.../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
/language
/en-GB
en-GB.mod_yourmodule.sys.ini
/anyother-language
anyother-language.mod_yourmodule.sys.ini
/media
/css
yourmodule.css
/images
doc.png
yourmodule-logo.png
/js
yourmodule.js
/tmpl
default.php
mod_yourmodule.php
mod_yourmodule.xml
</pre>

Create the compressed installation zip file as described in the 'Installation package' part of this tutorial.

That's it for this tutorial. Below we describe an alternative for data retrieval.

=== Use a component for data retrieval ===

Below is an alternative to using direct sql. You can use the methods provided by a component to retrieve the data. If you develop your own component, you can prepare methods for reuse, otherwise you can try to find a method in a components models to retrieve the data you want. Here we reuse the getItem method of the content component ( articles ). In this case you get all article data returned. If you use a lot of modules of this type on the same page, be a little aware of momory usage. If you want to test it, you only have to replace the getData method in helper.php.

To see the data available you can uncomment the var_dump line in mod_yourmodule.php.

==== helper.php Use of component ====

<source lang="php">
public static function getData($params)
{
//get article id from module parameter
$id = $params->get('article_id', 0);
if ( !$id )
{
return false;
}

$model = JModelLegacy::getInstance('Article', 'ContentModel', array('ignore_request' => true));

$app = JFactory::getApplication('site');

$model->setState('article.id', $id);
$model->setState('list.offset', 0);

// Load the parameters.
$params = $app->getParams('com_content');
$model->setState('params', $params);

$user = JFactory::getUser();

if ((!$user->authorise('core.edit.state', 'com_content')) && (!$user->authorise('core.edit', 'com_content')))
{
$model->setState('filter.published', 1);
$model->setState('filter.archived', 2);
}

$model->setState('filter.language', JLanguageMultilang::isEnabled());

return $model->getItem($id);;

</source>

=== Add javascript to the module ===

If you want to use javascript for yourmodule, here is an example. It loads the javascript file in the media/mod_yourmodule/js path and adds a script to the header of the html document.

Read more [[J3.x:Javascript_Frameworks|J3.x:Javascript Frameworks]]

==== default.php Javascript ====
<source>
JHtml::_('bootstrap.framework');

JHtml::script('mod_yourmodule/yourmodule.js', false, true, false, false, false);

$document = JFactory::getDocument();
$document->addScriptDeclaration('jQuery( document ).ready(function()
{
alert(\'I am an alert box!\');});'
);
</source>

Add this code below the line that loads the css file if you want to test it.

* We use jQuery so we have to load it '''before''' our own modules script. Here we load the Bootstrap framework that also includes jQuery. Use JHtml::_('jquery.framework') if you only need this.
* We add our scriptfile "relative" to the media folder.
* We add the script declaration directly to the document object. It gets added to the header in the html document.

User:Over/Step by step to a Joomla Module - Data retrieval and styling

2014-09-08T13:56:07Z

Over: /* mod_yourmodule.php - Load helper class */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== Introduction ===

In this step we will extend "Your module" to retrieve data from a database table in two ways, direct access to a table and using a components methods. You have to have installed the module you created in former parts of the tutorial, before you start to follow this part.

=== Data retrieval ===

As in the previous parts you copy a skeleton file to your module folder in your Joomla path of the server. This time you copy the helper.php file to the "root" of the module.

==== helper.php ====

<source type="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' );

abstract class ModYourmoduleHelper
{
/**
* Get data from table
* @return array
*/
public static function getData($params)
{
//we will add some code here
}
}

</source>

The top of the file looks like any other of our php files. Copy your own comment lines from one of the php files you have edited in the former parts of the tutorial. Then we have a class definition with a name following a convention you as well should follow. Mod + The module name + Helper. A comment block follows describing what the following function does. We will add our code within the function ( in developer language called method ). You have to read the coding standards or have a look in any Joomla! core php file to learn more about coding and commenting conventions.

We will use an article to have a litle more dynamic data example. If you didn't create an article earlier in this tutorial series do that now. Keep it short as it's only an example. In the Module Manager you open your module and under the option tab you choose your article example. You see the title but actually the article id number is stored as parameter value.

In the first example we'll get the article text by sending sql statements to the Joomla! database API.

==== helper.php - The sql commands ====
<source type="php">

/**
* Get data from table
* @return array
*/
public static function getData($params)
{
//get article id from module parameter
$id = $params->get('article_id', 0);
if ( !$id )
{
return false;
}
//get the users authorisations
$user = JFactory::getUser();
$groups = implode(',', $user->getAuthorisedViewLevels());

$db = JFactory::getDbo();
//get a db query object
$query = $db->getQuery(true);
//select article id, title and introtext
$query->select(
array(
$db->quoteName('a.id'),
$db->quoteName('a.title'),
$db->quoteName('a.introtext'),
)
);
//from the article table
$query->from($db->quoteName('#__content', 'a'));
//id from parameter, we cast to integer
$query->where($db->quoteName('id') . ' = '. (int) $id);
// Only return if published
$query->where($db->quoteName('a.state') . ' = 1 ');
//and user is authorised to read
$query->where('a.access IN (' . $groups . ')');

//uncomment this line to see the query string
//echo $query;

$db->setQuery($query);
try
{
//get the article
$result = $db->loadObject();
}
//check error
catch (RuntimeException $e)
{
//this is a module so we skip it if there are errors
// in other cases we would show a message
//$app = JFactory::getApplication();
//$app->enqueueMessage($e->getMessage(), 'error');

return false;
}

return $result;

}

</source>

See the brief comments in the text about what we are doing here.

Important security issue: use $db->quote($field_value) to avoid so called "sql-injections" for none integer or float variables. Be very careful when you build sql queries.

We can't describe the details to Joomla! sql queries within this tutorial. More in [http://docs.joomla.org/Accessing_the_database_using_JDatabase Accessing the database using JDatabase]

As this is a module we don't show errormessages to the user. If there are errors the page will still be ok.

Copy the code to your helper.php replacing the method ( = function ) getData.

The helper file is loaded and run from mod_yourmodule.php. Open it and add the following between defined(... and require.

==== mod_yourmodule.php - Load helper class ====

<source type="php">

// Include the helper file that provide the data
require __DIR__ . '/helper.php';

//the class suffix from parameter
$moduleclass_sfx = htmlspecialchars($params->get('moduleclass_sfx'));

if ( !$article = ModYourmoduleHelper::getData($params))
{
//if error or article not found skip this module
return false;
}

//uncomment this line to see the available fields
//var_dump($article);

</source>

At the same time we get the class suffix from the parameter. Explained below.
Now that you have the article data, we will change the output file to show it. Remember? /tmpl/default.php

==== default.php - Show article ====

<source type="php">

defined('_JEXEC') or die('Restricted access');
?>
<div class="yourmodule<?php echo $moduleclass_sfx ?>">

<h4><?php echo $article->title; ?></h4>

<div><?php echo $article->introtext; ?></div>

</div>
</source>

After defined(... and the php closing tab we change the html. We use embedded php code to echo the title and the introtext. We add a module specific class $moduleclass sfx to the div tag. $moduleclass sfx is the class suffix the user can add in the Module Manager -> tab Advanced. This can be used for Css styling if multiple instances of the same module are enabled. e.g. you can test to reuse your module by choosing another article. We will style them in the next step.

=== Css styling ===
Best practice on a website is to '''try''' to keep all css styling in one file. As you don't know if the users template shows your module as designed, you have to include a css file. Not really for what we have above, but in a tutorial we do as if. You should use the parameters we created in a former part, to let the user of the module exclude your css. Described in the Overrides part of the tutorial.

We will not only prepare for loading css but also for images and javascript. Best practice is to store those files in subfolders of the Joomla media folder. Please don't ask why this folder was named media.

Create folder path/to/your/joomla/media/mod_yourmodule. In the folder where you unpacked the tutorial zip file you'll find a media folder. Open this and copy all three subfolders to the new folder in your web folder. It should result in something like this

<pre>
...
/logs
/media
...
/mod_yourmodule *new directory*
/css *new directory*
yourmodule.css *new file*
/images *new directory*
doc.png *new file*
yourmodule-logo.png *new file*
/js *new directory*
yourmodule.js *new file*
yourmodule_ajax.js *new file*
...
/modules
...
</pre>

Did you use your module name? You don´t have to, but it´s a good practice to use distinct names.

=== Add Css file ===

We include the module specific css file to the header of the html document.

==== default.php - Include Css file and image ====

<source>

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

JHtml::stylesheet('mod_yourmodule/yourmodule.css', false, true, false);
?>
<div class="yourmodule<?php echo $moduleclass_sfx ?>">

<div class="row text-center">
<?php echo JHtml::image('mod_yourmodule/yourmodule-logo.png', 'Yourmodule logo', '', true, false );?>
</div>

<h4><?php echo $article->title; ?></h4>

<div><?php echo $article->introtext; ?></div>

</div>

</source>

With this code added yourmodule.css will be loaded from the path media/mod_yourmodule/css/
Be aware of the missing /css/ ! This is added by Joomla. The image will be loaded from the path media/mod_yourmodule/images/.

Let's test that the css is working by adding a few lines to the yourmodule.css file. Open it with the editor and add e.g. those lines that change text color. Do we have to mention the module name that was used as css class?

==== yourmodule.css ====
<source>
.yourmodule h4{
color: #08c;
}
.yourmodule p {
color: #005580;
}
</source>

On your frontend page the colors should have changed and an image added. Have a look! Be aware that your browser may have cached the css.

=== Update the xml and the zip file ===

Now we have to add the new files to the xml file and create an updated installation zip file.

Add the helper.php and the special media tag to the xml file.

==== mod_yourmodule.xml - Add helper.php ====

Add helper.php to the files tag.

<source>

<files>
<filename>helper.php</filename>
<filename>mod_yourmodule.xml</filename>
<filename module="mod_yourmodule">mod_yourmodule.php</filename>
<folder>tmpl</folder>
</files>

</source>

==== mod_yourmodule.xml - Add media folder ====

Add the media tag between files and languages.

<source>

</files>
<media destination="mod_yourmodule" folder="media">
<folder>css</folder>
<folder>images</folder>
<folder>js</folder>
</media>
<languages folder="langs">

</source>

=== Create the installation file ===

Now you copy '''all''' module files from the server to the path 'somewhere'/j_module_tutorial/new_module as in the 'Installation package' part of this tutorial.
Create a new folder 'media' and copy the three folders from media/mod_yourmodule.

<pre>
.../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
/language
/en-GB
en-GB.mod_yourmodule.sys.ini
/anyother-language
anyother-language.mod_yourmodule.sys.ini
/media
/css
yourmodule.css
/images
doc.png
yourmodule-logo.png
/js
yourmodule.js
/tmpl
default.php
mod_yourmodule.php
mod_yourmodule.xml
</pre>

Create the compressed installation zip file as described in the 'Installation package' part of this tutorial.

That's it for this tutorial. Below we describe an alternative for data retrieval.

=== Use a component for data retrieval ===

Below is an alternative to using direct sql. You can use the methods provided by a component to retrieve the data. If you develop your own component, you can prepare methods for reuse, otherwise you can try to find a method in a components models to retrieve the data you want. Here we reuse the getItem method of the content component ( articles ). In this case you get all article data returned. If you use a lot of modules of this type on the same page, be a little aware of momory usage. If you want to test it, you only have to replace the getData method in helper.php.

To see the data available you can uncomment the var_dump line in mod_yourmodule.php.

==== helper.php Use of component ====

<source lang="php">
public static function getData($params)
{
//get article id from module parameter
$id = $params->get('article_id', 0);
if ( !$id )
{
return false;
}

$model = JModelLegacy::getInstance('Article', 'ContentModel', array('ignore_request' => true));

$app = JFactory::getApplication('site');

$model->setState('article.id', $id);
$model->setState('list.offset', 0);

// Load the parameters.
$params = $app->getParams('com_content');
$model->setState('params', $params);

$user = JFactory::getUser();

if ((!$user->authorise('core.edit.state', 'com_content')) && (!$user->authorise('core.edit', 'com_content')))
{
$model->setState('filter.published', 1);
$model->setState('filter.archived', 2);
}

$model->setState('filter.language', JLanguageMultilang::isEnabled());

return $model->getItem($id);;

</source>

=== Add javascript to the module ===

If you want to use javascript for yourmodule, here is an example. It loads the javascript file in the media/mod_yourmodule/js path and adds a script to the header of the html document.

Read more [[J3.x:Javascript_Frameworks|J3.x:Javascript Frameworks]]

==== default.php Javascript ====
<source>
JHtml::_('bootstrap.framework');

JHtml::script('mod_yourmodule/yourmodule.js', false, true, false, false, false);

$document = JFactory::getDocument();
$document->addScriptDeclaration('jQuery( document ).ready(function()
{
alert(\'I am an alert box!\');});'
);
</source>

Add this code below the line that loads the css file if you want to test it.

* We use jQuery so we have to load it '''before''' our own modules script. Here we load the Bootstrap framework that also includes jQuery. Use JHtml::_('jquery.framework') if you only need this.
* We add our scriptfile "relative" to the media folder.
* We add the script declaration directly to the document object. It gets added to the header in the html document.

User:Over/Step by step to a Joomla Module - Data retrieval and styling

2014-09-08T13:52:42Z

Over: /* helper.php - The sql commands */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== Introduction ===

In this step we will extend "Your module" to retrieve data from a database table in two ways, direct access to a table and using a components methods. You have to have installed the module you created in former parts of the tutorial, before you start to follow this part.

=== Data retrieval ===

As in the previous parts you copy a skeleton file to your module folder in your Joomla path of the server. This time you copy the helper.php file to the "root" of the module.

==== helper.php ====

<source type="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' );

abstract class ModYourmoduleHelper
{
/**
* Get data from table
* @return array
*/
public static function getData($params)
{
//we will add some code here
}
}

</source>

The top of the file looks like any other of our php files. Copy your own comment lines from one of the php files you have edited in the former parts of the tutorial. Then we have a class definition with a name following a convention you as well should follow. Mod + The module name + Helper. A comment block follows describing what the following function does. We will add our code within the function ( in developer language called method ). You have to read the coding standards or have a look in any Joomla! core php file to learn more about coding and commenting conventions.

We will use an article to have a litle more dynamic data example. If you didn't create an article earlier in this tutorial series do that now. Keep it short as it's only an example. In the Module Manager you open your module and under the option tab you choose your article example. You see the title but actually the article id number is stored as parameter value.

In the first example we'll get the article text by sending sql statements to the Joomla! database API.

==== helper.php - The sql commands ====
<source type="php">

/**
* Get data from table
* @return array
*/
public static function getData($params)
{
//get article id from module parameter
$id = $params->get('article_id', 0);
if ( !$id )
{
return false;
}
//get the users authorisations
$user = JFactory::getUser();
$groups = implode(',', $user->getAuthorisedViewLevels());

$db = JFactory::getDbo();
//get a db query object
$query = $db->getQuery(true);
//select article id, title and introtext
$query->select(
array(
$db->quoteName('a.id'),
$db->quoteName('a.title'),
$db->quoteName('a.introtext'),
)
);
//from the article table
$query->from($db->quoteName('#__content', 'a'));
//id from parameter, we cast to integer
$query->where($db->quoteName('id') . ' = '. (int) $id);
// Only return if published
$query->where($db->quoteName('a.state') . ' = 1 ');
//and user is authorised to read
$query->where('a.access IN (' . $groups . ')');

//uncomment this line to see the query string
//echo $query;

$db->setQuery($query);
try
{
//get the article
$result = $db->loadObject();
}
//check error
catch (RuntimeException $e)
{
//this is a module so we skip it if there are errors
// in other cases we would show a message
//$app = JFactory::getApplication();
//$app->enqueueMessage($e->getMessage(), 'error');

return false;
}

return $result;

}

</source>

See the brief comments in the text about what we are doing here.

Important security issue: use $db->quote($field_value) to avoid so called "sql-injections" for none integer or float variables. Be very careful when you build sql queries.

We can't describe the details to Joomla! sql queries within this tutorial. More in [http://docs.joomla.org/Accessing_the_database_using_JDatabase Accessing the database using JDatabase]

As this is a module we don't show errormessages to the user. If there are errors the page will still be ok.

Copy the code to your helper.php replacing the method ( = function ) getData.

The helper file is loaded and run from mod_yourmodule.php. Open it and add the following between defined(... and require.

==== mod_yourmodule.php - Load helper class ====

<source type="php">

// Include the helper file that provide the data
require_once __DIR__ . '/helper.php';

//the class suffix from parameter
$moduleclass_sfx = htmlspecialchars($params->get('moduleclass_sfx'));

if ( !$article = ModYourmoduleHelper::getData($params))
{
//if error or article not found skip this module
return false;
}

//uncomment this line to see the available fields
//var_dump($article);

</source>

At the same time we get the class suffix from the parameter. Explained below.
Now that you have the article data, we will change the output file to show it. Remember? /tmpl/default.php

==== default.php - Show article ====

<source type="php">

defined('_JEXEC') or die('Restricted access');
?>
<div class="yourmodule<?php echo $moduleclass_sfx ?>">

<h4><?php echo $article->title; ?></h4>

<div><?php echo $article->introtext; ?></div>

</div>
</source>

After defined(... and the php closing tab we change the html. We use embedded php code to echo the title and the introtext. We add a module specific class $moduleclass sfx to the div tag. $moduleclass sfx is the class suffix the user can add in the Module Manager -> tab Advanced. This can be used for Css styling if multiple instances of the same module are enabled. e.g. you can test to reuse your module by choosing another article. We will style them in the next step.

=== Css styling ===
Best practice on a website is to '''try''' to keep all css styling in one file. As you don't know if the users template shows your module as designed, you have to include a css file. Not really for what we have above, but in a tutorial we do as if. You should use the parameters we created in a former part, to let the user of the module exclude your css. Described in the Overrides part of the tutorial.

We will not only prepare for loading css but also for images and javascript. Best practice is to store those files in subfolders of the Joomla media folder. Please don't ask why this folder was named media.

Create folder path/to/your/joomla/media/mod_yourmodule. In the folder where you unpacked the tutorial zip file you'll find a media folder. Open this and copy all three subfolders to the new folder in your web folder. It should result in something like this

<pre>
...
/logs
/media
...
/mod_yourmodule *new directory*
/css *new directory*
yourmodule.css *new file*
/images *new directory*
doc.png *new file*
yourmodule-logo.png *new file*
/js *new directory*
yourmodule.js *new file*
yourmodule_ajax.js *new file*
...
/modules
...
</pre>

Did you use your module name? You don´t have to, but it´s a good practice to use distinct names.

=== Add Css file ===

We include the module specific css file to the header of the html document.

==== default.php - Include Css file and image ====

<source>

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

JHtml::stylesheet('mod_yourmodule/yourmodule.css', false, true, false);
?>
<div class="yourmodule<?php echo $moduleclass_sfx ?>">

<div class="row text-center">
<?php echo JHtml::image('mod_yourmodule/yourmodule-logo.png', 'Yourmodule logo', '', true, false );?>
</div>

<h4><?php echo $article->title; ?></h4>

<div><?php echo $article->introtext; ?></div>

</div>

</source>

With this code added yourmodule.css will be loaded from the path media/mod_yourmodule/css/
Be aware of the missing /css/ ! This is added by Joomla. The image will be loaded from the path media/mod_yourmodule/images/.

Let's test that the css is working by adding a few lines to the yourmodule.css file. Open it with the editor and add e.g. those lines that change text color. Do we have to mention the module name that was used as css class?

==== yourmodule.css ====
<source>
.yourmodule h4{
color: #08c;
}
.yourmodule p {
color: #005580;
}
</source>

On your frontend page the colors should have changed and an image added. Have a look! Be aware that your browser may have cached the css.

=== Update the xml and the zip file ===

Now we have to add the new files to the xml file and create an updated installation zip file.

Add the helper.php and the special media tag to the xml file.

==== mod_yourmodule.xml - Add helper.php ====

Add helper.php to the files tag.

<source>

<files>
<filename>helper.php</filename>
<filename>mod_yourmodule.xml</filename>
<filename module="mod_yourmodule">mod_yourmodule.php</filename>
<folder>tmpl</folder>
</files>

</source>

==== mod_yourmodule.xml - Add media folder ====

Add the media tag between files and languages.

<source>

</files>
<media destination="mod_yourmodule" folder="media">
<folder>css</folder>
<folder>images</folder>
<folder>js</folder>
</media>
<languages folder="langs">

</source>

=== Create the installation file ===

Now you copy '''all''' module files from the server to the path 'somewhere'/j_module_tutorial/new_module as in the 'Installation package' part of this tutorial.
Create a new folder 'media' and copy the three folders from media/mod_yourmodule.

<pre>
.../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
/language
/en-GB
en-GB.mod_yourmodule.sys.ini
/anyother-language
anyother-language.mod_yourmodule.sys.ini
/media
/css
yourmodule.css
/images
doc.png
yourmodule-logo.png
/js
yourmodule.js
/tmpl
default.php
mod_yourmodule.php
mod_yourmodule.xml
</pre>

Create the compressed installation zip file as described in the 'Installation package' part of this tutorial.

That's it for this tutorial. Below we describe an alternative for data retrieval.

=== Use a component for data retrieval ===

Below is an alternative to using direct sql. You can use the methods provided by a component to retrieve the data. If you develop your own component, you can prepare methods for reuse, otherwise you can try to find a method in a components models to retrieve the data you want. Here we reuse the getItem method of the content component ( articles ). In this case you get all article data returned. If you use a lot of modules of this type on the same page, be a little aware of momory usage. If you want to test it, you only have to replace the getData method in helper.php.

To see the data available you can uncomment the var_dump line in mod_yourmodule.php.

==== helper.php Use of component ====

<source lang="php">
public static function getData($params)
{
//get article id from module parameter
$id = $params->get('article_id', 0);
if ( !$id )
{
return false;
}

$model = JModelLegacy::getInstance('Article', 'ContentModel', array('ignore_request' => true));

$app = JFactory::getApplication('site');

$model->setState('article.id', $id);
$model->setState('list.offset', 0);

// Load the parameters.
$params = $app->getParams('com_content');
$model->setState('params', $params);

$user = JFactory::getUser();

if ((!$user->authorise('core.edit.state', 'com_content')) && (!$user->authorise('core.edit', 'com_content')))
{
$model->setState('filter.published', 1);
$model->setState('filter.archived', 2);
}

$model->setState('filter.language', JLanguageMultilang::isEnabled());

return $model->getItem($id);;

</source>

=== Add javascript to the module ===

If you want to use javascript for yourmodule, here is an example. It loads the javascript file in the media/mod_yourmodule/js path and adds a script to the header of the html document.

Read more [[J3.x:Javascript_Frameworks|J3.x:Javascript Frameworks]]

==== default.php Javascript ====
<source>
JHtml::_('bootstrap.framework');

JHtml::script('mod_yourmodule/yourmodule.js', false, true, false, false, false);

$document = JFactory::getDocument();
$document->addScriptDeclaration('jQuery( document ).ready(function()
{
alert(\'I am an alert box!\');});'
);
</source>

Add this code below the line that loads the css file if you want to test it.

* We use jQuery so we have to load it '''before''' our own modules script. Here we load the Bootstrap framework that also includes jQuery. Use JHtml::_('jquery.framework') if you only need this.
* We add our scriptfile "relative" to the media folder.
* We add the script declaration directly to the document object. It gets added to the header in the html document.

User:Over/Step by step to a Joomla Module - Data retrieval and styling

2014-09-07T08:51:00Z

Over: /* default.php - Include Css file and image */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== Introduction ===

In this step we will extend "Your module" to retrieve data from a database table in two ways, direct access to a table and using a components methods. You have to have installed the module you created in former parts of the tutorial, before you start to follow this part.

=== Data retrieval ===

As in the previous parts you copy a skeleton file to your module folder in your Joomla path of the server. This time you copy the helper.php file to the "root" of the module.

==== helper.php ====

<source type="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' );

abstract class ModYourmoduleHelper
{
/**
* Get data from table
* @return array
*/
public static function getData($params)
{
//we will add some code here
}
}

</source>

The top of the file looks like any other of our php files. Copy your own comment lines from one of the php files you have edited in the former parts of the tutorial. Then we have a class definition with a name following a convention you as well should follow. Mod + The module name + Helper. A comment block follows describing what the following function does. We will add our code within the function ( in developer language called method ). You have to read the coding standards or have a look in any Joomla! core php file to learn more about coding and commenting conventions.

We will use an article to have a litle more dynamic data example. If you didn't create an article earlier in this tutorial series do that now. Keep it short as it's only an example. In the Module Manager you open your module and under the option tab you choose your article example. You see the title but actually the article id number is stored as parameter value.

In the first example we'll get the article text by sending sql statements to the Joomla! database API.

==== helper.php - The sql commands ====
<source type="php">

/**
* Get data from table
* @return array
*/
public static function getData($params)
{
//get article id from module parameter
$id = $params->get('article_id', 0);
if ( !$id )
{
return false;
}
//get the users authorisations
$user = JFactory::getUser();
$groups = implode(',', $user->getAuthorisedViewLevels());

$db = JFactory::getDbo();
//get a db query object
$query = $db->getQuery(true);
//select article id, title and introtext
$query->select(
array(
$db->quoteName('a.id'),
$db->quoteName('a.title'),
$db->quoteName('a.introtext'),
)
);
//from the article table
$query->from($db->quoteName('#__content', 'a'));
//id from parameter, we are conservative enough to cast the id
$query->where($db->quoteName('id') . ' = '. $db->quote( (int) $id));
// Only return if published
$query->where($db->quoteName('a.state') . ' = 1 ');
//and user is authorised to read
$query->where('a.access IN (' . $groups . ')');

//uncomment this line to see the query string
//echo $query;

$db->setQuery($query);
try
{
//get the article
$result = $db->loadObject();
}
//check error
catch (RuntimeException $e)
{
//this is a module so we skip it if there are errors
// in other cases we would show a message
//$app = JFactory::getApplication();
//$app->enqueueMessage($e->getMessage(), 'error');

return false;
}

return $result;

}

</source>

See the brief comments in the text about what we are doing here. Important security issue: use $db->quote('field_value') to avoid so called "sql-injections". Be very careful when you build sql queries. We can't describe the details to Joomla! sql queries within this tutorial. More in [http://docs.joomla.org/Accessing_the_database_using_JDatabase Accessing the database using JDatabase]

As this is a module we don't show errormessages to the user. If there are errors the page will still be ok.

Copy the code to your helper.php replacing the method ( = function ) getData.

The helper file is loaded and run from mod_yourmodule.php. Open it and add the following between defined(... and require.

==== mod_yourmodule.php - Load helper class ====

<source type="php">

// Include the helper file that provide the data
require_once __DIR__ . '/helper.php';

//the class suffix from parameter
$moduleclass_sfx = htmlspecialchars($params->get('moduleclass_sfx'));

if ( !$article = ModYourmoduleHelper::getData($params))
{
//if error or article not found skip this module
return false;
}

//uncomment this line to see the available fields
//var_dump($article);

</source>

At the same time we get the class suffix from the parameter. Explained below.
Now that you have the article data, we will change the output file to show it. Remember? /tmpl/default.php

==== default.php - Show article ====

<source type="php">

defined('_JEXEC') or die('Restricted access');
?>
<div class="yourmodule<?php echo $moduleclass_sfx ?>">

<h4><?php echo $article->title; ?></h4>

<div><?php echo $article->introtext; ?></div>

</div>
</source>

After defined(... and the php closing tab we change the html. We use embedded php code to echo the title and the introtext. We add a module specific class $moduleclass sfx to the div tag. $moduleclass sfx is the class suffix the user can add in the Module Manager -> tab Advanced. This can be used for Css styling if multiple instances of the same module are enabled. e.g. you can test to reuse your module by choosing another article. We will style them in the next step.

=== Css styling ===
Best practice on a website is to '''try''' to keep all css styling in one file. As you don't know if the users template shows your module as designed, you have to include a css file. Not really for what we have above, but in a tutorial we do as if. You should use the parameters we created in a former part, to let the user of the module exclude your css. Described in the Overrides part of the tutorial.

We will not only prepare for loading css but also for images and javascript. Best practice is to store those files in subfolders of the Joomla media folder. Please don't ask why this folder was named media.

Create folder path/to/your/joomla/media/mod_yourmodule. In the folder where you unpacked the tutorial zip file you'll find a media folder. Open this and copy all three subfolders to the new folder in your web folder. It should result in something like this

<pre>
...
/logs
/media
...
/mod_yourmodule *new directory*
/css *new directory*
yourmodule.css *new file*
/images *new directory*
doc.png *new file*
yourmodule-logo.png *new file*
/js *new directory*
yourmodule.js *new file*
yourmodule_ajax.js *new file*
...
/modules
...
</pre>

Did you use your module name? You don´t have to, but it´s a good practice to use distinct names.

=== Add Css file ===

We include the module specific css file to the header of the html document.

==== default.php - Include Css file and image ====

<source>

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

JHtml::stylesheet('mod_yourmodule/yourmodule.css', false, true, false);
?>
<div class="yourmodule<?php echo $moduleclass_sfx ?>">

<div class="row text-center">
<?php echo JHtml::image('mod_yourmodule/yourmodule-logo.png', 'Yourmodule logo', '', true, false );?>
</div>

<h4><?php echo $article->title; ?></h4>

<div><?php echo $article->introtext; ?></div>

</div>

</source>

With this code added yourmodule.css will be loaded from the path media/mod_yourmodule/css/
Be aware of the missing /css/ ! This is added by Joomla. The image will be loaded from the path media/mod_yourmodule/images/.

Let's test that the css is working by adding a few lines to the yourmodule.css file. Open it with the editor and add e.g. those lines that change text color. Do we have to mention the module name that was used as css class?

==== yourmodule.css ====
<source>
.yourmodule h4{
color: #08c;
}
.yourmodule p {
color: #005580;
}
</source>

On your frontend page the colors should have changed and an image added. Have a look! Be aware that your browser may have cached the css.

=== Update the xml and the zip file ===

Now we have to add the new files to the xml file and create an updated installation zip file.

Add the helper.php and the special media tag to the xml file.

==== mod_yourmodule.xml - Add helper.php ====

Add helper.php to the files tag.

<source>

<files>
<filename>helper.php</filename>
<filename>mod_yourmodule.xml</filename>
<filename module="mod_yourmodule">mod_yourmodule.php</filename>
<folder>tmpl</folder>
</files>

</source>

==== mod_yourmodule.xml - Add media folder ====

Add the media tag between files and languages.

<source>

</files>
<media destination="mod_yourmodule" folder="media">
<folder>css</folder>
<folder>images</folder>
<folder>js</folder>
</media>
<languages folder="langs">

</source>

=== Create the installation file ===

Now you copy '''all''' module files from the server to the path 'somewhere'/j_module_tutorial/new_module as in the 'Installation package' part of this tutorial.
Create a new folder 'media' and copy the three folders from media/mod_yourmodule.

<pre>
.../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
/language
/en-GB
en-GB.mod_yourmodule.sys.ini
/anyother-language
anyother-language.mod_yourmodule.sys.ini
/media
/css
yourmodule.css
/images
doc.png
yourmodule-logo.png
/js
yourmodule.js
/tmpl
default.php
mod_yourmodule.php
mod_yourmodule.xml
</pre>

Create the compressed installation zip file as described in the 'Installation package' part of this tutorial.

That's it for this tutorial. Below we describe an alternative for data retrieval.

=== Use a component for data retrieval ===

Below is an alternative to using direct sql. You can use the methods provided by a component to retrieve the data. If you develop your own component, you can prepare methods for reuse, otherwise you can try to find a method in a components models to retrieve the data you want. Here we reuse the getItem method of the content component ( articles ). In this case you get all article data returned. If you use a lot of modules of this type on the same page, be a little aware of momory usage. If you want to test it, you only have to replace the getData method in helper.php.

To see the data available you can uncomment the var_dump line in mod_yourmodule.php.

==== helper.php Use of component ====

<source lang="php">
public static function getData($params)
{
//get article id from module parameter
$id = $params->get('article_id', 0);
if ( !$id )
{
return false;
}

$model = JModelLegacy::getInstance('Article', 'ContentModel', array('ignore_request' => true));

$app = JFactory::getApplication('site');

$model->setState('article.id', $id);
$model->setState('list.offset', 0);

// Load the parameters.
$params = $app->getParams('com_content');
$model->setState('params', $params);

$user = JFactory::getUser();

if ((!$user->authorise('core.edit.state', 'com_content')) && (!$user->authorise('core.edit', 'com_content')))
{
$model->setState('filter.published', 1);
$model->setState('filter.archived', 2);
}

$model->setState('filter.language', JLanguageMultilang::isEnabled());

return $model->getItem($id);;

</source>

=== Add javascript to the module ===

If you want to use javascript for yourmodule, here is an example. It loads the javascript file in the media/mod_yourmodule/js path and adds a script to the header of the html document.

Read more [[J3.x:Javascript_Frameworks|J3.x:Javascript Frameworks]]

==== default.php Javascript ====
<source>
JHtml::_('bootstrap.framework');

JHtml::script('mod_yourmodule/yourmodule.js', false, true, false, false, false);

$document = JFactory::getDocument();
$document->addScriptDeclaration('jQuery( document ).ready(function()
{
alert(\'I am an alert box!\');});'
);
</source>

Add this code below the line that loads the css file if you want to test it.

* We use jQuery so we have to load it '''before''' our own modules script. Here we load the Bootstrap framework that also includes jQuery. Use JHtml::_('jquery.framework') if you only need this.
* We add our scriptfile "relative" to the media folder.
* We add the script declaration directly to the document object. It gets added to the header in the html document.

User:Over/Step by step to a Joomla Module - Data retrieval and styling

2014-09-07T08:49:42Z

Over: /* default.php - Include Css file and image */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== Introduction ===

In this step we will extend "Your module" to retrieve data from a database table in two ways, direct access to a table and using a components methods. You have to have installed the module you created in former parts of the tutorial, before you start to follow this part.

=== Data retrieval ===

As in the previous parts you copy a skeleton file to your module folder in your Joomla path of the server. This time you copy the helper.php file to the "root" of the module.

==== helper.php ====

<source type="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' );

abstract class ModYourmoduleHelper
{
/**
* Get data from table
* @return array
*/
public static function getData($params)
{
//we will add some code here
}
}

</source>

The top of the file looks like any other of our php files. Copy your own comment lines from one of the php files you have edited in the former parts of the tutorial. Then we have a class definition with a name following a convention you as well should follow. Mod + The module name + Helper. A comment block follows describing what the following function does. We will add our code within the function ( in developer language called method ). You have to read the coding standards or have a look in any Joomla! core php file to learn more about coding and commenting conventions.

We will use an article to have a litle more dynamic data example. If you didn't create an article earlier in this tutorial series do that now. Keep it short as it's only an example. In the Module Manager you open your module and under the option tab you choose your article example. You see the title but actually the article id number is stored as parameter value.

In the first example we'll get the article text by sending sql statements to the Joomla! database API.

==== helper.php - The sql commands ====
<source type="php">

/**
* Get data from table
* @return array
*/
public static function getData($params)
{
//get article id from module parameter
$id = $params->get('article_id', 0);
if ( !$id )
{
return false;
}
//get the users authorisations
$user = JFactory::getUser();
$groups = implode(',', $user->getAuthorisedViewLevels());

$db = JFactory::getDbo();
//get a db query object
$query = $db->getQuery(true);
//select article id, title and introtext
$query->select(
array(
$db->quoteName('a.id'),
$db->quoteName('a.title'),
$db->quoteName('a.introtext'),
)
);
//from the article table
$query->from($db->quoteName('#__content', 'a'));
//id from parameter, we are conservative enough to cast the id
$query->where($db->quoteName('id') . ' = '. $db->quote( (int) $id));
// Only return if published
$query->where($db->quoteName('a.state') . ' = 1 ');
//and user is authorised to read
$query->where('a.access IN (' . $groups . ')');

//uncomment this line to see the query string
//echo $query;

$db->setQuery($query);
try
{
//get the article
$result = $db->loadObject();
}
//check error
catch (RuntimeException $e)
{
//this is a module so we skip it if there are errors
// in other cases we would show a message
//$app = JFactory::getApplication();
//$app->enqueueMessage($e->getMessage(), 'error');

return false;
}

return $result;

}

</source>

See the brief comments in the text about what we are doing here. Important security issue: use $db->quote('field_value') to avoid so called "sql-injections". Be very careful when you build sql queries. We can't describe the details to Joomla! sql queries within this tutorial. More in [http://docs.joomla.org/Accessing_the_database_using_JDatabase Accessing the database using JDatabase]

As this is a module we don't show errormessages to the user. If there are errors the page will still be ok.

Copy the code to your helper.php replacing the method ( = function ) getData.

The helper file is loaded and run from mod_yourmodule.php. Open it and add the following between defined(... and require.

==== mod_yourmodule.php - Load helper class ====

<source type="php">

// Include the helper file that provide the data
require_once __DIR__ . '/helper.php';

//the class suffix from parameter
$moduleclass_sfx = htmlspecialchars($params->get('moduleclass_sfx'));

if ( !$article = ModYourmoduleHelper::getData($params))
{
//if error or article not found skip this module
return false;
}

//uncomment this line to see the available fields
//var_dump($article);

</source>

At the same time we get the class suffix from the parameter. Explained below.
Now that you have the article data, we will change the output file to show it. Remember? /tmpl/default.php

==== default.php - Show article ====

<source type="php">

defined('_JEXEC') or die('Restricted access');
?>
<div class="yourmodule<?php echo $moduleclass_sfx ?>">

<h4><?php echo $article->title; ?></h4>

<div><?php echo $article->introtext; ?></div>

</div>
</source>

After defined(... and the php closing tab we change the html. We use embedded php code to echo the title and the introtext. We add a module specific class $moduleclass sfx to the div tag. $moduleclass sfx is the class suffix the user can add in the Module Manager -> tab Advanced. This can be used for Css styling if multiple instances of the same module are enabled. e.g. you can test to reuse your module by choosing another article. We will style them in the next step.

=== Css styling ===
Best practice on a website is to '''try''' to keep all css styling in one file. As you don't know if the users template shows your module as designed, you have to include a css file. Not really for what we have above, but in a tutorial we do as if. You should use the parameters we created in a former part, to let the user of the module exclude your css. Described in the Overrides part of the tutorial.

We will not only prepare for loading css but also for images and javascript. Best practice is to store those files in subfolders of the Joomla media folder. Please don't ask why this folder was named media.

Create folder path/to/your/joomla/media/mod_yourmodule. In the folder where you unpacked the tutorial zip file you'll find a media folder. Open this and copy all three subfolders to the new folder in your web folder. It should result in something like this

<pre>
...
/logs
/media
...
/mod_yourmodule *new directory*
/css *new directory*
yourmodule.css *new file*
/images *new directory*
doc.png *new file*
yourmodule-logo.png *new file*
/js *new directory*
yourmodule.js *new file*
yourmodule_ajax.js *new file*
...
/modules
...
</pre>

Did you use your module name? You don´t have to, but it´s a good practice to use distinct names.

=== Add Css file ===

We include the module specific css file to the header of the html document.

==== default.php - Include Css file and image ====

<source>

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

JHtml::stylesheet('mod_yourmodule/yourmodule.css', false, true, false);
?>
<div class="yourmodule<?php echo $moduleclass_sfx ?>">

<div class="row text-center">
<?php echo JHtml::image('mod_yourmodule/yourmodule-logo.png', 'Yourmodule logo', '', true, false );?>
</div>

<h4><?php echo $article->title; ?></h4>

<div><?php echo $article->introtext; ?></div>

</div>

</source>

With this code added yourmodule.css will be loaded from the path media/mod_yourmodule/css/
Be aware of the missing /css/ ! This is added by Joomla. The image will be loaded from the path media/mod_yourmodule/images/.

Let's test that the css is working by adding a few lines to the yourmodule.css file. Open it with the editor and add e.g. those lines that change text color. Do we have to mention the module name that was as css class?

==== yourmodule.css ====
<source>
.yourmodule h4{
color: #08c;
}
.yourmodule p {
color: #005580;
}
</source>

On your frontend page the colors should have changed and an image added. Have a look! Be aware that your browser may have cached the css.

=== Update the xml and the zip file ===

Now we have to add the new files to the xml file and create an updated installation zip file.

Add the helper.php and the special media tag to the xml file.

==== mod_yourmodule.xml - Add helper.php ====

Add helper.php to the files tag.

<source>

<files>
<filename>helper.php</filename>
<filename>mod_yourmodule.xml</filename>
<filename module="mod_yourmodule">mod_yourmodule.php</filename>
<folder>tmpl</folder>
</files>

</source>

==== mod_yourmodule.xml - Add media folder ====

Add the media tag between files and languages.

<source>

</files>
<media destination="mod_yourmodule" folder="media">
<folder>css</folder>
<folder>images</folder>
<folder>js</folder>
</media>
<languages folder="langs">

</source>

=== Create the installation file ===

Now you copy '''all''' module files from the server to the path 'somewhere'/j_module_tutorial/new_module as in the 'Installation package' part of this tutorial.
Create a new folder 'media' and copy the three folders from media/mod_yourmodule.

<pre>
.../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
/language
/en-GB
en-GB.mod_yourmodule.sys.ini
/anyother-language
anyother-language.mod_yourmodule.sys.ini
/media
/css
yourmodule.css
/images
doc.png
yourmodule-logo.png
/js
yourmodule.js
/tmpl
default.php
mod_yourmodule.php
mod_yourmodule.xml
</pre>

Create the compressed installation zip file as described in the 'Installation package' part of this tutorial.

That's it for this tutorial. Below we describe an alternative for data retrieval.

=== Use a component for data retrieval ===

Below is an alternative to using direct sql. You can use the methods provided by a component to retrieve the data. If you develop your own component, you can prepare methods for reuse, otherwise you can try to find a method in a components models to retrieve the data you want. Here we reuse the getItem method of the content component ( articles ). In this case you get all article data returned. If you use a lot of modules of this type on the same page, be a little aware of momory usage. If you want to test it, you only have to replace the getData method in helper.php.

To see the data available you can uncomment the var_dump line in mod_yourmodule.php.

==== helper.php Use of component ====

<source lang="php">
public static function getData($params)
{
//get article id from module parameter
$id = $params->get('article_id', 0);
if ( !$id )
{
return false;
}

$model = JModelLegacy::getInstance('Article', 'ContentModel', array('ignore_request' => true));

$app = JFactory::getApplication('site');

$model->setState('article.id', $id);
$model->setState('list.offset', 0);

// Load the parameters.
$params = $app->getParams('com_content');
$model->setState('params', $params);

$user = JFactory::getUser();

if ((!$user->authorise('core.edit.state', 'com_content')) && (!$user->authorise('core.edit', 'com_content')))
{
$model->setState('filter.published', 1);
$model->setState('filter.archived', 2);
}

$model->setState('filter.language', JLanguageMultilang::isEnabled());

return $model->getItem($id);;

</source>

=== Add javascript to the module ===

If you want to use javascript for yourmodule, here is an example. It loads the javascript file in the media/mod_yourmodule/js path and adds a script to the header of the html document.

Read more [[J3.x:Javascript_Frameworks|J3.x:Javascript Frameworks]]

==== default.php Javascript ====
<source>
JHtml::_('bootstrap.framework');

JHtml::script('mod_yourmodule/yourmodule.js', false, true, false, false, false);

$document = JFactory::getDocument();
$document->addScriptDeclaration('jQuery( document ).ready(function()
{
alert(\'I am an alert box!\');});'
);
</source>

Add this code below the line that loads the css file if you want to test it.

* We use jQuery so we have to load it '''before''' our own modules script. Here we load the Bootstrap framework that also includes jQuery. Use JHtml::_('jquery.framework') if you only need this.
* We add our scriptfile "relative" to the media folder.
* We add the script declaration directly to the document object. It gets added to the header in the html document.

User:Over/Step by step to a Joomla Module - Data retrieval and styling

2014-09-07T08:46:00Z

Over: /* default.php Javascript */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== Introduction ===

In this step we will extend "Your module" to retrieve data from a database table in two ways, direct access to a table and using a components methods. You have to have installed the module you created in former parts of the tutorial, before you start to follow this part.

=== Data retrieval ===

As in the previous parts you copy a skeleton file to your module folder in your Joomla path of the server. This time you copy the helper.php file to the "root" of the module.

==== helper.php ====

<source type="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' );

abstract class ModYourmoduleHelper
{
/**
* Get data from table
* @return array
*/
public static function getData($params)
{
//we will add some code here
}
}

</source>

The top of the file looks like any other of our php files. Copy your own comment lines from one of the php files you have edited in the former parts of the tutorial. Then we have a class definition with a name following a convention you as well should follow. Mod + The module name + Helper. A comment block follows describing what the following function does. We will add our code within the function ( in developer language called method ). You have to read the coding standards or have a look in any Joomla! core php file to learn more about coding and commenting conventions.

We will use an article to have a litle more dynamic data example. If you didn't create an article earlier in this tutorial series do that now. Keep it short as it's only an example. In the Module Manager you open your module and under the option tab you choose your article example. You see the title but actually the article id number is stored as parameter value.

In the first example we'll get the article text by sending sql statements to the Joomla! database API.

==== helper.php - The sql commands ====
<source type="php">

/**
* Get data from table
* @return array
*/
public static function getData($params)
{
//get article id from module parameter
$id = $params->get('article_id', 0);
if ( !$id )
{
return false;
}
//get the users authorisations
$user = JFactory::getUser();
$groups = implode(',', $user->getAuthorisedViewLevels());

$db = JFactory::getDbo();
//get a db query object
$query = $db->getQuery(true);
//select article id, title and introtext
$query->select(
array(
$db->quoteName('a.id'),
$db->quoteName('a.title'),
$db->quoteName('a.introtext'),
)
);
//from the article table
$query->from($db->quoteName('#__content', 'a'));
//id from parameter, we are conservative enough to cast the id
$query->where($db->quoteName('id') . ' = '. $db->quote( (int) $id));
// Only return if published
$query->where($db->quoteName('a.state') . ' = 1 ');
//and user is authorised to read
$query->where('a.access IN (' . $groups . ')');

//uncomment this line to see the query string
//echo $query;

$db->setQuery($query);
try
{
//get the article
$result = $db->loadObject();
}
//check error
catch (RuntimeException $e)
{
//this is a module so we skip it if there are errors
// in other cases we would show a message
//$app = JFactory::getApplication();
//$app->enqueueMessage($e->getMessage(), 'error');

return false;
}

return $result;

}

</source>

See the brief comments in the text about what we are doing here. Important security issue: use $db->quote('field_value') to avoid so called "sql-injections". Be very careful when you build sql queries. We can't describe the details to Joomla! sql queries within this tutorial. More in [http://docs.joomla.org/Accessing_the_database_using_JDatabase Accessing the database using JDatabase]

As this is a module we don't show errormessages to the user. If there are errors the page will still be ok.

Copy the code to your helper.php replacing the method ( = function ) getData.

The helper file is loaded and run from mod_yourmodule.php. Open it and add the following between defined(... and require.

==== mod_yourmodule.php - Load helper class ====

<source type="php">

// Include the helper file that provide the data
require_once __DIR__ . '/helper.php';

//the class suffix from parameter
$moduleclass_sfx = htmlspecialchars($params->get('moduleclass_sfx'));

if ( !$article = ModYourmoduleHelper::getData($params))
{
//if error or article not found skip this module
return false;
}

//uncomment this line to see the available fields
//var_dump($article);

</source>

At the same time we get the class suffix from the parameter. Explained below.
Now that you have the article data, we will change the output file to show it. Remember? /tmpl/default.php

==== default.php - Show article ====

<source type="php">

defined('_JEXEC') or die('Restricted access');
?>
<div class="yourmodule<?php echo $moduleclass_sfx ?>">

<h4><?php echo $article->title; ?></h4>

<div><?php echo $article->introtext; ?></div>

</div>
</source>

After defined(... and the php closing tab we change the html. We use embedded php code to echo the title and the introtext. We add a module specific class $moduleclass sfx to the div tag. $moduleclass sfx is the class suffix the user can add in the Module Manager -> tab Advanced. This can be used for Css styling if multiple instances of the same module are enabled. e.g. you can test to reuse your module by choosing another article. We will style them in the next step.

=== Css styling ===
Best practice on a website is to '''try''' to keep all css styling in one file. As you don't know if the users template shows your module as designed, you have to include a css file. Not really for what we have above, but in a tutorial we do as if. You should use the parameters we created in a former part, to let the user of the module exclude your css. Described in the Overrides part of the tutorial.

We will not only prepare for loading css but also for images and javascript. Best practice is to store those files in subfolders of the Joomla media folder. Please don't ask why this folder was named media.

Create folder path/to/your/joomla/media/mod_yourmodule. In the folder where you unpacked the tutorial zip file you'll find a media folder. Open this and copy all three subfolders to the new folder in your web folder. It should result in something like this

<pre>
...
/logs
/media
...
/mod_yourmodule *new directory*
/css *new directory*
yourmodule.css *new file*
/images *new directory*
doc.png *new file*
yourmodule-logo.png *new file*
/js *new directory*
yourmodule.js *new file*
yourmodule_ajax.js *new file*
...
/modules
...
</pre>

Did you use your module name? You don´t have to, but it´s a good practice to use distinct names.

=== Add Css file ===

We include the module specific css file to the header of the html document.

==== default.php - Include Css file and image ====

<source>

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

JHtml::stylesheet('mod_yourmodule/yourmodule.css', false, true, false);
?>
<div class="yourmodule<?php echo $moduleclass_sfx ?>">

<div class="row text-center">
<?php echo JHtml::image('mod_yourmodule/yourmodule-logo.png', 'Yourmodule logo', '', true, false );?>
</div>

<h4><?php echo $article->title; ?></h4>

<div><?php echo $article->introtext; ?></div>

</div>

</source>

With this code added yourmodule.css will be loaded from the path media/mod_yourmodule/css/
Be aware of the missing /css/ ! This is added by Joomla. The image will be loaded from the path media/mod_yourmodule/images/.

Let's test that the css is working by adding a few lines to the yourmodule.css file. Open it with the editor and add e.g. those lines that change text color. Do we have to mention the module name?

==== yourmodule.css ====
<source>
.yourmodule h4{
color: #08c;
}
.yourmodule p {
color: #005580;
}
</source>

On your frontend page the colors should have changed and an image added. Have a look! Be aware that your browser may have cached the css.

=== Update the xml and the zip file ===

Now we have to add the new files to the xml file and create an updated installation zip file.

Add the helper.php and the special media tag to the xml file.

==== mod_yourmodule.xml - Add helper.php ====

Add helper.php to the files tag.

<source>

<files>
<filename>helper.php</filename>
<filename>mod_yourmodule.xml</filename>
<filename module="mod_yourmodule">mod_yourmodule.php</filename>
<folder>tmpl</folder>
</files>

</source>

==== mod_yourmodule.xml - Add media folder ====

Add the media tag between files and languages.

<source>

</files>
<media destination="mod_yourmodule" folder="media">
<folder>css</folder>
<folder>images</folder>
<folder>js</folder>
</media>
<languages folder="langs">

</source>

=== Create the installation file ===

Now you copy '''all''' module files from the server to the path 'somewhere'/j_module_tutorial/new_module as in the 'Installation package' part of this tutorial.
Create a new folder 'media' and copy the three folders from media/mod_yourmodule.

<pre>
.../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
/language
/en-GB
en-GB.mod_yourmodule.sys.ini
/anyother-language
anyother-language.mod_yourmodule.sys.ini
/media
/css
yourmodule.css
/images
doc.png
yourmodule-logo.png
/js
yourmodule.js
/tmpl
default.php
mod_yourmodule.php
mod_yourmodule.xml
</pre>

Create the compressed installation zip file as described in the 'Installation package' part of this tutorial.

That's it for this tutorial. Below we describe an alternative for data retrieval.

=== Use a component for data retrieval ===

Below is an alternative to using direct sql. You can use the methods provided by a component to retrieve the data. If you develop your own component, you can prepare methods for reuse, otherwise you can try to find a method in a components models to retrieve the data you want. Here we reuse the getItem method of the content component ( articles ). In this case you get all article data returned. If you use a lot of modules of this type on the same page, be a little aware of momory usage. If you want to test it, you only have to replace the getData method in helper.php.

To see the data available you can uncomment the var_dump line in mod_yourmodule.php.

==== helper.php Use of component ====

<source lang="php">
public static function getData($params)
{
//get article id from module parameter
$id = $params->get('article_id', 0);
if ( !$id )
{
return false;
}

$model = JModelLegacy::getInstance('Article', 'ContentModel', array('ignore_request' => true));

$app = JFactory::getApplication('site');

$model->setState('article.id', $id);
$model->setState('list.offset', 0);

// Load the parameters.
$params = $app->getParams('com_content');
$model->setState('params', $params);

$user = JFactory::getUser();

if ((!$user->authorise('core.edit.state', 'com_content')) && (!$user->authorise('core.edit', 'com_content')))
{
$model->setState('filter.published', 1);
$model->setState('filter.archived', 2);
}

$model->setState('filter.language', JLanguageMultilang::isEnabled());

return $model->getItem($id);;

</source>

=== Add javascript to the module ===

If you want to use javascript for yourmodule, here is an example. It loads the javascript file in the media/mod_yourmodule/js path and adds a script to the header of the html document.

Read more [[J3.x:Javascript_Frameworks|J3.x:Javascript Frameworks]]

==== default.php Javascript ====
<source>
JHtml::_('bootstrap.framework');

JHtml::script('mod_yourmodule/yourmodule.js', false, true, false, false, false);

$document = JFactory::getDocument();
$document->addScriptDeclaration('jQuery( document ).ready(function()
{
alert(\'I am an alert box!\');});'
);
</source>

Add this code below the line that loads the css file if you want to test it.

* We use jQuery so we have to load it '''before''' our own modules script. Here we load the Bootstrap framework that also includes jQuery. Use JHtml::_('jquery.framework') if you only need this.
* We add our scriptfile "relative" to the media folder.
* We add the script declaration directly to the document object. It gets added to the header in the html document.

User:Over/Step by step to a Joomla Module - Data retrieval and styling

2014-09-07T08:42:32Z

Over: /* Use a component for data retrieval */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== Introduction ===

In this step we will extend "Your module" to retrieve data from a database table in two ways, direct access to a table and using a components methods. You have to have installed the module you created in former parts of the tutorial, before you start to follow this part.

=== Data retrieval ===

As in the previous parts you copy a skeleton file to your module folder in your Joomla path of the server. This time you copy the helper.php file to the "root" of the module.

==== helper.php ====

<source type="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' );

abstract class ModYourmoduleHelper
{
/**
* Get data from table
* @return array
*/
public static function getData($params)
{
//we will add some code here
}
}

</source>

The top of the file looks like any other of our php files. Copy your own comment lines from one of the php files you have edited in the former parts of the tutorial. Then we have a class definition with a name following a convention you as well should follow. Mod + The module name + Helper. A comment block follows describing what the following function does. We will add our code within the function ( in developer language called method ). You have to read the coding standards or have a look in any Joomla! core php file to learn more about coding and commenting conventions.

We will use an article to have a litle more dynamic data example. If you didn't create an article earlier in this tutorial series do that now. Keep it short as it's only an example. In the Module Manager you open your module and under the option tab you choose your article example. You see the title but actually the article id number is stored as parameter value.

In the first example we'll get the article text by sending sql statements to the Joomla! database API.

==== helper.php - The sql commands ====
<source type="php">

/**
* Get data from table
* @return array
*/
public static function getData($params)
{
//get article id from module parameter
$id = $params->get('article_id', 0);
if ( !$id )
{
return false;
}
//get the users authorisations
$user = JFactory::getUser();
$groups = implode(',', $user->getAuthorisedViewLevels());

$db = JFactory::getDbo();
//get a db query object
$query = $db->getQuery(true);
//select article id, title and introtext
$query->select(
array(
$db->quoteName('a.id'),
$db->quoteName('a.title'),
$db->quoteName('a.introtext'),
)
);
//from the article table
$query->from($db->quoteName('#__content', 'a'));
//id from parameter, we are conservative enough to cast the id
$query->where($db->quoteName('id') . ' = '. $db->quote( (int) $id));
// Only return if published
$query->where($db->quoteName('a.state') . ' = 1 ');
//and user is authorised to read
$query->where('a.access IN (' . $groups . ')');

//uncomment this line to see the query string
//echo $query;

$db->setQuery($query);
try
{
//get the article
$result = $db->loadObject();
}
//check error
catch (RuntimeException $e)
{
//this is a module so we skip it if there are errors
// in other cases we would show a message
//$app = JFactory::getApplication();
//$app->enqueueMessage($e->getMessage(), 'error');

return false;
}

return $result;

}

</source>

See the brief comments in the text about what we are doing here. Important security issue: use $db->quote('field_value') to avoid so called "sql-injections". Be very careful when you build sql queries. We can't describe the details to Joomla! sql queries within this tutorial. More in [http://docs.joomla.org/Accessing_the_database_using_JDatabase Accessing the database using JDatabase]

As this is a module we don't show errormessages to the user. If there are errors the page will still be ok.

Copy the code to your helper.php replacing the method ( = function ) getData.

The helper file is loaded and run from mod_yourmodule.php. Open it and add the following between defined(... and require.

==== mod_yourmodule.php - Load helper class ====

<source type="php">

// Include the helper file that provide the data
require_once __DIR__ . '/helper.php';

//the class suffix from parameter
$moduleclass_sfx = htmlspecialchars($params->get('moduleclass_sfx'));

if ( !$article = ModYourmoduleHelper::getData($params))
{
//if error or article not found skip this module
return false;
}

//uncomment this line to see the available fields
//var_dump($article);

</source>

At the same time we get the class suffix from the parameter. Explained below.
Now that you have the article data, we will change the output file to show it. Remember? /tmpl/default.php

==== default.php - Show article ====

<source type="php">

defined('_JEXEC') or die('Restricted access');
?>
<div class="yourmodule<?php echo $moduleclass_sfx ?>">

<h4><?php echo $article->title; ?></h4>

<div><?php echo $article->introtext; ?></div>

</div>
</source>

After defined(... and the php closing tab we change the html. We use embedded php code to echo the title and the introtext. We add a module specific class $moduleclass sfx to the div tag. $moduleclass sfx is the class suffix the user can add in the Module Manager -> tab Advanced. This can be used for Css styling if multiple instances of the same module are enabled. e.g. you can test to reuse your module by choosing another article. We will style them in the next step.

=== Css styling ===
Best practice on a website is to '''try''' to keep all css styling in one file. As you don't know if the users template shows your module as designed, you have to include a css file. Not really for what we have above, but in a tutorial we do as if. You should use the parameters we created in a former part, to let the user of the module exclude your css. Described in the Overrides part of the tutorial.

We will not only prepare for loading css but also for images and javascript. Best practice is to store those files in subfolders of the Joomla media folder. Please don't ask why this folder was named media.

Create folder path/to/your/joomla/media/mod_yourmodule. In the folder where you unpacked the tutorial zip file you'll find a media folder. Open this and copy all three subfolders to the new folder in your web folder. It should result in something like this

<pre>
...
/logs
/media
...
/mod_yourmodule *new directory*
/css *new directory*
yourmodule.css *new file*
/images *new directory*
doc.png *new file*
yourmodule-logo.png *new file*
/js *new directory*
yourmodule.js *new file*
yourmodule_ajax.js *new file*
...
/modules
...
</pre>

Did you use your module name? You don´t have to, but it´s a good practice to use distinct names.

=== Add Css file ===

We include the module specific css file to the header of the html document.

==== default.php - Include Css file and image ====

<source>

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

JHtml::stylesheet('mod_yourmodule/yourmodule.css', false, true, false);
?>
<div class="yourmodule<?php echo $moduleclass_sfx ?>">

<div class="row text-center">
<?php echo JHtml::image('mod_yourmodule/yourmodule-logo.png', 'Yourmodule logo', '', true, false );?>
</div>

<h4><?php echo $article->title; ?></h4>

<div><?php echo $article->introtext; ?></div>

</div>

</source>

With this code added yourmodule.css will be loaded from the path media/mod_yourmodule/css/
Be aware of the missing /css/ ! This is added by Joomla. The image will be loaded from the path media/mod_yourmodule/images/.

Let's test that the css is working by adding a few lines to the yourmodule.css file. Open it with the editor and add e.g. those lines that change text color. Do we have to mention the module name?

==== yourmodule.css ====
<source>
.yourmodule h4{
color: #08c;
}
.yourmodule p {
color: #005580;
}
</source>

On your frontend page the colors should have changed and an image added. Have a look! Be aware that your browser may have cached the css.

=== Update the xml and the zip file ===

Now we have to add the new files to the xml file and create an updated installation zip file.

Add the helper.php and the special media tag to the xml file.

==== mod_yourmodule.xml - Add helper.php ====

Add helper.php to the files tag.

<source>

<files>
<filename>helper.php</filename>
<filename>mod_yourmodule.xml</filename>
<filename module="mod_yourmodule">mod_yourmodule.php</filename>
<folder>tmpl</folder>
</files>

</source>

==== mod_yourmodule.xml - Add media folder ====

Add the media tag between files and languages.

<source>

</files>
<media destination="mod_yourmodule" folder="media">
<folder>css</folder>
<folder>images</folder>
<folder>js</folder>
</media>
<languages folder="langs">

</source>

=== Create the installation file ===

Now you copy '''all''' module files from the server to the path 'somewhere'/j_module_tutorial/new_module as in the 'Installation package' part of this tutorial.
Create a new folder 'media' and copy the three folders from media/mod_yourmodule.

<pre>
.../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
/language
/en-GB
en-GB.mod_yourmodule.sys.ini
/anyother-language
anyother-language.mod_yourmodule.sys.ini
/media
/css
yourmodule.css
/images
doc.png
yourmodule-logo.png
/js
yourmodule.js
/tmpl
default.php
mod_yourmodule.php
mod_yourmodule.xml
</pre>

Create the compressed installation zip file as described in the 'Installation package' part of this tutorial.

That's it for this tutorial. Below we describe an alternative for data retrieval.

=== Use a component for data retrieval ===

Below is an alternative to using direct sql. You can use the methods provided by a component to retrieve the data. If you develop your own component, you can prepare methods for reuse, otherwise you can try to find a method in a components models to retrieve the data you want. Here we reuse the getItem method of the content component ( articles ). In this case you get all article data returned. If you use a lot of modules of this type on the same page, be a little aware of momory usage. If you want to test it, you only have to replace the getData method in helper.php.

To see the data available you can uncomment the var_dump line in mod_yourmodule.php.

==== helper.php Use of component ====

<source lang="php">
public static function getData($params)
{
//get article id from module parameter
$id = $params->get('article_id', 0);
if ( !$id )
{
return false;
}

$model = JModelLegacy::getInstance('Article', 'ContentModel', array('ignore_request' => true));

$app = JFactory::getApplication('site');

$model->setState('article.id', $id);
$model->setState('list.offset', 0);

// Load the parameters.
$params = $app->getParams('com_content');
$model->setState('params', $params);

$user = JFactory::getUser();

if ((!$user->authorise('core.edit.state', 'com_content')) && (!$user->authorise('core.edit', 'com_content')))
{
$model->setState('filter.published', 1);
$model->setState('filter.archived', 2);
}

$model->setState('filter.language', JLanguageMultilang::isEnabled());

return $model->getItem($id);;

</source>

=== Add javascript to the module ===

If you want to use javascript for yourmodule, here is an example. It loads the javascript file in the media/mod_yourmodule/js path and adds a script to the header of the html document.

Read more [[J3.x:Javascript_Frameworks|J3.x:Javascript Frameworks]]

==== default.php Javascript ====
<source>
JHtml::_('bootstrap.framework');

JHtml::script('mod_yourmodule/yourmodule.js', false, true, false, false, false);

$document = JFactory::getDocument();
$document->addScriptDeclaration('jQuery( document ).ready(function()
{
alert(\'I am an alert box!\');});'
);
</source>

Add this code below the line that loads the css file if you want to test it.

* We use jQuery so we have to load it '''before''' our own modulescript. Here we load the Bootstrap framework that also includes jQuery. Use JHtml::_('jquery.framework') if you only need this.
* We add our scriptfile "relative" to the media folder.
* We add the script declaration directly to the document object. It gets added to the header in the html document.

User:Over/Step by step to a Joomla Module - Data retrieval and styling

2014-09-07T08:27:54Z

Over: /* default.php Javascript */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== Introduction ===

In this step we will extend "Your module" to retrieve data from a database table in two ways, direct access to a table and using a components methods. You have to have installed the module you created in former parts of the tutorial, before you start to follow this part.

=== Data retrieval ===

As in the previous parts you copy a skeleton file to your module folder in your Joomla path of the server. This time you copy the helper.php file to the "root" of the module.

==== helper.php ====

<source type="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' );

abstract class ModYourmoduleHelper
{
/**
* Get data from table
* @return array
*/
public static function getData($params)
{
//we will add some code here
}
}

</source>

The top of the file looks like any other of our php files. Copy your own comment lines from one of the php files you have edited in the former parts of the tutorial. Then we have a class definition with a name following a convention you as well should follow. Mod + The module name + Helper. A comment block follows describing what the following function does. We will add our code within the function ( in developer language called method ). You have to read the coding standards or have a look in any Joomla! core php file to learn more about coding and commenting conventions.

We will use an article to have a litle more dynamic data example. If you didn't create an article earlier in this tutorial series do that now. Keep it short as it's only an example. In the Module Manager you open your module and under the option tab you choose your article example. You see the title but actually the article id number is stored as parameter value.

In the first example we'll get the article text by sending sql statements to the Joomla! database API.

==== helper.php - The sql commands ====
<source type="php">

/**
* Get data from table
* @return array
*/
public static function getData($params)
{
//get article id from module parameter
$id = $params->get('article_id', 0);
if ( !$id )
{
return false;
}
//get the users authorisations
$user = JFactory::getUser();
$groups = implode(',', $user->getAuthorisedViewLevels());

$db = JFactory::getDbo();
//get a db query object
$query = $db->getQuery(true);
//select article id, title and introtext
$query->select(
array(
$db->quoteName('a.id'),
$db->quoteName('a.title'),
$db->quoteName('a.introtext'),
)
);
//from the article table
$query->from($db->quoteName('#__content', 'a'));
//id from parameter, we are conservative enough to cast the id
$query->where($db->quoteName('id') . ' = '. $db->quote( (int) $id));
// Only return if published
$query->where($db->quoteName('a.state') . ' = 1 ');
//and user is authorised to read
$query->where('a.access IN (' . $groups . ')');

//uncomment this line to see the query string
//echo $query;

$db->setQuery($query);
try
{
//get the article
$result = $db->loadObject();
}
//check error
catch (RuntimeException $e)
{
//this is a module so we skip it if there are errors
// in other cases we would show a message
//$app = JFactory::getApplication();
//$app->enqueueMessage($e->getMessage(), 'error');

return false;
}

return $result;

}

</source>

See the brief comments in the text about what we are doing here. Important security issue: use $db->quote('field_value') to avoid so called "sql-injections". Be very careful when you build sql queries. We can't describe the details to Joomla! sql queries within this tutorial. More in [http://docs.joomla.org/Accessing_the_database_using_JDatabase Accessing the database using JDatabase]

As this is a module we don't show errormessages to the user. If there are errors the page will still be ok.

Copy the code to your helper.php replacing the method ( = function ) getData.

The helper file is loaded and run from mod_yourmodule.php. Open it and add the following between defined(... and require.

==== mod_yourmodule.php - Load helper class ====

<source type="php">

// Include the helper file that provide the data
require_once __DIR__ . '/helper.php';

//the class suffix from parameter
$moduleclass_sfx = htmlspecialchars($params->get('moduleclass_sfx'));

if ( !$article = ModYourmoduleHelper::getData($params))
{
//if error or article not found skip this module
return false;
}

//uncomment this line to see the available fields
//var_dump($article);

</source>

At the same time we get the class suffix from the parameter. Explained below.
Now that you have the article data, we will change the output file to show it. Remember? /tmpl/default.php

==== default.php - Show article ====

<source type="php">

defined('_JEXEC') or die('Restricted access');
?>
<div class="yourmodule<?php echo $moduleclass_sfx ?>">

<h4><?php echo $article->title; ?></h4>

<div><?php echo $article->introtext; ?></div>

</div>
</source>

After defined(... and the php closing tab we change the html. We use embedded php code to echo the title and the introtext. We add a module specific class $moduleclass sfx to the div tag. $moduleclass sfx is the class suffix the user can add in the Module Manager -> tab Advanced. This can be used for Css styling if multiple instances of the same module are enabled. e.g. you can test to reuse your module by choosing another article. We will style them in the next step.

=== Css styling ===
Best practice on a website is to '''try''' to keep all css styling in one file. As you don't know if the users template shows your module as designed, you have to include a css file. Not really for what we have above, but in a tutorial we do as if. You should use the parameters we created in a former part, to let the user of the module exclude your css. Described in the Overrides part of the tutorial.

We will not only prepare for loading css but also for images and javascript. Best practice is to store those files in subfolders of the Joomla media folder. Please don't ask why this folder was named media.

Create folder path/to/your/joomla/media/mod_yourmodule. In the folder where you unpacked the tutorial zip file you'll find a media folder. Open this and copy all three subfolders to the new folder in your web folder. It should result in something like this

<pre>
...
/logs
/media
...
/mod_yourmodule *new directory*
/css *new directory*
yourmodule.css *new file*
/images *new directory*
doc.png *new file*
yourmodule-logo.png *new file*
/js *new directory*
yourmodule.js *new file*
yourmodule_ajax.js *new file*
...
/modules
...
</pre>

Did you use your module name? You don´t have to, but it´s a good practice to use distinct names.

=== Add Css file ===

We include the module specific css file to the header of the html document.

==== default.php - Include Css file and image ====

<source>

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

JHtml::stylesheet('mod_yourmodule/yourmodule.css', false, true, false);
?>
<div class="yourmodule<?php echo $moduleclass_sfx ?>">

<div class="row text-center">
<?php echo JHtml::image('mod_yourmodule/yourmodule-logo.png', 'Yourmodule logo', '', true, false );?>
</div>

<h4><?php echo $article->title; ?></h4>

<div><?php echo $article->introtext; ?></div>

</div>

</source>

With this code added yourmodule.css will be loaded from the path media/mod_yourmodule/css/
Be aware of the missing /css/ ! This is added by Joomla. The image will be loaded from the path media/mod_yourmodule/images/.

Let's test that the css is working by adding a few lines to the yourmodule.css file. Open it with the editor and add e.g. those lines that change text color. Do we have to mention the module name?

==== yourmodule.css ====
<source>
.yourmodule h4{
color: #08c;
}
.yourmodule p {
color: #005580;
}
</source>

On your frontend page the colors should have changed and an image added. Have a look! Be aware that your browser may have cached the css.

=== Update the xml and the zip file ===

Now we have to add the new files to the xml file and create an updated installation zip file.

Add the helper.php and the special media tag to the xml file.

==== mod_yourmodule.xml - Add helper.php ====

Add helper.php to the files tag.

<source>

<files>
<filename>helper.php</filename>
<filename>mod_yourmodule.xml</filename>
<filename module="mod_yourmodule">mod_yourmodule.php</filename>
<folder>tmpl</folder>
</files>

</source>

==== mod_yourmodule.xml - Add media folder ====

Add the media tag between files and languages.

<source>

</files>
<media destination="mod_yourmodule" folder="media">
<folder>css</folder>
<folder>images</folder>
<folder>js</folder>
</media>
<languages folder="langs">

</source>

=== Create the installation file ===

Now you copy '''all''' module files from the server to the path 'somewhere'/j_module_tutorial/new_module as in the 'Installation package' part of this tutorial.
Create a new folder 'media' and copy the three folders from media/mod_yourmodule.

<pre>
.../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
/language
/en-GB
en-GB.mod_yourmodule.sys.ini
/anyother-language
anyother-language.mod_yourmodule.sys.ini
/media
/css
yourmodule.css
/images
doc.png
yourmodule-logo.png
/js
yourmodule.js
/tmpl
default.php
mod_yourmodule.php
mod_yourmodule.xml
</pre>

Create the compressed installation zip file as described in the 'Installation package' part of this tutorial.

That's it for this tutorial. Below we describe an alternative for data retrieval.

=== Use a component for data retrieval ===

Below is an alternative to using direct sql. You can use the methods provided by a component to retrieve the data. If you develop your own component, you can prepare methods for reuse, otherwise you can try to find a method in a components models to retrieve the data you want. Here we reuse the getItem method of the content component ( articles ). In this case you get all article data returned so be a little aware of momory usage. If you want to test it, you only have to replace the getData method in helper.php

==== helper.php Use of component ====

<source lang="php">
public static function getData($params)
{
//get article id from module parameter
$id = $params->get('article_id', 0);
if ( !$id )
{
return false;
}

$model = JModelLegacy::getInstance('Article', 'ContentModel', array('ignore_request' => true));

$app = JFactory::getApplication('site');

$model->setState('article.id', $id);
$model->setState('list.offset', 0);

// Load the parameters.
$params = $app->getParams('com_content');
$model->setState('params', $params);

$user = JFactory::getUser();

if ((!$user->authorise('core.edit.state', 'com_content')) && (!$user->authorise('core.edit', 'com_content')))
{
$model->setState('filter.published', 1);
$model->setState('filter.archived', 2);
}

$model->setState('filter.language', JLanguageMultilang::isEnabled());

return $model->getItem($id);;

</source>

=== Add javascript to the module ===

If you want to use javascript for yourmodule, here is an example. It loads the javascript file in the media/mod_yourmodule/js path and adds a script to the header of the html document.

Read more [[J3.x:Javascript_Frameworks|J3.x:Javascript Frameworks]]

==== default.php Javascript ====
<source>
JHtml::_('bootstrap.framework');

JHtml::script('mod_yourmodule/yourmodule.js', false, true, false, false, false);

$document = JFactory::getDocument();
$document->addScriptDeclaration('jQuery( document ).ready(function()
{
alert(\'I am an alert box!\');});'
);
</source>

Add this code below the line that loads the css file if you want to test it.

* We use jQuery so we have to load it '''before''' our own modulescript. Here we load the Bootstrap framework that also includes jQuery. Use JHtml::_('jquery.framework') if you only need this.
* We add our scriptfile "relative" to the media folder.
* We add the script declaration directly to the document object. It gets added to the header in the html document.

User:Over/Step by step to a Joomla Module - Data retrieval and styling

2014-09-07T08:21:40Z

Over: /* Css styling */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== Introduction ===

In this step we will extend "Your module" to retrieve data from a database table in two ways, direct access to a table and using a components methods. You have to have installed the module you created in former parts of the tutorial, before you start to follow this part.

=== Data retrieval ===

As in the previous parts you copy a skeleton file to your module folder in your Joomla path of the server. This time you copy the helper.php file to the "root" of the module.

==== helper.php ====

<source type="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' );

abstract class ModYourmoduleHelper
{
/**
* Get data from table
* @return array
*/
public static function getData($params)
{
//we will add some code here
}
}

</source>

The top of the file looks like any other of our php files. Copy your own comment lines from one of the php files you have edited in the former parts of the tutorial. Then we have a class definition with a name following a convention you as well should follow. Mod + The module name + Helper. A comment block follows describing what the following function does. We will add our code within the function ( in developer language called method ). You have to read the coding standards or have a look in any Joomla! core php file to learn more about coding and commenting conventions.

We will use an article to have a litle more dynamic data example. If you didn't create an article earlier in this tutorial series do that now. Keep it short as it's only an example. In the Module Manager you open your module and under the option tab you choose your article example. You see the title but actually the article id number is stored as parameter value.

In the first example we'll get the article text by sending sql statements to the Joomla! database API.

==== helper.php - The sql commands ====
<source type="php">

/**
* Get data from table
* @return array
*/
public static function getData($params)
{
//get article id from module parameter
$id = $params->get('article_id', 0);
if ( !$id )
{
return false;
}
//get the users authorisations
$user = JFactory::getUser();
$groups = implode(',', $user->getAuthorisedViewLevels());

$db = JFactory::getDbo();
//get a db query object
$query = $db->getQuery(true);
//select article id, title and introtext
$query->select(
array(
$db->quoteName('a.id'),
$db->quoteName('a.title'),
$db->quoteName('a.introtext'),
)
);
//from the article table
$query->from($db->quoteName('#__content', 'a'));
//id from parameter, we are conservative enough to cast the id
$query->where($db->quoteName('id') . ' = '. $db->quote( (int) $id));
// Only return if published
$query->where($db->quoteName('a.state') . ' = 1 ');
//and user is authorised to read
$query->where('a.access IN (' . $groups . ')');

//uncomment this line to see the query string
//echo $query;

$db->setQuery($query);
try
{
//get the article
$result = $db->loadObject();
}
//check error
catch (RuntimeException $e)
{
//this is a module so we skip it if there are errors
// in other cases we would show a message
//$app = JFactory::getApplication();
//$app->enqueueMessage($e->getMessage(), 'error');

return false;
}

return $result;

}

</source>

See the brief comments in the text about what we are doing here. Important security issue: use $db->quote('field_value') to avoid so called "sql-injections". Be very careful when you build sql queries. We can't describe the details to Joomla! sql queries within this tutorial. More in [http://docs.joomla.org/Accessing_the_database_using_JDatabase Accessing the database using JDatabase]

As this is a module we don't show errormessages to the user. If there are errors the page will still be ok.

Copy the code to your helper.php replacing the method ( = function ) getData.

The helper file is loaded and run from mod_yourmodule.php. Open it and add the following between defined(... and require.

==== mod_yourmodule.php - Load helper class ====

<source type="php">

// Include the helper file that provide the data
require_once __DIR__ . '/helper.php';

//the class suffix from parameter
$moduleclass_sfx = htmlspecialchars($params->get('moduleclass_sfx'));

if ( !$article = ModYourmoduleHelper::getData($params))
{
//if error or article not found skip this module
return false;
}

//uncomment this line to see the available fields
//var_dump($article);

</source>

At the same time we get the class suffix from the parameter. Explained below.
Now that you have the article data, we will change the output file to show it. Remember? /tmpl/default.php

==== default.php - Show article ====

<source type="php">

defined('_JEXEC') or die('Restricted access');
?>
<div class="yourmodule<?php echo $moduleclass_sfx ?>">

<h4><?php echo $article->title; ?></h4>

<div><?php echo $article->introtext; ?></div>

</div>
</source>

After defined(... and the php closing tab we change the html. We use embedded php code to echo the title and the introtext. We add a module specific class $moduleclass sfx to the div tag. $moduleclass sfx is the class suffix the user can add in the Module Manager -> tab Advanced. This can be used for Css styling if multiple instances of the same module are enabled. e.g. you can test to reuse your module by choosing another article. We will style them in the next step.

=== Css styling ===
Best practice on a website is to '''try''' to keep all css styling in one file. As you don't know if the users template shows your module as designed, you have to include a css file. Not really for what we have above, but in a tutorial we do as if. You should use the parameters we created in a former part, to let the user of the module exclude your css. Described in the Overrides part of the tutorial.

We will not only prepare for loading css but also for images and javascript. Best practice is to store those files in subfolders of the Joomla media folder. Please don't ask why this folder was named media.

Create folder path/to/your/joomla/media/mod_yourmodule. In the folder where you unpacked the tutorial zip file you'll find a media folder. Open this and copy all three subfolders to the new folder in your web folder. It should result in something like this

<pre>
...
/logs
/media
...
/mod_yourmodule *new directory*
/css *new directory*
yourmodule.css *new file*
/images *new directory*
doc.png *new file*
yourmodule-logo.png *new file*
/js *new directory*
yourmodule.js *new file*
yourmodule_ajax.js *new file*
...
/modules
...
</pre>

Did you use your module name? You don´t have to, but it´s a good practice to use distinct names.

=== Add Css file ===

We include the module specific css file to the header of the html document.

==== default.php - Include Css file and image ====

<source>

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

JHtml::stylesheet('mod_yourmodule/yourmodule.css', false, true, false);
?>
<div class="yourmodule<?php echo $moduleclass_sfx ?>">

<div class="row text-center">
<?php echo JHtml::image('mod_yourmodule/yourmodule-logo.png', 'Yourmodule logo', '', true, false );?>
</div>

<h4><?php echo $article->title; ?></h4>

<div><?php echo $article->introtext; ?></div>

</div>

</source>

With this code added yourmodule.css will be loaded from the path media/mod_yourmodule/css/
Be aware of the missing /css/ ! This is added by Joomla. The image will be loaded from the path media/mod_yourmodule/images/.

Let's test that the css is working by adding a few lines to the yourmodule.css file. Open it with the editor and add e.g. those lines that change text color. Do we have to mention the module name?

==== yourmodule.css ====
<source>
.yourmodule h4{
color: #08c;
}
.yourmodule p {
color: #005580;
}
</source>

On your frontend page the colors should have changed and an image added. Have a look! Be aware that your browser may have cached the css.

=== Update the xml and the zip file ===

Now we have to add the new files to the xml file and create an updated installation zip file.

Add the helper.php and the special media tag to the xml file.

==== mod_yourmodule.xml - Add helper.php ====

Add helper.php to the files tag.

<source>

<files>
<filename>helper.php</filename>
<filename>mod_yourmodule.xml</filename>
<filename module="mod_yourmodule">mod_yourmodule.php</filename>
<folder>tmpl</folder>
</files>

</source>

==== mod_yourmodule.xml - Add media folder ====

Add the media tag between files and languages.

<source>

</files>
<media destination="mod_yourmodule" folder="media">
<folder>css</folder>
<folder>images</folder>
<folder>js</folder>
</media>
<languages folder="langs">

</source>

=== Create the installation file ===

Now you copy '''all''' module files from the server to the path 'somewhere'/j_module_tutorial/new_module as in the 'Installation package' part of this tutorial.
Create a new folder 'media' and copy the three folders from media/mod_yourmodule.

<pre>
.../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
/language
/en-GB
en-GB.mod_yourmodule.sys.ini
/anyother-language
anyother-language.mod_yourmodule.sys.ini
/media
/css
yourmodule.css
/images
doc.png
yourmodule-logo.png
/js
yourmodule.js
/tmpl
default.php
mod_yourmodule.php
mod_yourmodule.xml
</pre>

Create the compressed installation zip file as described in the 'Installation package' part of this tutorial.

That's it for this tutorial. Below we describe an alternative for data retrieval.

=== Use a component for data retrieval ===

Below is an alternative to using direct sql. You can use the methods provided by a component to retrieve the data. If you develop your own component, you can prepare methods for reuse, otherwise you can try to find a method in a components models to retrieve the data you want. Here we reuse the getItem method of the content component ( articles ). In this case you get all article data returned so be a little aware of momory usage. If you want to test it, you only have to replace the getData method in helper.php

==== helper.php Use of component ====

<source lang="php">
public static function getData($params)
{
//get article id from module parameter
$id = $params->get('article_id', 0);
if ( !$id )
{
return false;
}

$model = JModelLegacy::getInstance('Article', 'ContentModel', array('ignore_request' => true));

$app = JFactory::getApplication('site');

$model->setState('article.id', $id);
$model->setState('list.offset', 0);

// Load the parameters.
$params = $app->getParams('com_content');
$model->setState('params', $params);

$user = JFactory::getUser();

if ((!$user->authorise('core.edit.state', 'com_content')) && (!$user->authorise('core.edit', 'com_content')))
{
$model->setState('filter.published', 1);
$model->setState('filter.archived', 2);
}

$model->setState('filter.language', JLanguageMultilang::isEnabled());

return $model->getItem($id);;

</source>

=== Add javascript to the module ===

If you want to use javascript for yourmodule, here is an example. It loads the javascript file in the media/mod_yourmodule/js path and adds a script to the header of the html document.

Read more [[J3.x:Javascript_Frameworks|J3.x:Javascript Frameworks]]

==== default.php Javascript ====
<source>
JHtml::_('bootstrap.framework');

JHtml::script('mod_yourmodule/yourmodule.js', false, true, false, false, false);

$document = JFactory::getDocument();
$document->addScriptDeclaration('jQuery( document ).ready(function()
{
alert(\'I am an alert box!\');});'
);
</source>

Add this code below the line that loads the css file if you want to test it.

* We use jQuery so we have to load it '''before''' our own modulescript. Here we load the Bootstrap framework that also includes jQuery. Use JHtml::_('jquery.framework') if you only need this.
* We add our scriptfile "relative" to the media folder.
* We add the script declaration directly to the document object. It gets added to the header in the html document.

User:Over/Step by step to a Joomla Module - Data retrieval and styling

2014-09-07T08:09:55Z

Over: /* Css styling */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== Introduction ===

In this step we will extend "Your module" to retrieve data from a database table in two ways, direct access to a table and using a components methods. You have to have installed the module you created in former parts of the tutorial, before you start to follow this part.

=== Data retrieval ===

As in the previous parts you copy a skeleton file to your module folder in your Joomla path of the server. This time you copy the helper.php file to the "root" of the module.

==== helper.php ====

<source type="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' );

abstract class ModYourmoduleHelper
{
/**
* Get data from table
* @return array
*/
public static function getData($params)
{
//we will add some code here
}
}

</source>

The top of the file looks like any other of our php files. Copy your own comment lines from one of the php files you have edited in the former parts of the tutorial. Then we have a class definition with a name following a convention you as well should follow. Mod + The module name + Helper. A comment block follows describing what the following function does. We will add our code within the function ( in developer language called method ). You have to read the coding standards or have a look in any Joomla! core php file to learn more about coding and commenting conventions.

We will use an article to have a litle more dynamic data example. If you didn't create an article earlier in this tutorial series do that now. Keep it short as it's only an example. In the Module Manager you open your module and under the option tab you choose your article example. You see the title but actually the article id number is stored as parameter value.

In the first example we'll get the article text by sending sql statements to the Joomla! database API.

==== helper.php - The sql commands ====
<source type="php">

/**
* Get data from table
* @return array
*/
public static function getData($params)
{
//get article id from module parameter
$id = $params->get('article_id', 0);
if ( !$id )
{
return false;
}
//get the users authorisations
$user = JFactory::getUser();
$groups = implode(',', $user->getAuthorisedViewLevels());

$db = JFactory::getDbo();
//get a db query object
$query = $db->getQuery(true);
//select article id, title and introtext
$query->select(
array(
$db->quoteName('a.id'),
$db->quoteName('a.title'),
$db->quoteName('a.introtext'),
)
);
//from the article table
$query->from($db->quoteName('#__content', 'a'));
//id from parameter, we are conservative enough to cast the id
$query->where($db->quoteName('id') . ' = '. $db->quote( (int) $id));
// Only return if published
$query->where($db->quoteName('a.state') . ' = 1 ');
//and user is authorised to read
$query->where('a.access IN (' . $groups . ')');

//uncomment this line to see the query string
//echo $query;

$db->setQuery($query);
try
{
//get the article
$result = $db->loadObject();
}
//check error
catch (RuntimeException $e)
{
//this is a module so we skip it if there are errors
// in other cases we would show a message
//$app = JFactory::getApplication();
//$app->enqueueMessage($e->getMessage(), 'error');

return false;
}

return $result;

}

</source>

See the brief comments in the text about what we are doing here. Important security issue: use $db->quote('field_value') to avoid so called "sql-injections". Be very careful when you build sql queries. We can't describe the details to Joomla! sql queries within this tutorial. More in [http://docs.joomla.org/Accessing_the_database_using_JDatabase Accessing the database using JDatabase]

As this is a module we don't show errormessages to the user. If there are errors the page will still be ok.

Copy the code to your helper.php replacing the method ( = function ) getData.

The helper file is loaded and run from mod_yourmodule.php. Open it and add the following between defined(... and require.

==== mod_yourmodule.php - Load helper class ====

<source type="php">

// Include the helper file that provide the data
require_once __DIR__ . '/helper.php';

//the class suffix from parameter
$moduleclass_sfx = htmlspecialchars($params->get('moduleclass_sfx'));

if ( !$article = ModYourmoduleHelper::getData($params))
{
//if error or article not found skip this module
return false;
}

//uncomment this line to see the available fields
//var_dump($article);

</source>

At the same time we get the class suffix from the parameter. Explained below.
Now that you have the article data, we will change the output file to show it. Remember? /tmpl/default.php

==== default.php - Show article ====

<source type="php">

defined('_JEXEC') or die('Restricted access');
?>
<div class="yourmodule<?php echo $moduleclass_sfx ?>">

<h4><?php echo $article->title; ?></h4>

<div><?php echo $article->introtext; ?></div>

</div>
</source>

After defined(... and the php closing tab we change the html. We use embedded php code to echo the title and the introtext. We add a module specific class $moduleclass sfx to the div tag. $moduleclass sfx is the class suffix the user can add in the Module Manager -> tab Advanced. This can be used for Css styling if multiple instances of the same module are enabled. e.g. you can test to reuse your module by choosing another article. We will style them in the next step.

=== Css styling ===
Best practice on a website is to '''try''' to keep all css styling in one file. As you don't know if the users template shows your module as designed you have to include a css file. Not really for what we have above but in a tutorial we do as if.

We will not only prepare for loading css but also for images and javascript. Best practice is to store those files in subfolders of the Joomla media folder. Please don't ask why this folder was named media.

Create folder path/to/your/joomla/media/mod_yourmodule. In the folder where you unpacked the tutorial zip file you'll find a media folder. Open this and copy all three subfolders to the new folder in your web folder. It should result in something like this

<pre>
...
/logs
/media
...
/mod_yourmodule *new directory*
/css *new directory*
yourmodule.css *new file*
/images *new directory*
doc.png *new file*
yourmodule-logo.png *new file*
/js *new directory*
yourmodule.js *new file*
...
/modules
...
</pre>

Did you use your module name? You don´t have to, but it´s a good practice to use distinct names.

=== Add Css file ===

We include the module specific css file to the header of the html document.

==== default.php - Include Css file and image ====

<source>

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

JHtml::stylesheet('mod_yourmodule/yourmodule.css', false, true, false);
?>
<div class="yourmodule<?php echo $moduleclass_sfx ?>">

<div class="row text-center">
<?php echo JHtml::image('mod_yourmodule/yourmodule-logo.png', 'Yourmodule logo', '', true, false );?>
</div>

<h4><?php echo $article->title; ?></h4>

<div><?php echo $article->introtext; ?></div>

</div>

</source>

With this code added yourmodule.css will be loaded from the path media/mod_yourmodule/css/
Be aware of the missing /css/ ! This is added by Joomla. The image will be loaded from the path media/mod_yourmodule/images/.

Let's test that the css is working by adding a few lines to the yourmodule.css file. Open it with the editor and add e.g. those lines that change text color. Do we have to mention the module name?

==== yourmodule.css ====
<source>
.yourmodule h4{
color: #08c;
}
.yourmodule p {
color: #005580;
}
</source>

On your frontend page the colors should have changed and an image added. Have a look! Be aware that your browser may have cached the css.

=== Update the xml and the zip file ===

Now we have to add the new files to the xml file and create an updated installation zip file.

Add the helper.php and the special media tag to the xml file.

==== mod_yourmodule.xml - Add helper.php ====

Add helper.php to the files tag.

<source>

<files>
<filename>helper.php</filename>
<filename>mod_yourmodule.xml</filename>
<filename module="mod_yourmodule">mod_yourmodule.php</filename>
<folder>tmpl</folder>
</files>

</source>

==== mod_yourmodule.xml - Add media folder ====

Add the media tag between files and languages.

<source>

</files>
<media destination="mod_yourmodule" folder="media">
<folder>css</folder>
<folder>images</folder>
<folder>js</folder>
</media>
<languages folder="langs">

</source>

=== Create the installation file ===

Now you copy '''all''' module files from the server to the path 'somewhere'/j_module_tutorial/new_module as in the 'Installation package' part of this tutorial.
Create a new folder 'media' and copy the three folders from media/mod_yourmodule.

<pre>
.../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
/language
/en-GB
en-GB.mod_yourmodule.sys.ini
/anyother-language
anyother-language.mod_yourmodule.sys.ini
/media
/css
yourmodule.css
/images
doc.png
yourmodule-logo.png
/js
yourmodule.js
/tmpl
default.php
mod_yourmodule.php
mod_yourmodule.xml
</pre>

Create the compressed installation zip file as described in the 'Installation package' part of this tutorial.

That's it for this tutorial. Below we describe an alternative for data retrieval.

=== Use a component for data retrieval ===

Below is an alternative to using direct sql. You can use the methods provided by a component to retrieve the data. If you develop your own component, you can prepare methods for reuse, otherwise you can try to find a method in a components models to retrieve the data you want. Here we reuse the getItem method of the content component ( articles ). In this case you get all article data returned so be a little aware of momory usage. If you want to test it, you only have to replace the getData method in helper.php

==== helper.php Use of component ====

<source lang="php">
public static function getData($params)
{
//get article id from module parameter
$id = $params->get('article_id', 0);
if ( !$id )
{
return false;
}

$model = JModelLegacy::getInstance('Article', 'ContentModel', array('ignore_request' => true));

$app = JFactory::getApplication('site');

$model->setState('article.id', $id);
$model->setState('list.offset', 0);

// Load the parameters.
$params = $app->getParams('com_content');
$model->setState('params', $params);

$user = JFactory::getUser();

if ((!$user->authorise('core.edit.state', 'com_content')) && (!$user->authorise('core.edit', 'com_content')))
{
$model->setState('filter.published', 1);
$model->setState('filter.archived', 2);
}

$model->setState('filter.language', JLanguageMultilang::isEnabled());

return $model->getItem($id);;

</source>

=== Add javascript to the module ===

If you want to use javascript for yourmodule, here is an example. It loads the javascript file in the media/mod_yourmodule/js path and adds a script to the header of the html document.

Read more [[J3.x:Javascript_Frameworks|J3.x:Javascript Frameworks]]

==== default.php Javascript ====
<source>
JHtml::_('bootstrap.framework');

JHtml::script('mod_yourmodule/yourmodule.js', false, true, false, false, false);

$document = JFactory::getDocument();
$document->addScriptDeclaration('jQuery( document ).ready(function()
{
alert(\'I am an alert box!\');});'
);
</source>

Add this code below the line that loads the css file if you want to test it.

* We use jQuery so we have to load it '''before''' our own modulescript. Here we load the Bootstrap framework that also includes jQuery. Use JHtml::_('jquery.framework') if you only need this.
* We add our scriptfile "relative" to the media folder.
* We add the script declaration directly to the document object. It gets added to the header in the html document.

User:Over/Step by step to a Joomla Module - Data retrieval and styling

2014-09-07T08:01:20Z

Over: /* mod_yourmodule.php - Load helper class */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== Introduction ===

In this step we will extend "Your module" to retrieve data from a database table in two ways, direct access to a table and using a components methods. You have to have installed the module you created in former parts of the tutorial, before you start to follow this part.

=== Data retrieval ===

As in the previous parts you copy a skeleton file to your module folder in your Joomla path of the server. This time you copy the helper.php file to the "root" of the module.

==== helper.php ====

<source type="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' );

abstract class ModYourmoduleHelper
{
/**
* Get data from table
* @return array
*/
public static function getData($params)
{
//we will add some code here
}
}

</source>

The top of the file looks like any other of our php files. Copy your own comment lines from one of the php files you have edited in the former parts of the tutorial. Then we have a class definition with a name following a convention you as well should follow. Mod + The module name + Helper. A comment block follows describing what the following function does. We will add our code within the function ( in developer language called method ). You have to read the coding standards or have a look in any Joomla! core php file to learn more about coding and commenting conventions.

We will use an article to have a litle more dynamic data example. If you didn't create an article earlier in this tutorial series do that now. Keep it short as it's only an example. In the Module Manager you open your module and under the option tab you choose your article example. You see the title but actually the article id number is stored as parameter value.

In the first example we'll get the article text by sending sql statements to the Joomla! database API.

==== helper.php - The sql commands ====
<source type="php">

/**
* Get data from table
* @return array
*/
public static function getData($params)
{
//get article id from module parameter
$id = $params->get('article_id', 0);
if ( !$id )
{
return false;
}
//get the users authorisations
$user = JFactory::getUser();
$groups = implode(',', $user->getAuthorisedViewLevels());

$db = JFactory::getDbo();
//get a db query object
$query = $db->getQuery(true);
//select article id, title and introtext
$query->select(
array(
$db->quoteName('a.id'),
$db->quoteName('a.title'),
$db->quoteName('a.introtext'),
)
);
//from the article table
$query->from($db->quoteName('#__content', 'a'));
//id from parameter, we are conservative enough to cast the id
$query->where($db->quoteName('id') . ' = '. $db->quote( (int) $id));
// Only return if published
$query->where($db->quoteName('a.state') . ' = 1 ');
//and user is authorised to read
$query->where('a.access IN (' . $groups . ')');

//uncomment this line to see the query string
//echo $query;

$db->setQuery($query);
try
{
//get the article
$result = $db->loadObject();
}
//check error
catch (RuntimeException $e)
{
//this is a module so we skip it if there are errors
// in other cases we would show a message
//$app = JFactory::getApplication();
//$app->enqueueMessage($e->getMessage(), 'error');

return false;
}

return $result;

}

</source>

See the brief comments in the text about what we are doing here. Important security issue: use $db->quote('field_value') to avoid so called "sql-injections". Be very careful when you build sql queries. We can't describe the details to Joomla! sql queries within this tutorial. More in [http://docs.joomla.org/Accessing_the_database_using_JDatabase Accessing the database using JDatabase]

As this is a module we don't show errormessages to the user. If there are errors the page will still be ok.

Copy the code to your helper.php replacing the method ( = function ) getData.

The helper file is loaded and run from mod_yourmodule.php. Open it and add the following between defined(... and require.

==== mod_yourmodule.php - Load helper class ====

<source type="php">

// Include the helper file that provide the data
require_once __DIR__ . '/helper.php';

//the class suffix from parameter
$moduleclass_sfx = htmlspecialchars($params->get('moduleclass_sfx'));

if ( !$article = ModYourmoduleHelper::getData($params))
{
//if error or article not found skip this module
return false;
}

//uncomment this line to see the available fields
//var_dump($article);

</source>

At the same time we get the class suffix from the parameter. Explained below.
Now that you have the article data, we will change the output file to show it. Remember? /tmpl/default.php

==== default.php - Show article ====

<source type="php">

defined('_JEXEC') or die('Restricted access');
?>
<div class="yourmodule<?php echo $moduleclass_sfx ?>">

<h4><?php echo $article->title; ?></h4>

<div><?php echo $article->introtext; ?></div>

</div>
</source>

After defined(... and the php closing tab we change the html. We use embedded php code to echo the title and the introtext. We add a module specific class $moduleclass sfx to the div tag. $moduleclass sfx is the class suffix the user can add in the Module Manager -> tab Advanced. This can be used for Css styling if multiple instances of the same module are enabled. e.g. you can test to reuse your module by choosing another article. We will style them in the next step.

=== Css styling ===
Best practice on a website is to '''try''' to keep all css styling in one file. As you don't know if the users template shows your module as designed you have to include a css file. Not really for what we have above but in a tutorial we do as if.

We will not only prepare for loading css but also for images and javascript. Best practice is to store those files in subfolders of the Joomla media folder. Please don't ask why this folder was named media.

Create folder path/to/your/joomla/media/mod_yourmodule. In the folder where you unpacked the tutorial zip file you'll find a media folder. Open this and copy all three subfolders to the new folder in your web folder. It should result in something like this

<pre>
...
/logs
/media
...
/mod_yourmodule *new directory*
/css *new directory*
yourmodule.css *new file*
/images *new directory*
doc.png *new file*
yourmodule-logo.png *new file*
/js *new directory*
yourmodule.js *new file*
...
/modules
...
</pre>

Did you use your module name?

=== Add Css file ===

We include the module specific css file to the header of the html document.

==== default.php - Include Css file and image ====

<source>

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

JHtml::stylesheet('mod_yourmodule/yourmodule.css', false, true, false);
?>
<div class="yourmodule<?php echo $moduleclass_sfx ?>">

<div class="row text-center">
<?php echo JHtml::image('mod_yourmodule/yourmodule-logo.png', 'Yourmodule logo', '', true, false );?>
</div>

<h4><?php echo $article->title; ?></h4>

<div><?php echo $article->introtext; ?></div>

</div>

</source>

With this code added yourmodule.css will be loaded from the path media/mod_yourmodule/css/
Be aware of the missing /css/ ! This is added by Joomla. The image will be loaded from the path media/mod_yourmodule/images/.

Let's test that the css is working by adding a few lines to the yourmodule.css file. Open it with the editor and add e.g. those lines that change text color. Do we have to mention the module name?

==== yourmodule.css ====
<source>
.yourmodule h4{
color: #08c;
}
.yourmodule p {
color: #005580;
}
</source>

On your frontend page the colors should have changed and an image added. Have a look! Be aware that your browser may have cached the css.

=== Update the xml and the zip file ===

Now we have to add the new files to the xml file and create an updated installation zip file.

Add the helper.php and the special media tag to the xml file.

==== mod_yourmodule.xml - Add helper.php ====

Add helper.php to the files tag.

<source>

<files>
<filename>helper.php</filename>
<filename>mod_yourmodule.xml</filename>
<filename module="mod_yourmodule">mod_yourmodule.php</filename>
<folder>tmpl</folder>
</files>

</source>

==== mod_yourmodule.xml - Add media folder ====

Add the media tag between files and languages.

<source>

</files>
<media destination="mod_yourmodule" folder="media">
<folder>css</folder>
<folder>images</folder>
<folder>js</folder>
</media>
<languages folder="langs">

</source>

=== Create the installation file ===

Now you copy '''all''' module files from the server to the path 'somewhere'/j_module_tutorial/new_module as in the 'Installation package' part of this tutorial.
Create a new folder 'media' and copy the three folders from media/mod_yourmodule.

<pre>
.../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
/language
/en-GB
en-GB.mod_yourmodule.sys.ini
/anyother-language
anyother-language.mod_yourmodule.sys.ini
/media
/css
yourmodule.css
/images
doc.png
yourmodule-logo.png
/js
yourmodule.js
/tmpl
default.php
mod_yourmodule.php
mod_yourmodule.xml
</pre>

Create the compressed installation zip file as described in the 'Installation package' part of this tutorial.

That's it for this tutorial. Below we describe an alternative for data retrieval.

=== Use a component for data retrieval ===

Below is an alternative to using direct sql. You can use the methods provided by a component to retrieve the data. If you develop your own component, you can prepare methods for reuse, otherwise you can try to find a method in a components models to retrieve the data you want. Here we reuse the getItem method of the content component ( articles ). In this case you get all article data returned so be a little aware of momory usage. If you want to test it, you only have to replace the getData method in helper.php

==== helper.php Use of component ====

<source lang="php">
public static function getData($params)
{
//get article id from module parameter
$id = $params->get('article_id', 0);
if ( !$id )
{
return false;
}

$model = JModelLegacy::getInstance('Article', 'ContentModel', array('ignore_request' => true));

$app = JFactory::getApplication('site');

$model->setState('article.id', $id);
$model->setState('list.offset', 0);

// Load the parameters.
$params = $app->getParams('com_content');
$model->setState('params', $params);

$user = JFactory::getUser();

if ((!$user->authorise('core.edit.state', 'com_content')) && (!$user->authorise('core.edit', 'com_content')))
{
$model->setState('filter.published', 1);
$model->setState('filter.archived', 2);
}

$model->setState('filter.language', JLanguageMultilang::isEnabled());

return $model->getItem($id);;

</source>

=== Add javascript to the module ===

If you want to use javascript for yourmodule, here is an example. It loads the javascript file in the media/mod_yourmodule/js path and adds a script to the header of the html document.

Read more [[J3.x:Javascript_Frameworks|J3.x:Javascript Frameworks]]

==== default.php Javascript ====
<source>
JHtml::_('bootstrap.framework');

JHtml::script('mod_yourmodule/yourmodule.js', false, true, false, false, false);

$document = JFactory::getDocument();
$document->addScriptDeclaration('jQuery( document ).ready(function()
{
alert(\'I am an alert box!\');});'
);
</source>

Add this code below the line that loads the css file if you want to test it.

* We use jQuery so we have to load it '''before''' our own modulescript. Here we load the Bootstrap framework that also includes jQuery. Use JHtml::_('jquery.framework') if you only need this.
* We add our scriptfile "relative" to the media folder.
* We add the script declaration directly to the document object. It gets added to the header in the html document.

User:Over/Step by step to a Joomla Module - Overrides

2014-09-06T04:57:26Z

Over: /* Overriding */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== Introduction ===
In this step we'll use your custom module to show you how you can use the powerful Joomla! methods to override ( = change ) the output. The same possibilities are valid for all modules and components that follows the Joomla! best practice.

=== Your site template directory ===

As you probably know, your template is found under the templates/ folder in your Joomla! directory. The folders important for our overrides are:

<pre>
...
/templates
...
/mytemplate
/css
/mod_yourmodule
yourmodule.css
...
/html
...
/com_mycomponent
/view1
default.php
/view2
default.php
...
/layouts
/joomla
/content
/info_block
/mod_yourmodule
default.php
alternative.php
...
/images
/mod_yourmodule
yourmodule-logo.png
...
/js
/mod_yourmodule
yourmodule.js
...
...
</pre>

The illustration above shows the paths and some of the files in your templates folder.
If we add files in those directories, they will be used instead of the extensions original files.
You can use the Template Manager to easily create overrides in the html path. [[J3.x:How_to_use_the_Template_Manager|J3.x:How to use the Template Manager]]

Be aware of that if you use a template including overrides, you have to find a way to protect your custom overrides when the template is updated. e.g. if you use the Beez3 template, you can create a copy of this template. See the Template Manager.

We can also override css, images and javascripts that are loaded with the JHtml functions and 'relative' to the media/ folder. We'll show this with the custom module you have created in this tutorial.

=== Overriding ===

Use the Template Manager or your file manager to copy the default.php from the /tmpl folder in your module to yourtemplate/html/mod_yourmodule/ as shown above. Open the copy with your editor and make some visual changes. Maybe you want to replace the Bootstrap classes if your template is not loading the Bootstrap Css. If you now refresh the browser page you'll see the changes.

You can create a second override for your module with another name. e.g. alternative.php and change some visible content. Now you click New in the Module Manager and choose your module. Edit the new copy of the module and choose the second override in the Advanced tab / Alternative Layout. Enable and have a look what happend.

You can do the same with components. As shown above, you have to add one folder per component view, where you add the output file. The name is not always default.php.

Copy the yourmodule.css file from media/mod_yourmodule/css to yourtemplate/css/mod_yourmodule/. Open this file and change css classes e.g. text to another color. Reload the page in the browser. Be aware of the browser cache. It can be, that you have to clear it to get the changed css loaded.

Copy an image to yourtemplate/images/mod_yourmodule/ and rename it to the same name as used in the default.php. Reload the page and you'll see your image.

The same possibility is valid for javascript. If they are loaded 'relative' to the media/ path you can copy them to yourtemplate/js/mod_yourmodule/ and change them.

As you remember we added two options to the module settings, load_css and load_js. A administrator/user may want to load css and/or javascript in other ways. If you use those parameters, the administrator can turn off the loading of your modules css and/or javacript without overriding the default.php. This is more important for components as css and javascript normaly not is loaded in overridable code.

=== Examples - optional exclusion of css and javascript===

==== default.php Css parameter ====
<source>

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

if ($params->get('load_css', 1))
{
JHtml::stylesheet('mod_yourmodule/yourmodule.css', false, true, false);
}
?>

</source>

==== default.php Javascript parameter ====
<source>

if ($params->get('load_js', 1))
{
JHtml::_('bootstrap.framework');

JHtml::script('mod_yourmodule/yourmodule.js', false, true, false, false, false);

$document = JFactory::getDocument();
$document->addScriptDeclaration('jQuery( document ).ready(function()
{
alert(\'I am an alert box!\');});'
);

}

</source>

=== The html/layouts path ===

A new possibility to Joomla! output is the reuse of parts of a view ( JLayout ). An example is the use of the same 'layout' in many of the different article views. JLayout files use the layout paths. In the Joomla! root you can find a /layouts folder that include the core JLayout files. Have a look at the available ones. Third party components usually use an own folder in their backend path.

To override those reused 'layouts' you copy them to the corresponding path in your templates directory and make the changes. They will be automaticly loaded instead of the original one.

It's not likely that you can reuse a JLayout file in a module, but it is possible.

=== Language string overrides ===

We will not describe this type of overrides here. We only want to remind you of the possibility to change language strings in extensions that are not your own. Do not change the original files.

Go to {{rarr|Extensions,Language Manager,Overrides}} to create overrides that change texts.

User:Over/Step by step to a Joomla Module - Overrides

2014-09-06T04:50:53Z

Over: /* Overriding */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== Introduction ===
In this step we'll use your custom module to show you how you can use the powerful Joomla! methods to override ( = change ) the output. The same possibilities are valid for all modules and components that follows the Joomla! best practice.

=== Your site template directory ===

As you probably know, your template is found under the templates/ folder in your Joomla! directory. The folders important for our overrides are:

<pre>
...
/templates
...
/mytemplate
/css
/mod_yourmodule
yourmodule.css
...
/html
...
/com_mycomponent
/view1
default.php
/view2
default.php
...
/layouts
/joomla
/content
/info_block
/mod_yourmodule
default.php
alternative.php
...
/images
/mod_yourmodule
yourmodule-logo.png
...
/js
/mod_yourmodule
yourmodule.js
...
...
</pre>

The illustration above shows the paths and some of the files in your templates folder.
If we add files in those directories, they will be used instead of the extensions original files.
You can use the Template Manager to easily create overrides in the html path. [[J3.x:How_to_use_the_Template_Manager|J3.x:How to use the Template Manager]]

Be aware of that if you use a template including overrides, you have to find a way to protect your custom overrides when the template is updated. e.g. if you use the Beez3 template, you can create a copy of this template. See the Template Manager.

We can also override css, images and javascripts that are loaded with the JHtml functions and 'relative' to the media/ folder. We'll show this with the custom module you have created in this tutorial.

=== Overriding ===

Use the Template Manager or your file manager to copy the default.php from the /tmpl folder in your module to yourtemplate/html/mod_yourmodule/ as shown above. Open the copy with your editor and make some visual changes. Maybe you want to replace the Bootstrap classes if your template is not loading the Bootstrap Css. If you now refresh the browser page you'll see the changes.

You can create a second override for your module with another name. e.g. alternative.php and change some visible content. Now you click New in the Module Manager and choose your module. Edit the new copy of the module and choose the second override in the Advanced tab / Alternative Layout. Enable and have a look what happend.

You can do the same with components. As shown above, you have to add one folder per component view, where you add the output file. The name is not always default.php.

Copy the yourmodule.css file from media/mod_yourmodule/css to yourtemplate/css/mod_yourmodule/. Open this file and change css classes e.g. text to another color. Reload the page in the browser. Be aware of the browser cache. It can be, that you have to clear it to get the changed css loaded.

Copy an image to yourtemplate/images/mod_yourmodule/ and rename it to the same name as used in the default.php. Reload the page and you'll see your image.

The same possibility is valid for javascript. If they are loaded 'relative' to the media/ path you can copy them to yourtemplate/js/mod_yourmodule/ and change them.

As you remember we added two options to the module settings, load_css and load_js. A administrator/user may want to load css and/or javascript in other ways. If you use those parameters, the administrator can turn off the loading of your modules css and/or javacript without overriding the default.php. This is more important for components as css and javascript normaly not is loaded in overridable code.

Examples - optional exclusion of the css and javascript:
==== default.php Css parameter ====
<source>

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

if ($params->get('load_css', 1))
{
JHtml::stylesheet('mod_yourmodule/yourmodule.css', false, true, false);
}
?>

</source>

==== default.php Javascript parameter ====
<source>

if ($params->get('load_js', 1))
{
JHtml::_('bootstrap.framework');

JHtml::script('mod_yourmodule/yourmodule.js', false, true, false, false, false);

$document = JFactory::getDocument();
$document->addScriptDeclaration('jQuery( document ).ready(function()
{
alert(\'I am an alert box!\');});'
);

}

</source>

=== The html/layouts path ===

A new possibility to Joomla! output is the reuse of parts of a view ( JLayout ). An example is the use of the same 'layout' in many of the different article views. JLayout files use the layout paths. In the Joomla! root you can find a /layouts folder that include the core JLayout files. Have a look at the available ones. Third party components usually use an own folder in their backend path.

To override those reused 'layouts' you copy them to the corresponding path in your templates directory and make the changes. They will be automaticly loaded instead of the original one.

It's not likely that you can reuse a JLayout file in a module, but it is possible.

=== Language string overrides ===

We will not describe this type of overrides here. We only want to remind you of the possibility to change language strings in extensions that are not your own. Do not change the original files.

Go to {{rarr|Extensions,Language Manager,Overrides}} to create overrides that change texts.

User:Over/Step by step to a Joomla Module - Overrides

2014-09-06T04:47:58Z

Over: /* default.php Css parameter */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== Introduction ===
In this step we'll use your custom module to show you how you can use the powerful Joomla! methods to override ( = change ) the output. The same possibilities are valid for all modules and components that follows the Joomla! best practice.

=== Your site template directory ===

As you probably know, your template is found under the templates/ folder in your Joomla! directory. The folders important for our overrides are:

<pre>
...
/templates
...
/mytemplate
/css
/mod_yourmodule
yourmodule.css
...
/html
...
/com_mycomponent
/view1
default.php
/view2
default.php
...
/layouts
/joomla
/content
/info_block
/mod_yourmodule
default.php
alternative.php
...
/images
/mod_yourmodule
yourmodule-logo.png
...
/js
/mod_yourmodule
yourmodule.js
...
...
</pre>

The illustration above shows the paths and some of the files in your templates folder.
If we add files in those directories, they will be used instead of the extensions original files.
You can use the Template Manager to easily create overrides in the html path. [[J3.x:How_to_use_the_Template_Manager|J3.x:How to use the Template Manager]]

Be aware of that if you use a template including overrides, you have to find a way to protect your custom overrides when the template is updated. e.g. if you use the Beez3 template, you can create a copy of this template. See the Template Manager.

We can also override css, images and javascripts that are loaded with the JHtml functions and 'relative' to the media/ folder. We'll show this with the custom module you have created in this tutorial.

=== Overriding ===

Use the Template Manager or your file manager to copy the default.php from the /tmpl folder in your module to yourtemplate/html/mod_yourmodule/ as shown above. Open the copy with your editor and make some visual changes. Maybe you want to replace the Bootstrap classes if your template is not loading the Bootstrap Css. If you now refresh the browser page you'll see the changes.

You can create a second override for your module with another name. e.g. alternative.php and change some visible content. Now you click New in the Module Manager and choose your module. Edit the new copy of the module and choose the second override in the Advanced tab / Alternative Layout. Enable and have a look what happend.

You can do the same with components. As shown above, you have to add one folder per component view, where you add the output file. The name is not always default.php.

Copy the yourmodule.css file from media/mod_yourmodule/css to yourtemplate/css/mod_yourmodule/. Open this file and change css classes e.g. text to another color. Reload the page in the browser. Be aware of the browser cache. It can be, that you have to clear it to get the changed css loaded.

Copy an image to yourtemplate/images/mod_yourmodule/ and rename it to the same name as used in the default.php. Reload the page and you'll see your image.

The same possibility is valid for javascript. If they are loaded 'relative' to the media/ path you can copy them to yourtemplate/js/mod_yourmodule/ and change them.

As you remember we added two options to the module settings, load_css and load_js. A administrator/user may want to load css and/or javascript in other ways. If you use those parameters, the administrator can turn off the loading of your modules css and/or javacript without overriding the default.php. This is more important for components as css and javascript normaly not is loaded in overridable code.

Example - optional exclusion of the css:
==== default.php Css parameter ====

<source>

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

if ($params->get('load_css', 1))
{
JHtml::stylesheet('mod_yourmodule/yourmodule.css', false, true, false);
}
?>

</source>

==== default.php Javascript parameter ====
<source>

if ($params->get('load_js', 1))
{
JHtml::_('bootstrap.framework');

JHtml::script('mod_yourmodule/yourmodule.js', false, true, false, false, false);

$document = JFactory::getDocument();
$document->addScriptDeclaration('jQuery( document ).ready(function()
{
alert(\'I am an alert box!\');});'
);

}

</source>

=== The html/layouts path ===

A new possibility to Joomla! output is the reuse of parts of a view ( JLayout ). An example is the use of the same 'layout' in many of the different article views. JLayout files use the layout paths. In the Joomla! root you can find a /layouts folder that include the core JLayout files. Have a look at the available ones. Third party components usually use an own folder in their backend path.

To override those reused 'layouts' you copy them to the corresponding path in your templates directory and make the changes. They will be automaticly loaded instead of the original one.

It's not likely that you can reuse a JLayout file in a module, but it is possible.

=== Language string overrides ===

We will not describe this type of overrides here. We only want to remind you of the possibility to change language strings in extensions that are not your own. Do not change the original files.

Go to {{rarr|Extensions,Language Manager,Overrides}} to create overrides that change texts.

User:Over/Step by step to a Joomla Module - Installation package

2014-09-06T04:27:59Z

Over: /* Alternative language files handling */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== 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 =====
<source>

; 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"

</source>

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!'''

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

There is no good reference available at the time of writing. Please change this link if a better is found. [[Specification_of_language_files|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.

<code>
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."
</code>

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 ====

<source>
<description>MOD_YOURMODULE_XML_DESCRIPTION</description>
</source>

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 ====

<source>

<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>

</source>

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 [http://docs.joomla.org/Module 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 ====

<source>

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"
</source>

=== 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 ====

<source>

<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>

</source>

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.

<div class="large-12 panel radius" style="background-color:#fff; border:1px solid #aaa; margin:1em 0;">
'''''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.
</div>

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 ):

<pre>

.../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
/language
/en-GB
en-GB.mod_yourmodule.sys.ini
/anyother-language
anyother-language.mod_yourmodule.sys.ini
/tmpl
default.php
mod_yourmodule.php
mod_yourmodule.xml

</pre>

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 ====

<source>

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."

</source>

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/language-codes.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 {{rarr|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 {{rarr|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:
<pre>

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

</pre>

==== 1. Easiest way ====

Add a folder tag to the files area in the xml file.
<pre>
<folder>language</folder>
</pre>
The folder will be stored in the extensions folder and no files in the core language folder.
ALL files are copied, not only the ones for installed languages.

==== 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).

<source>

<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>

</source>

The files are saved to the core language folder in the traditional way.
Only the files for installed languages are copied.

User:Over/Step by step to a Joomla Module - Installation package

2014-09-06T04:20:34Z

Over: /* Create the compressed installation file */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== 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 =====
<source>

; 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"

</source>

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!'''

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

There is no good reference available at the time of writing. Please change this link if a better is found. [[Specification_of_language_files|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.

<code>
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."
</code>

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 ====

<source>
<description>MOD_YOURMODULE_XML_DESCRIPTION</description>
</source>

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 ====

<source>

<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>

</source>

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 [http://docs.joomla.org/Module 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 ====

<source>

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"
</source>

=== 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 ====

<source>

<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>

</source>

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.

<div class="large-12 panel radius" style="background-color:#fff; border:1px solid #aaa; margin:1em 0;">
'''''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.
</div>

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 ):

<pre>

.../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
/language
/en-GB
en-GB.mod_yourmodule.sys.ini
/anyother-language
anyother-language.mod_yourmodule.sys.ini
/tmpl
default.php
mod_yourmodule.php
mod_yourmodule.xml

</pre>

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 ====

<source>

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."

</source>

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/language-codes.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 {{rarr|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 {{rarr|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
** /en-GB
*** en-GB.mod_yourmodule.ini
*** en-GB.mod_yourmodule.sys.ini
** /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.
ALL files are copied, not only the ones for installed languages.

==== 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).

<source>

<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>

</source>

The files are saved to the core language folder in the traditional way.
Only the files for installed languages are copied.

User:Over/Step by step to a Joomla Module - Basic

2014-09-06T04:04:51Z

Over: /* Install and enable the module */

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.

=== 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 ===

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.

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 <config> 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]]

User:Over/Step by step to a Joomla Module - Overrides

2014-09-06T03:41:40Z

Over: /* The html/layouts path */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== Introduction ===
In this step we'll use your custom module to show you how you can use the powerful Joomla! methods to override ( = change ) the output. The same possibilities are valid for all modules and components that follows the Joomla! best practice.

=== Your site template directory ===

As you probably know, your template is found under the templates/ folder in your Joomla! directory. The folders important for our overrides are:

<pre>
...
/templates
...
/mytemplate
/css
/mod_yourmodule
yourmodule.css
...
/html
...
/com_mycomponent
/view1
default.php
/view2
default.php
...
/layouts
/joomla
/content
/info_block
/mod_yourmodule
default.php
alternative.php
...
/images
/mod_yourmodule
yourmodule-logo.png
...
/js
/mod_yourmodule
yourmodule.js
...
...
</pre>

The illustration above shows the paths and some of the files in your templates folder.
If we add files in those directories, they will be used instead of the extensions original files.
You can use the Template Manager to easily create overrides in the html path. [[J3.x:How_to_use_the_Template_Manager|J3.x:How to use the Template Manager]]

Be aware of that if you use a template including overrides, you have to find a way to protect your custom overrides when the template is updated. e.g. if you use the Beez3 template, you can create a copy of this template. See the Template Manager.

We can also override css, images and javascripts that are loaded with the JHtml functions and 'relative' to the media/ folder. We'll show this with the custom module you have created in this tutorial.

=== Overriding ===

Use the Template Manager or your file manager to copy the default.php from the /tmpl folder in your module to yourtemplate/html/mod_yourmodule/ as shown above. Open the copy with your editor and make some visual changes. Maybe you want to replace the Bootstrap classes if your template is not loading the Bootstrap Css. If you now refresh the browser page you'll see the changes.

You can create a second override for your module with another name. e.g. alternative.php and change some visible content. Now you click New in the Module Manager and choose your module. Edit the new copy of the module and choose the second override in the Advanced tab / Alternative Layout. Enable and have a look what happend.

You can do the same with components. As shown above, you have to add one folder per component view, where you add the output file. The name is not always default.php.

Copy the yourmodule.css file from media/mod_yourmodule/css to yourtemplate/css/mod_yourmodule/. Open this file and change css classes e.g. text to another color. Reload the page in the browser. Be aware of the browser cache. It can be, that you have to clear it to get the changed css loaded.

Copy an image to yourtemplate/images/mod_yourmodule/ and rename it to the same name as used in the default.php. Reload the page and you'll see your image.

The same possibility is valid for javascript. If they are loaded 'relative' to the media/ path you can copy them to yourtemplate/js/mod_yourmodule/ and change them.

As you remember we added two options to the module settings, load_css and load_js. A administrator/user may want to load css and/or javascript in other ways. If you use those parameters, the administrator can turn off the loading of your modules css and/or javacript without overriding the default.php. This is more important for components as css and javascript normaly not is loaded in overridable code.

Example - optional exclusion of the css:
==== default.php Css parameter ====

<source>
defined('_JEXEC') or die('Restricted access');

if ($params->get('load_css', 1)) {
JHtml::stylesheet('mod_yourmodule/yourmodule.css', false, true, false);
}
?></source>

=== The html/layouts path ===

A new possibility to Joomla! output is the reuse of parts of a view ( JLayout ). An example is the use of the same 'layout' in many of the different article views. JLayout files use the layout paths. In the Joomla! root you can find a /layouts folder that include the core JLayout files. Have a look at the available ones. Third party components usually use an own folder in their backend path.

To override those reused 'layouts' you copy them to the corresponding path in your templates directory and make the changes. They will be automaticly loaded instead of the original one.

It's not likely that you can reuse a JLayout file in a module, but it is possible.

=== Language string overrides ===

We will not describe this type of overrides here. We only want to remind you of the possibility to change language strings in extensions that are not your own. Do not change the original files.

Go to {{rarr|Extensions,Language Manager,Overrides}} to create overrides that change texts.

User:Over/Step by step to a Joomla Module - Overrides

2014-09-06T03:15:05Z

Over: /* Overriding */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== Introduction ===
In this step we'll use your custom module to show you how you can use the powerful Joomla! methods to override ( = change ) the output. The same possibilities are valid for all modules and components that follows the Joomla! best practice.

=== Your site template directory ===

As you probably know, your template is found under the templates/ folder in your Joomla! directory. The folders important for our overrides are:

<pre>
...
/templates
...
/mytemplate
/css
/mod_yourmodule
yourmodule.css
...
/html
...
/com_mycomponent
/view1
default.php
/view2
default.php
...
/layouts
/joomla
/content
/info_block
/mod_yourmodule
default.php
alternative.php
...
/images
/mod_yourmodule
yourmodule-logo.png
...
/js
/mod_yourmodule
yourmodule.js
...
...
</pre>

The illustration above shows the paths and some of the files in your templates folder.
If we add files in those directories, they will be used instead of the extensions original files.
You can use the Template Manager to easily create overrides in the html path. [[J3.x:How_to_use_the_Template_Manager|J3.x:How to use the Template Manager]]

Be aware of that if you use a template including overrides, you have to find a way to protect your custom overrides when the template is updated. e.g. if you use the Beez3 template, you can create a copy of this template. See the Template Manager.

We can also override css, images and javascripts that are loaded with the JHtml functions and 'relative' to the media/ folder. We'll show this with the custom module you have created in this tutorial.

=== Overriding ===

Use the Template Manager or your file manager to copy the default.php from the /tmpl folder in your module to yourtemplate/html/mod_yourmodule/ as shown above. Open the copy with your editor and make some visual changes. Maybe you want to replace the Bootstrap classes if your template is not loading the Bootstrap Css. If you now refresh the browser page you'll see the changes.

You can create a second override for your module with another name. e.g. alternative.php and change some visible content. Now you click New in the Module Manager and choose your module. Edit the new copy of the module and choose the second override in the Advanced tab / Alternative Layout. Enable and have a look what happend.

You can do the same with components. As shown above, you have to add one folder per component view, where you add the output file. The name is not always default.php.

Copy the yourmodule.css file from media/mod_yourmodule/css to yourtemplate/css/mod_yourmodule/. Open this file and change css classes e.g. text to another color. Reload the page in the browser. Be aware of the browser cache. It can be, that you have to clear it to get the changed css loaded.

Copy an image to yourtemplate/images/mod_yourmodule/ and rename it to the same name as used in the default.php. Reload the page and you'll see your image.

The same possibility is valid for javascript. If they are loaded 'relative' to the media/ path you can copy them to yourtemplate/js/mod_yourmodule/ and change them.

As you remember we added two options to the module settings, load_css and load_js. A administrator/user may want to load css and/or javascript in other ways. If you use those parameters, the administrator can turn off the loading of your modules css and/or javacript without overriding the default.php. This is more important for components as css and javascript normaly not is loaded in overridable code.

Example - optional exclusion of the css:
==== default.php Css parameter ====

<source>
defined('_JEXEC') or die('Restricted access');

if ($params->get('load_css', 1)) {
JHtml::stylesheet('mod_yourmodule/yourmodule.css', false, true, false);
}
?></source>

=== The html/layouts path ===

A new possibility to Joomla! output is the reuse of parts of a view ( JLayout ). An example is the use of the same 'layout' in many of the different article views. JLayout files use the layout paths. In the Joomla! root you can find a /layouts folder that include the core JLayout files. Have a look at the available ones. Third party components usually use an own folder in their backend path.

To override those reused 'layouts' you copy them to the corresponding path in your templates directory and make the changes. They will be automaticly loaded instead of the original one.

It's not likely that you can reuse a JLayout file in a module, but it is possible.

User:Over/Step by step to a Joomla Module - Installation package

2014-09-06T02:27:12Z

Over: /* en-GB.mod_yourmodule.ini */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== 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 =====
<source>

; 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"

</source>

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!'''

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

There is no good reference available at the time of writing. Please change this link if a better is found. [[Specification_of_language_files|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.

<code>
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."
</code>

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 ====

<source>
<description>MOD_YOURMODULE_XML_DESCRIPTION</description>
</source>

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 ====

<source>

<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>

</source>

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 [http://docs.joomla.org/Module 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 ====

<source>

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"
</source>

=== 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 ====

<source>

<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>

</source>

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.

<div class="large-12 panel radius" style="background-color:#fff; border:1px solid #aaa; margin:1em 0;">
'''''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.
</div>

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
** /langs
*** en-GB.mod_yourmodule.ini
*** en-GB.mod_yourmodule.sys.ini
*** anyother-language.mod_yourmodule.in
*** anyother-language.mod_yourmodule.sys.ini
** /language
*** /en-GB
**** en-GB.mod_yourmodule.sys.ini
*** /anyother-language
**** anyother-language.mod_yourmodule.sys.ini
** /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 ====

<source>

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."

</source>

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/language-codes.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 {{rarr|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 {{rarr|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
** /en-GB
*** en-GB.mod_yourmodule.ini
*** en-GB.mod_yourmodule.sys.ini
** /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.
ALL files are copied, not only the ones for installed languages.

==== 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).

<source>

<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>

</source>

The files are saved to the core language folder in the traditional way.
Only the files for installed languages are copied.

User:Over/Step by step to a Joomla Module - Installation package

2014-09-06T02:15:09Z

Over: /* mod_yourmodule.sys.ini - Installation message */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== 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 =====
<source>

; 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"

</source>

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!'''

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

There is no good reference available at the time of writing. Please change this link if a better is found. [[Specification_of_language_files|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.

<code>
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."
</code>

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 ====

<source>
<description>MOD_YOURMODULE_XML_DESCRIPTION</description>
</source>

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 ====

<source>

<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>

</source>

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 [http://docs.joomla.org/Module 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 ====

<source>

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"
</source>

=== 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 ====

<source>

<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>

</source>

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.

<div class="large-12 panel radius" style="background-color:#fff; border:1px solid #aaa; margin:1em 0;">
'''''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.
</div>

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
** /langs
*** en-GB.mod_yourmodule.ini
*** en-GB.mod_yourmodule.sys.ini
*** anyother-language.mod_yourmodule.in
*** anyother-language.mod_yourmodule.sys.ini
** /language
*** /en-GB
**** en-GB.mod_yourmodule.sys.ini
*** /anyother-language
**** anyother-language.mod_yourmodule.sys.ini
** /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 ====

<source>

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."

</source>

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/language-codes.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 {{rarr|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 {{rarr|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
** /en-GB
*** en-GB.mod_yourmodule.ini
*** en-GB.mod_yourmodule.sys.ini
** /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.
ALL files are copied, not only the ones for installed languages.

==== 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).

<source>

<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>

</source>

The files are saved to the core language folder in the traditional way.
Only the files for installed languages are copied.

User:Over/Step by step to a Joomla Module - Installation package

2014-09-06T02:03:31Z

Over: /* Create the compressed installation file */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== 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 =====
<source>

; 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"

</source>

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!'''

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

There is no good reference available at the time of writing. Please change this link if a better is found. [[Specification_of_language_files|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.

<code>
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."
</code>

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 ====

<source>
<description>MOD_YOURMODULE_XML_DESCRIPTION</description>
</source>

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 ====

<source>

<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>

</source>

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 [http://docs.joomla.org/Module 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 ====

<source>

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"
</source>

=== 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 ====

<source>

<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>

</source>

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.

<div class="large-12 panel radius" style="background-color:#fff; border:1px solid #aaa; margin:1em 0;">
'''''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.
</div>

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
** /langs
*** en-GB.mod_yourmodule.ini
*** en-GB.mod_yourmodule.sys.ini
*** anyother-language.mod_yourmodule.in
*** anyother-language.mod_yourmodule.sys.ini
** /language
*** /en-GB
**** en-GB.mod_yourmodule.sys.ini
*** /anyother-language
**** anyother-language.mod_yourmodule.sys.ini
** /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 ====

<source>

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."

</source>

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 {{rarr|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 {{rarr|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
** /en-GB
*** en-GB.mod_yourmodule.ini
*** en-GB.mod_yourmodule.sys.ini
** /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.
ALL files are copied, not only the ones for installed languages.

==== 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).

<source>

<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>

</source>

The files are saved to the core language folder in the traditional way.
Only the files for installed languages are copied.

User:Over/Step by step to a Joomla Module - Installation package

2014-09-06T02:00:20Z

Over: /* Alternative language files handling */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== 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 =====
<source>

; 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"

</source>

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!'''

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

There is no good reference available at the time of writing. Please change this link if a better is found. [[Specification_of_language_files|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.

<code>
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."
</code>

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 ====

<source>
<description>MOD_YOURMODULE_XML_DESCRIPTION</description>
</source>

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 ====

<source>

<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>

</source>

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 [http://docs.joomla.org/Module 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 ====

<source>

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"
</source>

=== 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 ====

<source>

<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>

</source>

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.

<div class="large-12 panel radius" style="background-color:#fff; border:1px solid #aaa; margin:1em 0;">
'''''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.
</div>

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 ====

<source>

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."

</source>

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 {{rarr|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 {{rarr|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
** /en-GB
*** en-GB.mod_yourmodule.ini
*** en-GB.mod_yourmodule.sys.ini
** /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.
ALL files are copied, not only the ones for installed languages.

==== 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).

<source>

<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>

</source>

The files are saved to the core language folder in the traditional way.
Only the files for installed languages are copied.

User:Over/Step by step to a Joomla Module - Installation package

2014-09-06T01:51:25Z

Over: /* 2. Traditional way */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== 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 =====
<source>

; 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"

</source>

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!'''

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

There is no good reference available at the time of writing. Please change this link if a better is found. [[Specification_of_language_files|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.

<code>
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."
</code>

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 ====

<source>
<description>MOD_YOURMODULE_XML_DESCRIPTION</description>
</source>

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 ====

<source>

<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>

</source>

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 [http://docs.joomla.org/Module 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 ====

<source>

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"
</source>

=== 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 ====

<source>

<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>

</source>

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.

<div class="large-12 panel radius" style="background-color:#fff; border:1px solid #aaa; margin:1em 0;">
'''''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.
</div>

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 ====

<source>

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."

</source>

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 {{rarr|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 {{rarr|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.
ALL files are copied, not only the ones for installed languages.

==== 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).

<source>

<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>

</source>

The files are saved to the core language folder in the traditional way.
Only the files for installed languages are copied.

User:Over/Step by step to a Joomla Module - Installation package

2014-09-06T01:48:43Z

Over: /* 1. Easiest way */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== 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 =====
<source>

; 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"

</source>

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!'''

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

There is no good reference available at the time of writing. Please change this link if a better is found. [[Specification_of_language_files|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.

<code>
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."
</code>

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 ====

<source>
<description>MOD_YOURMODULE_XML_DESCRIPTION</description>
</source>

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 ====

<source>

<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>

</source>

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 [http://docs.joomla.org/Module 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 ====

<source>

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"
</source>

=== 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 ====

<source>

<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>

</source>

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.

<div class="large-12 panel radius" style="background-color:#fff; border:1px solid #aaa; margin:1em 0;">
'''''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.
</div>

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 ====

<source>

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."

</source>

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 {{rarr|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 {{rarr|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.
ALL files are copied, not only the ones for installed languages.

==== 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).

<source>

<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>

</source>

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

User:Over/Step by step to a Joomla Module - Overrides

2014-09-05T12:38:53Z

Over: /* The html/layouts path */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== Introduction ===
In this step we'll use your custom module to show you how you can use the powerful Joomla! methods to override ( = change ) the output. The same possibilities are valid for all modules and components that follows the Joomla! best practice.

=== Your site template directory ===

As you probably know, your template is found under the templates/ folder in your Joomla! directory. The folders important for our overrides are:

<pre>
...
/templates
...
/mytemplate
/css
/mod_yourmodule
yourmodule.css
...
/html
...
/com_mycomponent
/view1
default.php
/view2
default.php
...
/layouts
/joomla
/content
/info_block
/mod_yourmodule
default.php
alternative.php
...
/images
/mod_yourmodule
yourmodule-logo.png
...
/js
/mod_yourmodule
yourmodule.js
...
...
</pre>

The illustration above shows the paths and some of the files in your templates folder.
If we add files in those directories, they will be used instead of the extensions original files.
You can use the Template Manager to easily create overrides in the html path. [[J3.x:How_to_use_the_Template_Manager|J3.x:How to use the Template Manager]]

Be aware of that if you use a template including overrides, you have to find a way to protect your custom overrides when the template is updated. e.g. if you use the Beez3 template, you can create a copy of this template. See the Template Manager.

We can also override css, images and javascripts that are loaded with the JHtml functions and 'relative' to the media/ folder. We'll show this with the custom module you have created in this tutorial.

=== Overriding ===

Use the Template Manager or your file manager to copy the default.php from the /tmpl folder in your module to yourtemplate/html/mod_yourmodule/ as shown above. Open the copy with your editor and make some visual changes. Maybe you want to replace the Bootstrap classes if your temlate is not loading the Bootstrap Css. If you now refresh the browser page you'll see the changes.

You can do the same with components. As shown above, you have to add one folder per component view, where you add the output file. The name is not always default.php.

Copy the yourmodule.css file from media/mod_yourmodule/css to yourtemplate/css/mod_yourmodule/. Open this file and change css classes e.g. text to another color. Reload the page in the browser. Be aware of the browser cache. It can be, that you have to clear it to get the changed css loaded.

Copy an image to yourtemplate/images/mod_yourmodule/ and rename it to the same name as used in the default.php. Reload the page and you'll see your image.

The same possibility is valid for javascript. If they are loaded 'relative' to the media/ path you can copy them to yourtemplate/js/mod_yourmodule/ and change them.

As you remember we added two options to the module settings, load_css and load_js. A administrator/user may want to load css and/or javascript in other ways. If you use those parameters, the administrator can turn off the loading of your modules css and/or javacript without overriding the default.php. This is more important for components as css and javascript normaly not is loaded in overridable code.

Example - optional exclusion of the css:
==== default.php Css parameter ====

<source>
defined('_JEXEC') or die('Restricted access');

if ($params->get('load_css', 1)) {
JHtml::stylesheet('mod_yourmodule/yourmodule.css', false, true, false);
}
?></source>

=== The html/layouts path ===

A new possibility to Joomla! output is the reuse of parts of a view ( JLayout ). An example is the use of the same 'layout' in many of the different article views. JLayout files use the layout paths. In the Joomla! root you can find a /layouts folder that include the core JLayout files. Have a look at the available ones. Third party components usually use an own folder in their backend path.

To override those reused 'layouts' you copy them to the corresponding path in your templates directory and make the changes. They will be automaticly loaded instead of the original one.

It's not likely that you can reuse a JLayout file in a module, but it is possible.

User:Over/Step by step to a Joomla Module - Installation package

2014-09-05T11:54:41Z

Over: /* 2. Traditional way */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== 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 =====
<source>

; 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"

</source>

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!'''

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

There is no good reference available at the time of writing. Please change this link if a better is found. [[Specification_of_language_files|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.

<code>
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."
</code>

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 ====

<source>
<description>MOD_YOURMODULE_XML_DESCRIPTION</description>
</source>

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 ====

<source>

<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>

</source>

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 [http://docs.joomla.org/Module 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 ====

<source>

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"
</source>

=== 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 ====

<source>

<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>

</source>

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.

<div class="large-12 panel radius" style="background-color:#fff; border:1px solid #aaa; margin:1em 0;">
'''''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.
</div>

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 ====

<source>

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."

</source>

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 {{rarr|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 {{rarr|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).

<source>

<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>

</source>

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

User:Over/Step by step to a Joomla Module - Installation package

2014-09-05T11:11:22Z

Over: /* Alternative language files handling */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== 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 =====
<source>

; 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"

</source>

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!'''

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

There is no good reference available at the time of writing. Please change this link if a better is found. [[Specification_of_language_files|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.

<code>
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."
</code>

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 ====

<source>
<description>MOD_YOURMODULE_XML_DESCRIPTION</description>
</source>

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 ====

<source>

<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>

</source>

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 [http://docs.joomla.org/Module 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 ====

<source>

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"
</source>

=== 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 ====

<source>

<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>

</source>

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.

<div class="large-12 panel radius" style="background-color:#fff; border:1px solid #aaa; margin:1em 0;">
'''''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.
</div>

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 ====

<source>

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."

</source>

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 {{rarr|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 {{rarr|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).

<source>

<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>

</source>

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

User:Over/Step by step to a Joomla Module - Installation package

2014-09-05T11:02:49Z

Over: /* Create the compressed installation file */

{{User:Over/Step_by_step_to_a_Joomla_Module/nav}}

=== 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 =====
<source>

; 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"

</source>

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!'''

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

There is no good reference available at the time of writing. Please change this link if a better is found. [[Specification_of_language_files|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.

<code>
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."
</code>

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 ====

<source>
<description>MOD_YOURMODULE_XML_DESCRIPTION</description>
</source>

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 ====

<source>

<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>

</source>

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 [http://docs.joomla.org/Module 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 ====

<source>

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"
</source>

=== 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 ====

<source>

<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>

</source>

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.

<div class="large-12 panel radius" style="background-color:#fff; border:1px solid #aaa; margin:1em 0;">
'''''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.
</div>

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 ====

<source>

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."

</source>

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 {{rarr|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 {{rarr|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 of the folder name!

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).

<source>

<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>

</source>

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