Joomla! Documentation - User contributions [en]

Calendar form field type

2022-12-15T01:51:32Z

Garkell: Minor tweek to the format

<noinclude><languages /></noinclude>
<translate>
The '''calendar''' form field type provides a text box for entry of a date. An icon next to the text box provides a link to a pop-up calendar, which can also be used to enter the date value. If the field has a saved value this is shown in the text box. Otherwise the default value, if any, is displayed.</translate>

[[Image:DatePicker1.calendar-<translate>
en</translate>.png|right]]
<translate>
* '''type''' (mandatory) must be ''calendar''.</translate>
<translate>
* '''name''' (mandatory) is the unique name of the field.</translate>
<translate>
* '''label''' (mandatory) (translatable) is the descriptive title of the field.</translate>
<translate>
* '''default''' (optional) is the default date. This must be given in the same format as specified by the format argument. You can put "NOW" to have current date or time information in the given format. You can also used any [[https://docs.joomla.org/How_to_use_JDate#Arguments JDate arguments]] ('now +1 month', 'now +2 months +7 days +12 hours', ...)</translate>
<translate>
* '''description''' (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the text box.</translate>
<translate>
* '''readonly''' (optional) is whether the text box is read-only (''true'' or ''false''). If the text box is read-only, the date cannot be changed, but can be selected and copied. No calendar icon will be shown.</translate>
<translate>
* '''disabled''' (optional) is whether the text box is disabled (''true'' or ''false''). If the text box is disabled, the date cannot be changed, selected or copied.</translate>
<translate>
* '''class''' (optional) is a CSS class name for the HTML form field. It is recommended to use the "Bootstrap2 Relatives sizing" (see code examples below).</translate>
<translate>
* '''format''' (optional) is the date format to be used. This is in the format used by PHP to specify date string formats (see below). If no format argument is given, '%Y-%m-%d' is assumed (giving dates like '2017-05-15'). If <code>showtime</code> is true then you will need to include some time fields, for example, '%Y-%m-%d %H:%i:%s'.</translate>
<translate>
* '''filter''' (optional) is time zone to be used. There are two main values: ''server_utc'' and ''user_utc''. The first one is server time zone and the later is user time zone as configured in global configuration and user information respectively. There is also a value of ''none'' which must be used if the server time zone is set to something other than UTC and ''showtime'' is false.</translate>
<translate>

* '''translateformat''' (optional): If set to true, the calendar will use the <code>DATE_FORMAT_CALENDAR_DATE</code> language key (if <code>showtime</code> is true) or <code>DATE_FORMAT_CALENDAR_DATETIME</code> (if <code>showtime</code> is false) to determine the format. The <code>format</code> attribute is ignored. If false, the <code>format</code> attribute is used (same behaviour as prior to 3.7.0) but note that the <code>format</code> string must include time fields for the time to be recorded. Defaults to false.</translate>
<translate>

* '''showtime''' (optional): If set to true and <code>translateformat</code> is true, the language key <code>DATE_FORMAT_CALENDAR_DATETIME</code> is used, otherwise <code>DATE_FORMAT_CALENDAR_DATE</code>. (starting with 3.7.0). Defaults to false.</translate>

<translate>

* '''timeformat''' (optional): can be set to 12 or 24 (starting with 3.7.0). If set to 12, an additional selection is available to the user to choose between AM and PM. This attribute does not affect how the date/time is saved. Defaults to 24.</translate>

<translate>

* '''singleheader''' (optional): if set to false, the year and the month selection will be set on two separates lines, with independent selection (starting with 3.7.0). Defaults to false.</translate>

<translate>

* '''todaybutton''' (optional): if set to true, a button is added at the bottom of the date picker to select the date of the current day (starting with 3.7.0). Defaults to true.</translate>

<translate>

* '''weeknumbers''' (optional): if set to true, a column is added at the left of the date picker to display the number of the week in the current year (starting with 3.7.0). Defaults to true.</translate>

<translate>

* '''filltable''' (optional): if set to true, dates of the previous and next month are added at the top and bottom of the current month to fill the grid (starting with 3.7.0). Defaults to true.</translate>

<translate>

* '''minyear''' (optional): set a signed integer for a number of years (-10, -2, 0, 7, 12, ...) to define the relative lower limit for the year selection. The user cannot select a year before this limit (starting with 3.7.0). If zero, which is the default, there is no limit.</translate>

<translate>

* '''maxyear''' (optional): set a signed integer for a number of years (-10, -2, 0, 7, 12, ...) to define the relative upper limit for the year selection. The user cannot select a year after this limit (starting with 3.7.0). If zero, which is the default, there is no limit.</translate>

<translate>
Example for a light DatePicker XML field definition:</translate>
<source lang="xml"><field name="<translate>
mycalendar</translate>" type="calendar" default="<translate>
2017-05-15</translate>" label="<translate>
Select a date</translate>" description=""
class="input-small" required="true" filter="user_utc"
showtime="false" todaybutton="false" filltable="false" translateformat="true" /></source>
[[Image:DatePicker1.calendar-<translate>
en</translate>.png|center]]

<translate>

Example for an advanced DatePicker XML field definition:</translate>
<source lang="xml"><field name="<translate>
mycalendar</translate>" type="calendar" default="<translate>
2017-05-15</translate>" label="<translate>
Select a date</translate>" description=""
class="input-medium" required="true" filter="user_utc" format="<translate>
%Y-%m-%d %H:%i:%s</translate>"
singleheader="true" showtime="true" timeformat="12" todaybutton="true" weeknumbers="true"
filltable="true" minyear="-3" maxyear="5" /></source>
[[Image:DatePicker2.calendar-<translate>
en</translate>.png|center]]

<translate>
The format attribute specifies the format that the date string will be saved in. It is also the format that manually entered dates need to be enterered in; except that the punctuation character is ignored. The coding scheme used to specify date formats is a custom one defined for the javascript library used in the datepicker, full details of which can be found for example on [https://github.com/joomla/joomla-cms/blob/staging/media/system/js/calendar-uncompressed.js#L1741-L1774 Joomla's Github].</translate>
<translate>
The following are some of the most frequently used date string codes:</translate>

{| class="wikitable"
|-
!<translate>
Character</translate>
!<translate>
Description</translate>
!<translate>
Example</translate>
|-
|d
|<translate>
Day of the month, 2 digits with leading zeros</translate>
|<translate>
01 to 31</translate>
|-
|a
|<translate>
A textual representation of a day, three letters</translate>
|<translate>
Mon through Sun</translate>
|-
|e
|<translate>
Day of the month without leading zeros</translate>
|<translate>
1 to 31</translate>
|-
|A
|<translate>
A full textual representation of the day of the week</translate>
|<translate>
Monday through Sunday</translate>
|-
|w
|<translate>
Numeric representation of the day of the week</translate>
|<translate>
0 (for Sunday) through 6 (for Saturday)</translate>
|-
|j
|<translate>
The day of the year (starting from 0)</translate>
|<translate>
001 through 366</translate>
|-
|B
|<translate>
A full textual representation of a month</translate>
|<translate>
January through December</translate>
|-
|m
|<translate>
Numeric representation of a month, with leading zeros</translate>
|<translate>
01 through 12</translate>
|-
|b
|<translate>
A short textual representation of a month, three letters</translate>
|<translate>
Jan through Dec</translate>
|-
|Y
|<translate>
A full numeric representation of a year, 4 digits</translate>
|<translate>
1999 or 2003</translate>
|-
|y
|<translate>
A two-digit representation of a year</translate>
|<translate>
99 or 03</translate>
|-
|P
|<translate>
Lowercase Ante Meridiem or Post Meridiem</translate>
|<translate>
am or pm</translate>
|-
|p
|<translate>
Uppercase Ante Meridiem or Post Meridiem</translate>
|<translate>
AM or PM</translate>
|}

<translate>
Note: The format in which dates are stored in the params.ini file is that specified by the format argument. Since there can be language-dependent elements to this format (for example, the '%A' specifier), you need to be careful not to use such elements if there is a possibility that the front-end and back-end languages may be different.</translate>

<translate>
Note: The calendar form field type does not support non-Gregorian calendars. If you need to support non-Gregorian calendars then you will need to create a custom form field type to support your calendar.</translate>

<translate>=== Standard associated filters === </translate>
<translate>
* '''user_utc''' - Calculates the specified value to the time of Greenwich, according to the user time zone settings.</translate>

<translate>=== See also === </translate>
<translate>
* [[S:MyLanguage/Standard form field types|List of standard form field types]]</translate>

<noinclude>
<translate>

[[Category:Standard form field types]]
</translate>
</noinclude>

Calendar form field type

2022-12-15T01:50:05Z

Garkell: Minor tweek to the format

<noinclude><languages /></noinclude>
<translate>
The '''calendar''' form field type provides a text box for entry of a date. An icon next to the text box provides a link to a pop-up calendar, which can also be used to enter the date value. If the field has a saved value this is shown in the text box. Otherwise the default value, if any, is displayed.</translate>

[[Image:DatePicker1.calendar-<translate>
en</translate>.png|right]]
<translate>
* '''type''' (mandatory) must be ''calendar''.</translate>
<translate>
* '''name''' (mandatory) is the unique name of the field.</translate>
<translate>
* '''label''' (mandatory) (translatable) is the descriptive title of the field.</translate>
<translate>
* '''default''' (optional) is the default date. This must be given in the same format as specified by the format argument. You can put "NOW" to have current date or time information in the given format. You can also used any [[https://docs.joomla.org/How_to_use_JDate#Arguments JDate arguments]] ('now +1 month', 'now +2 months +7 days +12 hours', ...)</translate>
<translate>
* '''description''' (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the text box.</translate>
<translate>
* '''readonly''' (optional) is whether the text box is read-only (''true'' or ''false''). If the text box is read-only, the date cannot be changed, but can be selected and copied. No calendar icon will be shown.</translate>
<translate>
* '''disabled''' (optional) is whether the text box is disabled (''true'' or ''false''). If the text box is disabled, the date cannot be changed, selected or copied.</translate>
<translate>
* '''class''' (optional) is a CSS class name for the HTML form field. It is recommended to use the "Bootstrap2 Relatives sizing" (see code examples below).</translate>
<translate>
* '''format''' (optional) is the date format to be used. This is in the format used by PHP to specify date string formats (see below). If no format argument is given, '%Y-%m-%d' is assumed (giving dates like '2017-05-15'). If <code>showtime</code> is true then you will need to include some time fields, for example, '%Y-%m-%d %H:%i:%s'.</translate>
<translate>
* '''filter''' (optional) is time zone to be used. There are two main values: ''server_utc'' and ''user_utc''. The first one is server time zone and the later is user time zone as configured in global configuration and user information respectively. There is also a value of ''none'' which must be used if the server time zone is set to something other than UTC and ''showtime'' is false.</translate>
<translate>

* '''translateformat''' (optional): If set to true, the calendar will use the <code>DATE_FORMAT_CALENDAR_DATE</code> language key (if <code>showtime</code> is true) or <code>DATE_FORMAT_CALENDAR_DATETIME</code> (if <code>showtime</code> is false) to determine the format. The <code>format</code> attribute is ignored. If false, the <code>format</code> attribute is used (same behaviour as prior to 3.7.0) but note that the <code>format</code> string must include time fields for the time to be recorded. Defaults to false.</translate>
<translate>

* '''showtime''' (optional): If set to true and <code>translateformat</code> is true, the language key <code>DATE_FORMAT_CALENDAR_DATETIME</code> is used, otherwise <code>DATE_FORMAT_CALENDAR_DATE</code>. (starting with 3.7.0). Defaults to false.</translate>

<translate>

* '''timeformat''' (optional): can be set to 12 or 24 (starting with 3.7.0). If set to 12, an additional selection is available to the user to choose between AM and PM. This attribute does not affect how the date/time is saved. Defaults to 24.</translate>

<translate>

* '''singleheader''' (optional): if set to false, the year and the month selection will be set on two separates lines, with independent selection (starting with 3.7.0). Defaults to false.</translate>

<translate>

* '''todaybutton''' (optional): if set to true, a button is added at the bottom of the date picker to select the date of the current day (starting with 3.7.0). Defaults to true.</translate>

<translate>

* '''weeknumbers''' (optional): if set to true, a column is added at the left of the date picker to display the number of the week in the current year (starting with 3.7.0). Defaults to true.</translate>

<translate>

* '''filltable''' (optional): if set to true, dates of the previous and next month are added at the top and bottom of the current month to fill the grid (starting with 3.7.0). Defaults to true.</translate>

<translate>

* '''minyear''' (optional): set a signed integer for a number of years (-10, -2, 0, 7, 12, ...) to define the relative lower limit for the year selection. The user cannot select a year before this limit (starting with 3.7.0). If zero, which is the default, there is no limit.</translate>

<translate>

* '''maxyear''' (optional): set a signed integer for a number of years (-10, -2, 0, 7, 12, ...) to define the relative upper limit for the year selection. The user cannot select a year after this limit (starting with 3.7.0). If zero, which is the default, there is no limit.</translate>

<translate>
Example for a light DatePicker XML field definition:</translate>
<source lang="xml"><field name="<translate>
mycalendar</translate>" type="calendar" default="<translate>
2017-05-15</translate>" label="<translate>
Select a date</translate>" description=""
class="input-small" required="true" filter="user_utc"
showtime="false" todaybutton="false" filltable="false" translateformat="true" /></source>
[[Image:DatePicker1.calendar-<translate>
en</translate>.png|center]]

<translate>

Example for an advanced DatePicker XML field definition:</translate>
<source lang="xml"><field name="<translate>
mycalendar</translate>" type="calendar" default="<translate>
2017-05-15</translate>" label="<translate>
Select a date</translate>" description=""
class="input-medium" required="true" filter="user_utc" format="<translate>
%Y-%m-%d %H:%M:%S</translate>"
singleheader="true" showtime="true" timeformat="12" todaybutton="true" weeknumbers="true"
filltable="true" minyear="-3" maxyear="5" /></source>
[[Image:DatePicker2.calendar-<translate>
en</translate>.png|center]]

<translate>
The format attribute specifies the format that the date string will be saved in. It is also the format that manually entered dates need to be enterered in; except that the punctuation character is ignored. The coding scheme used to specify date formats is a custom one defined for the javascript library used in the datepicker, full details of which can be found for example on [https://github.com/joomla/joomla-cms/blob/staging/media/system/js/calendar-uncompressed.js#L1741-L1774 Joomla's Github].</translate>
<translate>
The following are some of the most frequently used date string codes:</translate>

{| class="wikitable"
|-
!<translate>
Character</translate>
!<translate>
Description</translate>
!<translate>
Example</translate>
|-
|d
|<translate>
Day of the month, 2 digits with leading zeros</translate>
|<translate>
01 to 31</translate>
|-
|a
|<translate>
A textual representation of a day, three letters</translate>
|<translate>
Mon through Sun</translate>
|-
|e
|<translate>
Day of the month without leading zeros</translate>
|<translate>
1 to 31</translate>
|-
|A
|<translate>
A full textual representation of the day of the week</translate>
|<translate>
Monday through Sunday</translate>
|-
|w
|<translate>
Numeric representation of the day of the week</translate>
|<translate>
0 (for Sunday) through 6 (for Saturday)</translate>
|-
|j
|<translate>
The day of the year (starting from 0)</translate>
|<translate>
001 through 366</translate>
|-
|B
|<translate>
A full textual representation of a month</translate>
|<translate>
January through December</translate>
|-
|m
|<translate>
Numeric representation of a month, with leading zeros</translate>
|<translate>
01 through 12</translate>
|-
|b
|<translate>
A short textual representation of a month, three letters</translate>
|<translate>
Jan through Dec</translate>
|-
|Y
|<translate>
A full numeric representation of a year, 4 digits</translate>
|<translate>
1999 or 2003</translate>
|-
|y
|<translate>
A two-digit representation of a year</translate>
|<translate>
99 or 03</translate>
|-
|P
|<translate>
Lowercase Ante Meridiem or Post Meridiem</translate>
|<translate>
am or pm</translate>
|-
|p
|<translate>
Uppercase Ante Meridiem or Post Meridiem</translate>
|<translate>
AM or PM</translate>
|}

<translate>
Note: The format in which dates are stored in the params.ini file is that specified by the format argument. Since there can be language-dependent elements to this format (for example, the '%A' specifier), you need to be careful not to use such elements if there is a possibility that the front-end and back-end languages may be different.</translate>

<translate>
Note: The calendar form field type does not support non-Gregorian calendars. If you need to support non-Gregorian calendars then you will need to create a custom form field type to support your calendar.</translate>

<translate>=== Standard associated filters === </translate>
<translate>
* '''user_utc''' - Calculates the specified value to the time of Greenwich, according to the user time zone settings.</translate>

<translate>=== See also === </translate>
<translate>
* [[S:MyLanguage/Standard form field types|List of standard form field types]]</translate>

<noinclude>
<translate>

[[Category:Standard form field types]]
</translate>
</noinclude>

User:Garkell

2021-02-13T23:29:18Z

Garkell:

<noinclude><languages /></noinclude>
{{Top portal heading|color=white-bkgd|icon=joomla|icon-color=#5091cd|size=5x|text-color=#333|title=<translate> Joomla 4 Custom FormFields</translate>}}
<translate> This will help with creating your own custom formfield for your component ready for Joomla 4.</translate>

== An Example Custom Field Type == 

<translate>
Suppose you're working on your component named ''com_phonebook'' and you want to define a field that contains cities. Create the file <code>administrator/components/com_phonebook/src/Field/CityField.php</code> and write something similar to the following:</translate>

<source lang="php"><?php

namespace yourname\Component\Phonebook\Administrator\Field;

// Check to ensure this file is included in Joomla!
defined('_JEXEC') or die('Restricted access');

use \Joomla\CMS\Factory;
use \Joomla\CMS\Form\FormField;
use \yourname\Component\Phonebook\Administrator\Helper\PhonebookHelper;

class CityField extends FormField
{
protected $type = 'City';

// getLabel() left out

public function getInput() {
return '<select id="'.$this->id.'" name="'.$this->name.'">'.
'<option value="1" >New York</option>'.
'<option value="2" >Chicago</option>'.
'<option value="3" >San Francisco</option>'.
'</select>';
}
}
</source>

__NOTOC__
<noinclude>
[[Category:JDOC Projects{{#translation:}}]]
[[Category:Joomla!_4.x{{#translation:}}]]
</noinclude>
__NOEDITSECTION__

User:Garkell

2021-02-13T23:28:01Z

Garkell: Initial creation - just learning

<noinclude><languages /></noinclude>
{{Top portal heading|color=white-bkgd|icon=joomla|icon-color=#5091cd|size=5x|text-color=#333|title=<translate> Joomla 4 Custom FormFields</translate>}}
<translate> This will help with creating your own custom formfield for your component ready for Joomla 4.</translate>

== An Example Custom Field Type == 

<translate>
Suppose you're working on your component named ''com_phonebook'' and you want to define a field that contains cities. Create the file <code>administrator/components/com_phonebook/src/Field/CityField.php</code> and write something similar to the following:</translate>

<source lang="php"><?php

namespace yourname\Component\Phonebook\Administrator\Field;

// Check to ensure this file is included in Joomla!
defined('_JEXEC') or die('Restricted access');

use \Joomla\CMS\Factory;
use \Joomla\CMS\Form\FormField;
use \yourname\Component\Phonebook\Administrator\Helper\PhonebookHelper;

class CityField extends FormField {

protected $type = 'City';

// getLabel() left out

public function getInput() {
return '<select id="'.$this->id.'" name="'.$this->name.'">'.
'<option value="1" >New York</option>'.
'<option value="2" >Chicago</option>'.
'<option value="3" >San Francisco</option>'.
'</select>';
}
}
</source>

__NOTOC__
<noinclude>
[[Category:JDOC Projects{{#translation:}}]]
[[Category:Joomla!_4.x{{#translation:}}]]
</noinclude>
__NOEDITSECTION__

J4.x:Web Assets

2020-12-22T00:11:09Z

Garkell: readability

<noinclude><languages /></noinclude>
<translate>
== Concept == 
</translate>
<translate> In the frontend world many assets are related. For example our keepalive script depends on the core.js file for options management. In Joomla there never was an easy way to specify this, you just had to include multiple files. Joomla 4 changes this with the concept of web assets.</translate>

<translate>
== Definition == 
</translate>
<translate> Related assets are defined in a JSON file such as [https://github.com/joomla/joomla-cms/blob/7b72c565b610e02c1b01f8958d622879631fa6a2/build/media_source/system/joomla.asset.json#L14-L21 system/joomla.asset.json#L14-L21] </translate>

<translate> This has a structure of having a schema definition (for validation), name, version, license and then one or more asset definitions. Assets are comprised of a list of js files and css files related to the assets and any dependencies. The dependencies section is just a list of asset names that are required for the asset to function. Example:</translate>

<source lang="json">
{
"$schema": "https://developer.joomla.org/schemas/json-schema/web_assets.json",
"name": "com_example",
"version": "4.0.0",
"description": "Joomla CMS",
"license": "GPL-2.0+",
"assets": [
{
"name": "bar",
"type": "style",
"uri": "com_example/bar.css"
},
{
"name": "bar",
"type": "script",
"uri": "com_example/bar.js"
},
{
"name": "beer",
"type": "style",
"uri": "com_example/beer.css",
"dependencies": [
"bar"
],
},
{
"name": "beer",
"type": "script",
"dependencies": [
"core",
"bar"
],
"uri": "com_example/beer.js",
"attributes": {
"defer": true,
"data-foo": "bar"
}
}
]
}
</source>

The <source lang="json" inline>$schema</source> attribute is a schema definition file that allows you to validate your file using JSON Schema. Read [https://json-schema.org/understanding-json-schema/index.html the official website] for more information on json schema validation works.

'''Note:''' Having joomla.asset.json for your extension or template are recommend but not required to WebAssset to work (see next section).

'''Note:''' It is not recommended to add an inline asset to a json file, prefer to use a file.

== Explaining asset stages ==

Each asset has 2 stages: registered and used.

'''Registered''' is where an asset is loaded into '''WebAssetRegistry'''. That means '''WebAssetManager''' knows about the existence of these assets, but will not attach them to a document while rendering.
All assets loaded from joomla.asset.json is at '''registered''' stage.

'''Used''' is where an asset is enabled via "$wa->useAsset()" (->useScript(), ->useStyle(), ->registerAndUseX() etc). That means '''WebAssetManager''' will attach these assets and their dependencies to a document while rendering.

An asset cannot be used if it was not registered before, this will cause an unknown asset exception.

== Register an asset ==

All known assets loaded and then stored in '''WebAssetRegistry''' (to enable/disable an asset item you have to use '''WebAssetManager''', see next section).

<translate> Joomla! will look for next assets definition automatically at runtime (in following order):</translate>
<pre>
media/vendor/joomla.asset.json (on first access to WebAssetRegistry)
media/system/joomla.asset.json
media/legacy/joomla.asset.json
media/{com_active_component}/joomla.asset.json (on dispatch the application)
templates/{active_template}/joomla.asset.json
</pre>

And load them to registry of known assets.

<translate> '''Note:''' Each following assets definition will override asset items from previous assets definition, by item name.</translate>

<translate> You can register your own assets definition via '''WebAssetRegistry''':</translate>

<source lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();
$wr = $wa->getRegistry();
$wr->addRegistryFile('relative/path/to/your/joomla.asset.json');
</source>

<translate> To add a custom asset item at runtime:</translate>
<source lang="php">
$wr->add('script', new Joomla\CMS\WebAsset\WebAssetItem('foobar', 'com_foobar/file.js', ['type' => 'script']));
</source>

Or more simply, using '''WebAssetManager''':
<source lang="php">
$wa->registerScript('foobar', 'com_foobar/file.js');
</source>

The new asset item '''foobar''' will be added to the registry of know assets, but will not be attached to a document until your code (a layout, template etc) will request it.

<translate> To check whether an asset exists:</translate>
<source lang="php">
if ($wa->assetExists('script', 'foobar'))
{
var_dump('Script "foobar" exists!');
}
</source>

<translate>

== Enabling an asset == 
</translate>
<translate> All asset management in the current Document handled by '''WebAssetManager''', which is accessible with '''$doc->getWebAssetManager();'''</translate>
<translate> By using AssetManager you can enable or disable needed asset easily in Joomla! through a standard methods.</translate>

<translate> To enable an asset in the page use the useAsset function, for example:</translate>

<source lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();
$wa->useScript('keepalive');

// Or multiple
$wa->useScript('keepalive')
->useScript('fields.validate')
->useStyle('foobar')
->useScript('foobar');

// Add new asset item with dependency and use it
$wa->registerAndUseScript('bar', 'com_foobar/bar.js', [], [], ['core', 'foobar']);
</source>

<translate> '''WebAssetManager''' will look to '''WebAssetRegistry''' whether the requested asset exists, and will enable it for current Document instance. Otherwise it will throw an UnknownAssetException.</translate>

<translate> To disable an asset in the page use the disableAsset function. The example below will disable the jquery-noconflict asset from being loaded.</translate>

<source lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();
$wa->disableScript('jquery-noconflict');
</source>

<translate> '''Note:''' If there are any dependencies to the disabled asset, then this asset will be re-enabled automatically, no matter what.</translate>

<translate> To check whether asset enabled, and the asset state:</translate>
<source lang="php">
// Checking whether an asset are active (enabled manually or automatically as dependency)
if ($wa->isAssetActive('script', 'foobar'))
{
var_dump('Script "foobar" are active!');
}

// Checking state
switch($wa->getAssetState('script', 'foobar')){
case Joomla\CMS\WebAsset\WebAssetManager::ASSET_STATE_ACTIVE:
var_dump('Active! Was enabled manually');
break;
case Joomla\CMS\WebAsset\WebAssetManager::ASSET_STATE_DEPENDENCY:
var_dump('Active! Was enabled automatically while resolving dependencies');
break;
default:
var_dump('not active!');
}
</source>

<translate>

== Overriding an asset == 


Overriding may be useful when you need to redefine the URI of asset item or its dependencies.


As already was noted, each of the following assets definition from joomla.asset.json will override asset items from previous assets definitions, by item name.


That means if you provide joomla.asset.json which contain already loaded asset items, they will be replaced with your items.


Another way to override in the code is to register an item with the same name.


Example, we have "foobar" script, that load com_example/foobar.js library, and we want to use CDN for this exact library:


How it defined in the system initially:


<source lang="json">
...
{
"name": "foobar",
"type": "script",
"uri": "com_example/foobar.js",
"dependencies": ["core"]
}
...
</source>


To override the URI we define the asset item with "foobar" name in our joomla.asset.json:


<source lang="json">
...
{
"name": "foobar",
"type": "script",
"uri": "http://foobar.cdn.blabla/foobar.js",
"dependencies": ["core"]
}
...
</source>


Or, register new asset item with AssetManager:
<source lang="php">
$wa->registerScript('foobar', 'http://fobar.cdn.blabla/foobar.js', [], [], ['core']);
</source>

== Working with a styles == 


AssetManager allow to manage Stylesheet files. Stylesheet asset item have a type "style".


Example json defination of item in joomla.asset.json:
<source lang="json">
...
{
"name": "foobar",
"type": "style",
"uri": "com_example/foobar.css"
}
...
</source>

=== Methods to work with styles === 
AssetManager offers the following methods to work with style files:
<source lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();


// Attach foobar to the document
$wa->useStyle('foobar');


// Disable foobar from being attached
$wa->disableStyle('foobar');


// Register custom item without json defination
$wa->registerStyle('bar', 'com_example/bar.css', [], ['data-foo' => 'some attribute'], ['some.dependency']);
// And use it later
$wa->useStyle('bar');


// Register and attach a custom item in one run
$wa->registerAndUseStyle('bar', 'com_example/bar.css', [], ['data-foo' => 'some attribute'], ['some.dependency']);
</source>

=== Add inline style === 


Additionaly to style files, WebAssetManager allows you to add an inline style, and maintain their relation to the file asset.
Inline styles may be placed directly before the dependency, after the dependency, or as usual after all styles.


Inline asset may have a name as well as other assets (but not required), the name can be used to retrieve the asset item from a registry, or as a dependency to another inline asset. If the name is not specified then a generated name based on a content hash will be used.


<source lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();


// Add an inline content as usual, will be rendered in flow after all assets
$wa->addInlineStyle('content of inline1');


// Add an inline content that will be placed after "foobar" asset
$wa->addInlineStyle('content of inline2', ['position' => 'after'], ['data-foo' => 'bar'], ['foobar']);


// Add an inline content that will be placed before "foobar" asset
$wa->addInlineStyle('content of inline3', ['position' => 'before'], [], ['foobar']);


// Named inline asset
$wa->addInlineStyle('content of inline4', ['name' => 'my.inline.asset']);
</source>


'''Note:''' "foobar" asset should exist in the asset registry, otherwise you will get an unsatisfied dependency exception.


Example above will produce:
<source lang="html5">
...
<style>content of inline3</style>
<link rel="stylesheet" href="foobar.css" />
<style data-foo="bar">content of inline2</style>
...
...
<style>content of inline1</style>
<style>content of inline4</style>
...
</source>


If inline asset has multiple dependencies, then will be used last one for positioning. Example:
<source lang="php">
$wa->addInlineStyle('content of inline1', ['position' => 'before'], [], ['foo', 'bar']);
$wa->addInlineStyle('content of inline2', ['position' => 'after'], [], ['foo', 'bar']);
</source>
Will produce:
<source lang="html5">
...
<link rel="stylesheet" href="foo.css" />
<style>content of inline1</style>
<link rel="stylesheet" href="bar.css" />
<style>content of inline2</style>
...
</source>


'''Note:''' Named inline assets may be a dependency to another inline asset, however it is not recommended to use an inline asset as dependency to non-inline asset. This will work, but this behavior may change in the future. Prefer to use "position" instead.

== Working with a scripts == 


AssetManager allow to manage Script files. Script asset item have a type "script".


Example json defination of item in joomla.asset.json:
<source lang="json">
...
{
"name": "foobar",
"type": "script",
"uri": "com_example/foobar.js",
"dependencies": ["core"]
}
...
</source>

=== Methods to work with scripts === 
AssetManager offer next methods to work with script files:
<source lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();


// Attach foobar to the document
$wa->useScript('foobar');


// Disable foobar from being attached
$wa->disableScript('foobar');


// Register custom item without json defination
$wa->registerScript('bar', 'com_example/bar.js', [], ['defer' => true], ['core']);
// And use it later
$wa->useScript('bar');


// Register and attach a custom item in one run
$wa->registerAndUseScript('bar','com_example/bar.js', [], ['defer' => true], ['core']);
</source>

=== Add inline script === 


Addittionaly to script files WebAssetManager allow to add an inline script, and maintain their relation to the file asset.
Inline script may be placed directly before the dependency, after the dependency, or as usual after all scripts.


Inline asset may have a name as well as other assets (but not required), the name can be used to retrive the asset item form a registry, or as dependecy to another inline asset. If name not specified then will be used generated name based on a content hash.


<source lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();


// Add an inline content as usual, will be rendered in flow after all assets
$wa->addInlineScript('content of inline1');


// Add an inline content that will be placed after "foobar" asset
$wa->addInlineScript('content of inline2', ['position' => 'after'], ['data-foo' => 'bar'], ['foobar']);


// Add an inline content that will be placed before "foobar" asset
$wa->addInlineScript('content of inline3', ['position' => 'before'], [], ['foobar']);


// Named inline asset
$wa->addInlineScript('content of inline4', ['name' => 'my.inline.asset']);


// Specify script type
$wa->addInlineScript('content of inline5', [], ['type' => 'module']);
</source>


'''Note:''' "foobar" asset should exist in the asset registry, otherwise you will get an unsatisfied dependency exception.


Example above will produce:
<source lang="html5">
...
<script>content of inline3</script>
<script src="foobar.js"></script>
<script data-foo="bar">content of inline2</script>
...
...
<script>content of inline1</script>
<script>content of inline4</script>
<script type="module">content of inline5</script>
...
</source>


If inline asset have a multiple dependencies, then will be used last one for positioning. Example:
<source lang="php">
$wa->addInlineScript('content of inline1', ['position' => 'before'], [], ['foo', 'bar']);
$wa->addInlineScript('content of inline2', ['position' => 'after'], [], ['foo', 'bar']);
</source>
Will produce:
<source lang="html5">
...
<script src="foo.js"></script>
<script>content of inline1</script>
<script src="bar.js"></script>
<script>content of inline2</script>
...
</source>


'''Note:''' Named inline asset may be as dependency to another inline asset, hovewer it is not recomended to use an inline asset as dependency to non-inline asset. This will work, but this behavior may changes in future. Prefer to use "position" instead.

== Working with a web component == 


Joomla! allows you to use Web Components (https://developer.mozilla.org/en-US/docs/Web/Web_Components) for your needs. In Joomla! web components are not loaded as regular script, but loaded via Web Component loader so that they are loaded asynchronously. Therefore, a web component asset item must have a flag "webcomponent" set to the boolean "true".
In all other aspects, working with web components in AssetManager is the same as working with a "script" asset item.


Example json definition of some web components in joomla.asset.json:
<source lang="json">
...
{
"name": "webcomponent.foobar",
"type": "style",
"uri": "com_example/foobar-custom-element.css",
"webcomponent": true
},
{
"name": "webcomponent.foobar",
"type": "script",
"uri": "com_example/foobar-custom-element.js",
"webcomponent": true
}
...
</source>


Alternatively you can register them in PHP:
<source lang="php">
$wa->registerStyle('webcomponent.foobar', 'com_example/foobar-custom-element.css', ['webcomponent' => true])
->registerScript('webcomponent.foobar', 'com_example/foobar-custom-element.js', ['webcomponent' => true]);
</source>


Attach to document:
<source lang="php">
$wa->useStyle('webcomponent.foobar')
->useScript('webcomponent.foobar');
</source>


'''Note:''' It is preferred to prefix the asset name with "webcomponent." to make it easily to spot, and distinct it from regular scripts in a layout.

=== Methods to work with web component === 


All methods to work with a web component are the same as methods to work with script asset item.

== Working with a presets == 


"Preset" is a special kind of asset item that hold a list of items that has to be enabled, in same way as direct call of useAsset() to each of item in the list.
Preset can hold mixed types of assets (script, style, another preset, etc), the type should be provided after # symbol and follows after an asset name, example: foo#style, bar#script.


Example json defination of item in joomla.asset.json:
<source lang="json">
...
{
"name": "foobar",
"type": "preset",
"uri": "",
"dependencies": [
"core#script",
"foobar#style",
"foobar#script",
]
}
...
</source>

=== Methods to work with preset === 
AssetManager offer next methods to work with preset items:
<source lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();


// Attach all items from foobar preset to the document
$wa->usePreset('foobar');


// Disable all items from foobar preset from being attached
$wa->disablePreset('foobar');


// Register custom item without json defination
$wa->registerPreset('bar', '', [], [], ['core#script', 'bar#script']);
// And use it later
$wa->usePreset('bar');


// Register and attach a custom item in one run
$wa->registerAndUsePreset('bar','', [], [], ['core#script', 'bar#script']);
</source>

== Advanced: Custom WebAssetItem class == 
</translate>

<translate> The default class for all WebAsset items is '''Joomla\CMS\WebAsset\WebAssetItem'''.</translate>

<translate> You are also allowed to use a custom class, which must implement '''Joomla\CMS\WebAsset\WebAssetItemInterface''' or extend '''Joomla\CMS\WebAsset\WebAssetItem'''.</translate>

<translate> A custom class can allow you to do advanced actions, for example, including a script file depending on an active language:</translate>
<source lang="php">
class MyComExampleAssetItem extends WebAssetItem
{
public function getUri($resolvePath = true): string
{
$langTag = Factory::getApplication()->getLanguage()->getTag();
// For script asset use ".js", for style we would use ".css"
$path = 'com_example/bar-' . $langTag . '.js';

if ($resolvePath)
{
// For script asset use "script", for style we would use "stylesheet"
$path = $this->resolvePath($path, 'script');
}

return $path;
}
}
</source>

<translate> Additionally, implementing '''Joomla\CMS\WebAsset\WebAssetAttachBehaviorInterface''' allows you to add a script options (which may depend on the environment) when your asset is enabled and attached to the Document.</translate>

<source lang="php">
class MyFancyFoobarAssetItem extends WebAssetItem implements WebAssetAttachBehaviorInterface
{
public function onAttachCallback(Document $doc): void
{
$user = Factory::getApplication()->getIdentity();
$doc->addScriptOptions('com_example.fancyfoobar', ['userName' => $user->username]);
}
}
</source>

'''Important note:''' An asset item that implements '''WebAssetAttachBehaviorInterface''' should be enabled before [https://docs.joomla.org/Plugin/Events/System#onBeforeCompileHead onBeforeCompileHead] event, otherwise 'onAttachCallback' will be ignored.

<translate>
=== Defining a custom WebAssetItem class in joomla.asset.json === 
</translate>

<translate> In joomla.asset.json you can define which Class should be used with specific AssetItem.</translate>
<translate> For this you can use 2 properties '''namespace''' and '''class'''. '''namespace''' can be defined at Root level (then it will be used as default namespace for all Asset items in joomla.asset.json) or in the Item level. For example:</translate>

<source lang="json">
{
"$schema": "https://developer.joomla.org/schemas/json-schema/web_assets.json",
"name": "com_example",
"version": "4.0.0",
"namespace": "Joomla\Component\Example\WebAsset",
"assets": [
{
"name": "foo",
"type": "script",
"class": "FooAssetItem",
"uri": "com_example/foo.js"
},
{
"name": "bar",
"type": "script",
"namespace": "MyFooBar\Library\Example\WebAsset",
"class": "BarAssetItem",
"uri": "com_example/bar.js"
}
]
}
</source>
<translate> Here the asset '''foo''' will be associated with class '''Joomla\Component\Example\WebAsset\FooAssetItem''', and '''bar''' with class '''MyFooBar\Library\Example\WebAsset\BarAssetItem'''.</translate>

<translate> '''Note:''' If '''namespace''' are not defined then by default will be used '''Joomla\CMS\WebAsset'''. When '''namespace''' is defined but empty, then no namespace will be used, only '''class'''. Example:</translate>
<source lang="json">
{
"$schema": "https://developer.joomla.org/schemas/json-schema/web_assets.json",
"name": "com_example",
"assets": [
{
"name": "foo",
"type": "script",
"class": "FooAssetItem",
"uri": "com_example/foo.js"
},
{
"name": "bar",
"type": "script",
"namespace": "",
"class": "BarAssetItem",
"uri": "com_example/bar.js"
}
]
}
</source>
<translate> Here the asset '''foo''' will be associated with class '''Joomla\CMS\WebAsset\FooAssetItem''', and '''bar''' with class '''BarAssetItem''' (without namespace).</translate>

<noinclude>
[[Category:Joomla! 4.x{{#translation:}}]]
[[Category:Joomla! 4.0{{#translation:}}]]
[[Category:Tutorials{{#translation:}}]]
[[Category:Development{{#translation:}}]]
</noinclude>

J4.x:Web Assets

2020-12-22T00:03:10Z

Garkell: readability

<noinclude><languages /></noinclude>
<translate>
== Concept == 
</translate>
<translate> In the frontend world many assets are related. For example our keepalive script depends on the core.js file for options management. In Joomla there never was an easy way to specify this, you just had to include multiple files. Joomla 4 changes this with the concept of web assets.</translate>

<translate>
== Definition == 
</translate>
<translate> Related assets are defined in a JSON file such as [https://github.com/joomla/joomla-cms/blob/7b72c565b610e02c1b01f8958d622879631fa6a2/build/media_source/system/joomla.asset.json#L14-L21 system/joomla.asset.json#L14-L21] </translate>

<translate> This has a structure of having a schema definition (for validation), name, version, license and then one or more asset definitions. Assets are comprised of a list of js files and css files related to the assets and any dependencies. The dependencies section is just a list of asset names that are required for the asset to function. Example:</translate>

<source lang="json">
{
"$schema": "https://developer.joomla.org/schemas/json-schema/web_assets.json",
"name": "com_example",
"version": "4.0.0",
"description": "Joomla CMS",
"license": "GPL-2.0+",
"assets": [
{
"name": "bar",
"type": "style",
"uri": "com_example/bar.css"
},
{
"name": "bar",
"type": "script",
"uri": "com_example/bar.js"
},
{
"name": "beer",
"type": "style",
"uri": "com_example/beer.css",
"dependencies": [
"bar"
],
},
{
"name": "beer",
"type": "script",
"dependencies": [
"core",
"bar"
],
"uri": "com_example/beer.js",
"attributes": {
"defer": true,
"data-foo": "bar"
}
}
]
}
</source>

The <source lang="json" inline>$schema</source> attribute is a schema definition file that allows you to validate your file using JSON Schema. Read [https://json-schema.org/understanding-json-schema/index.html the official website] for more information on json schema validation works.

'''Note:''' Having joomla.asset.json for your extension or template are recommend but not required to WebAssset to work (see next section).

'''Note:''' It is not recommended to add an inline asset to a json file, prefer to use a file.

== Explaining asset stages ==

Each asset has 2 stages: registered and used.

'''Registered''' is where an asset is loaded into '''WebAssetRegistry'''. That means '''WebAssetManager''' knows about the existence of these assets, but will not attach them to a document while rendering.
All assets loaded from joomla.asset.json is at '''registered''' stage.

'''Used''' is where an asset is enabled via "$wa->useAsset()" (->useScript(), ->useStyle(), ->registerAndUseX() etc). That means '''WebAssetManager''' will attach these assets and their dependencies to a document while rendering.

An asset cannot be used if it was not registered before, this will cause an unknown asset exception.

== Register an asset ==

All known assets loaded and then stored in '''WebAssetRegistry''' (to enable/disable an asset item you have to use '''WebAssetManager''', see next section).

<translate> Joomla! will look for next assets definition automatically at runtime (in following order):</translate>
<pre>
media/vendor/joomla.asset.json (on first access to WebAssetRegistry)
media/system/joomla.asset.json
media/legacy/joomla.asset.json
media/{com_active_component}/joomla.asset.json (on dispatch the application)
templates/{active_template}/joomla.asset.json
</pre>

And load them to registry of known assets.

<translate> '''Note:''' Each following assets definition will override asset items from previous assets definition, by item name.</translate>

<translate> You can register your own assets definition via '''WebAssetRegistry''':</translate>

<source lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();
$wr = $wa->getRegistry();
$wr->addRegistryFile('relative/path/to/your/joomla.asset.json');
</source>

<translate> To add a custom asset item at runtime:</translate>
<source lang="php">
$wr->add('script', new Joomla\CMS\WebAsset\WebAssetItem('foobar', 'com_foobar/file.js', ['type' => 'script']));
</source>

Or more simply, using '''WebAssetManager''':
<source lang="php">
$wa->registerScript('foobar', 'com_foobar/file.js');
</source>

The new asset item '''foobar''' will be added to the registry of know assets, but will not be attached to a document until your code (a layout, template etc) will request it.

<translate> To check whether an asset exists:</translate>
<source lang="php">
if ($wa->assetExists('script', 'foobar'))
{
var_dump('Script "foobar" exists!');
}
</source>

<translate>

== Enabling an asset == 
</translate>
<translate> All asset management in the current Document handled by '''WebAssetManager''', which is accessible with '''$doc->getWebAssetManager();'''</translate>
<translate> By using AssetManager you can enable or disable needed asset easily in Joomla! through a standard methods.</translate>

<translate> To enable an asset in the page use the useAsset function, for example:</translate>

<source lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();
$wa->useScript('keepalive');

// Or multiple
$wa->useScript('keepalive')
->useScript('fields.validate')
->useStyle('foobar')
->useScript('foobar');

// Add new asset item with dependency and use it
$wa->registerAndUseScript('bar', 'com_foobar/bar.js', [], [], ['core', 'foobar']);
</source>

<translate> '''WebAssetManager''' will look to '''WebAssetRegistry''' whether the requested asset exists, and will enable it for current Document instance. Otherwise it will throw an UnknownAssetException.</translate>

<translate> To disable an asset in the page use the disableAsset function. The example below will disable the jquery-noconflict asset from being loaded.</translate>

<source lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();
$wa->disableScript('jquery-noconflict');
</source>

<translate> '''Note:''' If there are any dependencies to the disabled asset, then this asset will be re-enabled automatically, no matter what.</translate>

<translate> To check whether asset enabled, and the asset state:</translate>
<source lang="php">
// Checking whether an asset are active (enabled manually or automatically as dependency)
if ($wa->isAssetActive('script', 'foobar'))
{
var_dump('Script "foobar" are active!');
}

// Checking state
switch($wa->getAssetState('script', 'foobar')){
case Joomla\CMS\WebAsset\WebAssetManager::ASSET_STATE_ACTIVE:
var_dump('Active! Was enabled manually');
break;
case Joomla\CMS\WebAsset\WebAssetManager::ASSET_STATE_DEPENDENCY:
var_dump('Active! Was enabled automatically while resolving dependencies');
break;
default:
var_dump('not active!');
}
</source>

<translate>

== Overriding an asset == 


Overriding may be useful when you need to redefine the URI of asset item or its dependencies.


As already was noted, each of the following assets definition from joomla.asset.json will override asset items from previous assets definitions, by item name.


That means if you provide joomla.asset.json which contain already loaded asset items, they will be replaced with your items.


Another way to override in the code is to register an item with the same name.


Example, we have "foobar" script, that load com_example/foobar.js library, and we want to use CDN for this exact library:


How it defined in the system initially:


<source lang="json">
...
{
"name": "foobar",
"type": "script",
"uri": "com_example/foobar.js",
"dependencies": ["core"]
}
...
</source>


To override the URI we define the asset item with "foobar" name in our joomla.asset.json:


<source lang="json">
...
{
"name": "foobar",
"type": "script",
"uri": "http://foobar.cdn.blabla/foobar.js",
"dependencies": ["core"]
}
...
</source>


Or, register new asset item with AssetManager:
<source lang="php">
$wa->registerScript('foobar', 'http://fobar.cdn.blabla/foobar.js', [], [], ['core']);
</source>

== Working with a styles == 


AssetManager allow to manage Stylesheet files. Stylesheet asset item have a type "style".


Example json defination of item in joomla.asset.json:
<source lang="json">
...
{
"name": "foobar",
"type": "style",
"uri": "com_example/foobar.css"
}
...
</source>

=== Methods to work with styles === 
AssetManager offers the following methods to work with style files:
<source lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();


// Attach foobar to the document
$wa->useStyle('foobar');


// Disable foobar from being attached
$wa->disableStyle('foobar');


// Register custom item without json defination
$wa->registerStyle('bar', 'com_example/bar.css', [], ['data-foo' => 'some attribute'], ['some.dependency']);
// And use it later
$wa->useStyle('bar');


// Register and attach a custom item in one run
$wa->registerAndUseStyle('bar', 'com_example/bar.css', [], ['data-foo' => 'some attribute'], ['some.dependency']);
</source>

=== Add inline style === 


Addittionaly to style files WebAssetManager allow to add an inline style, and maintain their relation to the file asset.
Inline style may be placed directly before the dependency, after the dependency, or as usual after all styles.


Inline asset may have a name as well as other assets (but not required), the name can be used to retrive the asset item form a registry, or as dependecy to another inline asset. If name not specified then will be used generated name based on a content hash.


<source lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();


// Add an inline content as usual, will be rendered in flow after all assets
$wa->addInlineStyle('content of inline1');


// Add an inline content that will be placed after "foobar" asset
$wa->addInlineStyle('content of inline2', ['position' => 'after'], ['data-foo' => 'bar'], ['foobar']);


// Add an inline content that will be placed before "foobar" asset
$wa->addInlineStyle('content of inline3', ['position' => 'before'], [], ['foobar']);


// Named inline asset
$wa->addInlineStyle('content of inline4', ['name' => 'my.inline.asset']);
</source>


'''Note:''' "foobar" asset should exist in the asset registry, otherwise you will get an unsatisfied dependency exception.


Example above will produce:
<source lang="html5">
...
<style>content of inline3</style>
<link rel="stylesheet" href="foobar.css" />
<style data-foo="bar">content of inline2</style>
...
...
<style>content of inline1</style>
<style>content of inline4</style>
...
</source>


If inline asset have a multiple dependencies, then will be used last one for positioning. Example:
<source lang="php">
$wa->addInlineStyle('content of inline1', ['position' => 'before'], [], ['foo', 'bar']);
$wa->addInlineStyle('content of inline2', ['position' => 'after'], [], ['foo', 'bar']);
</source>
Will produce:
<source lang="html5">
...
<link rel="stylesheet" href="foo.css" />
<style>content of inline1</style>
<link rel="stylesheet" href="bar.css" />
<style>content of inline2</style>
...
</source>


'''Note:''' Named inline asset may be as dependency to another inline asset, hovewer it is not recomended to use an inline asset as dependency to non-inline asset. This will work, but this behavior may changes in future. Prefer to use "position" instead.

== Working with a scripts == 


AssetManager allow to manage Script files. Script asset item have a type "script".


Example json defination of item in joomla.asset.json:
<source lang="json">
...
{
"name": "foobar",
"type": "script",
"uri": "com_example/foobar.js",
"dependencies": ["core"]
}
...
</source>

=== Methods to work with scripts === 
AssetManager offer next methods to work with script files:
<source lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();


// Attach foobar to the document
$wa->useScript('foobar');


// Disable foobar from being attached
$wa->disableScript('foobar');


// Register custom item without json defination
$wa->registerScript('bar', 'com_example/bar.js', [], ['defer' => true], ['core']);
// And use it later
$wa->useScript('bar');


// Register and attach a custom item in one run
$wa->registerAndUseScript('bar','com_example/bar.js', [], ['defer' => true], ['core']);
</source>

=== Add inline script === 


Addittionaly to script files WebAssetManager allow to add an inline script, and maintain their relation to the file asset.
Inline script may be placed directly before the dependency, after the dependency, or as usual after all scripts.


Inline asset may have a name as well as other assets (but not required), the name can be used to retrive the asset item form a registry, or as dependecy to another inline asset. If name not specified then will be used generated name based on a content hash.


<source lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();


// Add an inline content as usual, will be rendered in flow after all assets
$wa->addInlineScript('content of inline1');


// Add an inline content that will be placed after "foobar" asset
$wa->addInlineScript('content of inline2', ['position' => 'after'], ['data-foo' => 'bar'], ['foobar']);


// Add an inline content that will be placed before "foobar" asset
$wa->addInlineScript('content of inline3', ['position' => 'before'], [], ['foobar']);


// Named inline asset
$wa->addInlineScript('content of inline4', ['name' => 'my.inline.asset']);


// Specify script type
$wa->addInlineScript('content of inline5', [], ['type' => 'module']);
</source>


'''Note:''' "foobar" asset should exist in the asset registry, otherwise you will get an unsatisfied dependency exception.


Example above will produce:
<source lang="html5">
...
<script>content of inline3</script>
<script src="foobar.js"></script>
<script data-foo="bar">content of inline2</script>
...
...
<script>content of inline1</script>
<script>content of inline4</script>
<script type="module">content of inline5</script>
...
</source>


If inline asset have a multiple dependencies, then will be used last one for positioning. Example:
<source lang="php">
$wa->addInlineScript('content of inline1', ['position' => 'before'], [], ['foo', 'bar']);
$wa->addInlineScript('content of inline2', ['position' => 'after'], [], ['foo', 'bar']);
</source>
Will produce:
<source lang="html5">
...
<script src="foo.js"></script>
<script>content of inline1</script>
<script src="bar.js"></script>
<script>content of inline2</script>
...
</source>


'''Note:''' Named inline asset may be as dependency to another inline asset, hovewer it is not recomended to use an inline asset as dependency to non-inline asset. This will work, but this behavior may changes in future. Prefer to use "position" instead.

== Working with a web component == 


Joomla! allows you to use Web Components (https://developer.mozilla.org/en-US/docs/Web/Web_Components) for your needs. In Joomla! web components are not loaded as regular script, but loaded via Web Component loader so that they are loaded asynchronously. Therefore, a web component asset item must have a flag "webcomponent" set to the boolean "true".
In all other aspects, working with web components in AssetManager is the same as working with a "script" asset item.


Example json definition of some web components in joomla.asset.json:
<source lang="json">
...
{
"name": "webcomponent.foobar",
"type": "style",
"uri": "com_example/foobar-custom-element.css",
"webcomponent": true
},
{
"name": "webcomponent.foobar",
"type": "script",
"uri": "com_example/foobar-custom-element.js",
"webcomponent": true
}
...
</source>


Alternatively you can register them in PHP:
<source lang="php">
$wa->registerStyle('webcomponent.foobar', 'com_example/foobar-custom-element.css', ['webcomponent' => true])
->registerScript('webcomponent.foobar', 'com_example/foobar-custom-element.js', ['webcomponent' => true]);
</source>


Attach to document:
<source lang="php">
$wa->useStyle('webcomponent.foobar')
->useScript('webcomponent.foobar');
</source>


'''Note:''' It is preferred to prefix the asset name with "webcomponent." to make it easily to spot, and distinct it from regular scripts in a layout.

=== Methods to work with web component === 


All methods to work with a web component are the same as methods to work with script asset item.

== Working with a presets == 


"Preset" is a special kind of asset item that hold a list of items that has to be enabled, in same way as direct call of useAsset() to each of item in the list.
Preset can hold mixed types of assets (script, style, another preset, etc), the type should be provided after # symbol and follows after an asset name, example: foo#style, bar#script.


Example json defination of item in joomla.asset.json:
<source lang="json">
...
{
"name": "foobar",
"type": "preset",
"uri": "",
"dependencies": [
"core#script",
"foobar#style",
"foobar#script",
]
}
...
</source>

=== Methods to work with preset === 
AssetManager offer next methods to work with preset items:
<source lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();


// Attach all items from foobar preset to the document
$wa->usePreset('foobar');


// Disable all items from foobar preset from being attached
$wa->disablePreset('foobar');


// Register custom item without json defination
$wa->registerPreset('bar', '', [], [], ['core#script', 'bar#script']);
// And use it later
$wa->usePreset('bar');


// Register and attach a custom item in one run
$wa->registerAndUsePreset('bar','', [], [], ['core#script', 'bar#script']);
</source>

== Advanced: Custom WebAssetItem class == 
</translate>

<translate> The default class for all WebAsset items is '''Joomla\CMS\WebAsset\WebAssetItem'''.</translate>

<translate> You are also allowed to use a custom class, which must implement '''Joomla\CMS\WebAsset\WebAssetItemInterface''' or extend '''Joomla\CMS\WebAsset\WebAssetItem'''.</translate>

<translate> A custom class can allow you to do advanced actions, for example, including a script file depending on an active language:</translate>
<source lang="php">
class MyComExampleAssetItem extends WebAssetItem
{
public function getUri($resolvePath = true): string
{
$langTag = Factory::getApplication()->getLanguage()->getTag();
// For script asset use ".js", for style we would use ".css"
$path = 'com_example/bar-' . $langTag . '.js';

if ($resolvePath)
{
// For script asset use "script", for style we would use "stylesheet"
$path = $this->resolvePath($path, 'script');
}

return $path;
}
}
</source>

<translate> Additionally, implementing '''Joomla\CMS\WebAsset\WebAssetAttachBehaviorInterface''' allows you to add a script options (which may depend on the environment) when your asset is enabled and attached to the Document.</translate>

<source lang="php">
class MyFancyFoobarAssetItem extends WebAssetItem implements WebAssetAttachBehaviorInterface
{
public function onAttachCallback(Document $doc): void
{
$user = Factory::getApplication()->getIdentity();
$doc->addScriptOptions('com_example.fancyfoobar', ['userName' => $user->username]);
}
}
</source>

'''Important note:''' An asset item that implements '''WebAssetAttachBehaviorInterface''' should be enabled before [https://docs.joomla.org/Plugin/Events/System#onBeforeCompileHead onBeforeCompileHead] event, otherwise 'onAttachCallback' will be ignored.

<translate>
=== Defining a custom WebAssetItem class in joomla.asset.json === 
</translate>

<translate> In joomla.asset.json you can define which Class should be used with specific AssetItem.</translate>
<translate> For this you can use 2 properties '''namespace''' and '''class'''. '''namespace''' can be defined at Root level (then it will be used as default namespace for all Asset items in joomla.asset.json) or in the Item level. For example:</translate>

<source lang="json">
{
"$schema": "https://developer.joomla.org/schemas/json-schema/web_assets.json",
"name": "com_example",
"version": "4.0.0",
"namespace": "Joomla\Component\Example\WebAsset",
"assets": [
{
"name": "foo",
"type": "script",
"class": "FooAssetItem",
"uri": "com_example/foo.js"
},
{
"name": "bar",
"type": "script",
"namespace": "MyFooBar\Library\Example\WebAsset",
"class": "BarAssetItem",
"uri": "com_example/bar.js"
}
]
}
</source>
<translate> Here the asset '''foo''' will be associated with class '''Joomla\Component\Example\WebAsset\FooAssetItem''', and '''bar''' with class '''MyFooBar\Library\Example\WebAsset\BarAssetItem'''.</translate>

<translate> '''Note:''' If '''namespace''' are not defined then by default will be used '''Joomla\CMS\WebAsset'''. When '''namespace''' is defined but empty, then no namespace will be used, only '''class'''. Example:</translate>
<source lang="json">
{
"$schema": "https://developer.joomla.org/schemas/json-schema/web_assets.json",
"name": "com_example",
"assets": [
{
"name": "foo",
"type": "script",
"class": "FooAssetItem",
"uri": "com_example/foo.js"
},
{
"name": "bar",
"type": "script",
"namespace": "",
"class": "BarAssetItem",
"uri": "com_example/bar.js"
}
]
}
</source>
<translate> Here the asset '''foo''' will be associated with class '''Joomla\CMS\WebAsset\FooAssetItem''', and '''bar''' with class '''BarAssetItem''' (without namespace).</translate>

<noinclude>
[[Category:Joomla! 4.x{{#translation:}}]]
[[Category:Joomla! 4.0{{#translation:}}]]
[[Category:Tutorials{{#translation:}}]]
[[Category:Development{{#translation:}}]]
</noinclude>

J4.x:Web Assets

2020-12-21T23:54:25Z

Garkell: /* Explaining asset stages */

<noinclude><languages /></noinclude>
<translate>
== Concept == 
</translate>
<translate> In the frontend world many assets are related. For example our keepalive script depends on the core.js file for options management. In Joomla there never was an easy way to specify this, you just had to include multiple files. Joomla 4 changes this with the concept of web assets.</translate>

<translate>
== Definition == 
</translate>
<translate> Related assets are defined in a JSON file such as [https://github.com/joomla/joomla-cms/blob/7b72c565b610e02c1b01f8958d622879631fa6a2/build/media_source/system/joomla.asset.json#L14-L21 system/joomla.asset.json#L14-L21] </translate>

<translate> This has a structure of having a schema definition (for validation), name, version, license and then one or more asset definitions. Assets are comprised of a list of js files and css files related to the assets and any dependencies. The dependencies section is just a list of asset names that are required for the asset to function. Example:</translate>

<source lang="json">
{
"$schema": "https://developer.joomla.org/schemas/json-schema/web_assets.json",
"name": "com_example",
"version": "4.0.0",
"description": "Joomla CMS",
"license": "GPL-2.0+",
"assets": [
{
"name": "bar",
"type": "style",
"uri": "com_example/bar.css"
},
{
"name": "bar",
"type": "script",
"uri": "com_example/bar.js"
},
{
"name": "beer",
"type": "style",
"uri": "com_example/beer.css",
"dependencies": [
"bar"
],
},
{
"name": "beer",
"type": "script",
"dependencies": [
"core",
"bar"
],
"uri": "com_example/beer.js",
"attributes": {
"defer": true,
"data-foo": "bar"
}
}
]
}
</source>

The <source lang="json" inline>$schema</source> attribute is a schema definition file that allows you to validate your file using JSON Schema. Read [https://json-schema.org/understanding-json-schema/index.html the official website] for more information on json schema validation works.

'''Note:''' Having joomla.asset.json for your extension or template are recommend but not required to WebAssset to work (see next section).

'''Note:''' It is not recommended to add an inline asset to a json file, prefer to use a file.

== Explaining asset stages ==

Each asset has 2 stages: registered and used.

'''Registered''' is where an asset is loaded into '''WebAssetRegistry'''. That means '''WebAssetManager''' knows about the existence of these assets, but will not attach them to a document while rendering.
All assets loaded from joomla.asset.json is at '''registered''' stage.

'''Used''' is where an asset is enabled via "$wa->useAsset()" (->useScript(), ->useStyle(), ->registerAndUseX() etc). That means '''WebAssetManager''' will attach these assets and their dependencies to a document while rendering.

An asset cannot be used if it was not registered before, this will cause an unknown asset exception.

== Register an asset ==

All known assets loaded and then stored in '''WebAssetRegistry''' (to enable/disable an asset item you have to use '''WebAssetManager''', see next section).

<translate> Joomla! will look for next assets definition automatically at runtime (in following order):</translate>
<pre>
media/vendor/joomla.asset.json (on first access to WebAssetRegistry)
media/system/joomla.asset.json
media/legacy/joomla.asset.json
media/{com_active_component}/joomla.asset.json (on dispatch the application)
templates/{active_template}/joomla.asset.json
</pre>

And load them to registry of known assets.

<translate> '''Note:''' Each following assets definition will override asset items from previous assets definition, by item name.</translate>

<translate> You can register your own assets definition via '''WebAssetRegistry''':</translate>

<source lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();
$wr = $wa->getRegistry();
$wr->addRegistryFile('relative/path/to/your/joomla.asset.json');
</source>

<translate> To add a custom asset item at runtime:</translate>
<source lang="php">
$wr->add('script', new Joomla\CMS\WebAsset\WebAssetItem('foobar', 'com_foobar/file.js', ['type' => 'script']));
</source>

Or more simply, using '''WebAssetManager''':
<source lang="php">
$wa->registerScript('foobar', 'com_foobar/file.js');
</source>

The new asset item '''foobar''' will be added to the registry of know assets, but will not be attached to a document until your code (a layout, template etc) will request it.

<translate> To check whether an asset exists:</translate>
<source lang="php">
if ($wa->assetExists('script', 'foobar'))
{
var_dump('Script "foobar" exists!');
}
</source>

<translate>

== Enabling an asset == 
</translate>
<translate> All asset management in the current Document handled by '''WebAssetManager''', which is accessible with '''$doc->getWebAssetManager();'''</translate>
<translate> By using AssetManager you can enable or disable needed asset easily in Joomla! through a standard methods.</translate>

<translate> To enable an asset in the page use the useAsset function, for example:</translate>

<source lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();
$wa->useScript('keepalive');

// Or multiple
$wa->useScript('keepalive')
->useScript('fields.validate')
->useStyle('foobar')
->useScript('foobar');

// Add new asset item with dependency and use it
$wa->registerAndUseScript('bar', 'com_foobar/bar.js', [], [], ['core', 'foobar']);
</source>

<translate> '''WebAssetManager''' will look to '''WebAssetRegistry''' whether the requested asset exists, and will enable it for current Document instance. Otherwise it will throw an UnknownAssetException.</translate>

<translate> To disable an asset in the page use the disableAsset function. The example below will disable the jquery-noconflict asset from being loaded.</translate>

<source lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();
$wa->disableScript('jquery-noconflict');
</source>

<translate> '''Note:''' If there are any dependencies to the disabled asset, then this asset will be re-enabled automatically, no matter what.</translate>

<translate> To check whether asset enabled, and the asset state:</translate>
<source lang="php">
// Checking whether an asset are active (enabled manually or automatically as dependency)
if ($wa->isAssetActive('script', 'foobar'))
{
var_dump('Script "foobar" are active!');
}

// Checking state
switch($wa->getAssetState('script', 'foobar')){
case Joomla\CMS\WebAsset\WebAssetManager::ASSET_STATE_ACTIVE:
var_dump('Active! Was enabled manually');
break;
case Joomla\CMS\WebAsset\WebAssetManager::ASSET_STATE_DEPENDENCY:
var_dump('Active! Was enabled automatically while resolving dependencies');
break;
default:
var_dump('not active!');
}
</source>

<translate>

== Overriding an asset == 


Overriding may be useful when you need to redefine the URI of asset item or its dependencies.


As already was noted, each of the following assets definition from joomla.asset.json will override asset items from previous assets definitions, by item name.


That means if you provide joomla.asset.json which contain already loaded asset items, they will be replaced with your items.


Another way to override in the code is to register an item with the same name.


Example, we have "foobar" script, that load com_example/foobar.js library, and we want to use CDN for this exact library:


How it defined in the system initially:


<source lang="json">
...
{
"name": "foobar",
"type": "script",
"uri": "com_example/foobar.js",
"dependencies": ["core"]
}
...
</source>


To override the URI we define the asset item with "foobar" name in our joomla.asset.json:


<source lang="json">
...
{
"name": "foobar",
"type": "script",
"uri": "http://foobar.cdn.blabla/foobar.js",
"dependencies": ["core"]
}
...
</source>


Or, register new asset item with AssetManager:
<source lang="php">
$wa->registerScript('foobar', 'http://fobar.cdn.blabla/foobar.js', [], [], ['core']);
</source>

== Working with a styles == 


AssetManager allow to manage Stylesheet files. Stylesheet asset item have a type "style".


Example json defination of item in joomla.asset.json:
<source lang="json">
...
{
"name": "foobar",
"type": "style",
"uri": "com_example/foobar.css"
}
...
</source>

=== Methods to work with styles === 
AssetManager offer next methods to work with style files:
<source lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();


// Attach foobar to the document
$wa->useStyle('foobar');


// Disable foobar from being attached
$wa->disableStyle('foobar');


// Register custom item without json defination
$wa->registerStyle('bar', 'com_example/bar.css', [], ['data-foo' => 'some attribute'], ['some.dependency']);
// And use it later
$wa->useStyle('bar');


// Register and attach a custom item in one run
$wa->registerAndUseStyle('bar', 'com_example/bar.css', [], ['data-foo' => 'some attribute'], ['some.dependency']);
</source>

=== Add inline style === 


Addittionaly to style files WebAssetManager allow to add an inline style, and maintain their relation to the file asset.
Inline style may be placed directly before the dependency, after the dependency, or as usual after all styles.


Inline asset may have a name as well as other assets (but not required), the name can be used to retrive the asset item form a registry, or as dependecy to another inline asset. If name not specified then will be used generated name based on a content hash.


<source lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();


// Add an inline content as usual, will be rendered in flow after all assets
$wa->addInlineStyle('content of inline1');


// Add an inline content that will be placed after "foobar" asset
$wa->addInlineStyle('content of inline2', ['position' => 'after'], ['data-foo' => 'bar'], ['foobar']);


// Add an inline content that will be placed before "foobar" asset
$wa->addInlineStyle('content of inline3', ['position' => 'before'], [], ['foobar']);


// Named inline asset
$wa->addInlineStyle('content of inline4', ['name' => 'my.inline.asset']);
</source>


'''Note:''' "foobar" asset should exist in the asset registry, otherwise you will get an unsatisfied dependency exception.


Example above will produce:
<source lang="html5">
...
<style>content of inline3</style>
<link rel="stylesheet" href="foobar.css" />
<style data-foo="bar">content of inline2</style>
...
...
<style>content of inline1</style>
<style>content of inline4</style>
...
</source>


If inline asset have a multiple dependencies, then will be used last one for positioning. Example:
<source lang="php">
$wa->addInlineStyle('content of inline1', ['position' => 'before'], [], ['foo', 'bar']);
$wa->addInlineStyle('content of inline2', ['position' => 'after'], [], ['foo', 'bar']);
</source>
Will produce:
<source lang="html5">
...
<link rel="stylesheet" href="foo.css" />
<style>content of inline1</style>
<link rel="stylesheet" href="bar.css" />
<style>content of inline2</style>
...
</source>


'''Note:''' Named inline asset may be as dependency to another inline asset, hovewer it is not recomended to use an inline asset as dependency to non-inline asset. This will work, but this behavior may changes in future. Prefer to use "position" instead.

== Working with a scripts == 


AssetManager allow to manage Script files. Script asset item have a type "script".


Example json defination of item in joomla.asset.json:
<source lang="json">
...
{
"name": "foobar",
"type": "script",
"uri": "com_example/foobar.js",
"dependencies": ["core"]
}
...
</source>

=== Methods to work with scripts === 
AssetManager offer next methods to work with script files:
<source lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();


// Attach foobar to the document
$wa->useScript('foobar');


// Disable foobar from being attached
$wa->disableScript('foobar');


// Register custom item without json defination
$wa->registerScript('bar', 'com_example/bar.js', [], ['defer' => true], ['core']);
// And use it later
$wa->useScript('bar');


// Register and attach a custom item in one run
$wa->registerAndUseScript('bar','com_example/bar.js', [], ['defer' => true], ['core']);
</source>

=== Add inline script === 


Addittionaly to script files WebAssetManager allow to add an inline script, and maintain their relation to the file asset.
Inline script may be placed directly before the dependency, after the dependency, or as usual after all scripts.


Inline asset may have a name as well as other assets (but not required), the name can be used to retrive the asset item form a registry, or as dependecy to another inline asset. If name not specified then will be used generated name based on a content hash.


<source lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();


// Add an inline content as usual, will be rendered in flow after all assets
$wa->addInlineScript('content of inline1');


// Add an inline content that will be placed after "foobar" asset
$wa->addInlineScript('content of inline2', ['position' => 'after'], ['data-foo' => 'bar'], ['foobar']);


// Add an inline content that will be placed before "foobar" asset
$wa->addInlineScript('content of inline3', ['position' => 'before'], [], ['foobar']);


// Named inline asset
$wa->addInlineScript('content of inline4', ['name' => 'my.inline.asset']);


// Specify script type
$wa->addInlineScript('content of inline5', [], ['type' => 'module']);
</source>


'''Note:''' "foobar" asset should exist in the asset registry, otherwise you will get an unsatisfied dependency exception.


Example above will produce:
<source lang="html5">
...
<script>content of inline3</script>
<script src="foobar.js"></script>
<script data-foo="bar">content of inline2</script>
...
...
<script>content of inline1</script>
<script>content of inline4</script>
<script type="module">content of inline5</script>
...
</source>


If inline asset have a multiple dependencies, then will be used last one for positioning. Example:
<source lang="php">
$wa->addInlineScript('content of inline1', ['position' => 'before'], [], ['foo', 'bar']);
$wa->addInlineScript('content of inline2', ['position' => 'after'], [], ['foo', 'bar']);
</source>
Will produce:
<source lang="html5">
...
<script src="foo.js"></script>
<script>content of inline1</script>
<script src="bar.js"></script>
<script>content of inline2</script>
...
</source>


'''Note:''' Named inline asset may be as dependency to another inline asset, hovewer it is not recomended to use an inline asset as dependency to non-inline asset. This will work, but this behavior may changes in future. Prefer to use "position" instead.

== Working with a web component == 


Joomla! allows you to use Web Components (https://developer.mozilla.org/en-US/docs/Web/Web_Components) for your needs. In Joomla! web components are not loaded as regular script, but loaded via Web Component loader so that they are loaded asynchronously. Therefore, a web component asset item must have a flag "webcomponent" set to the boolean "true".
In all other aspects, working with web components in AssetManager is the same as working with a "script" asset item.


Example json definition of some web components in joomla.asset.json:
<source lang="json">
...
{
"name": "webcomponent.foobar",
"type": "style",
"uri": "com_example/foobar-custom-element.css",
"webcomponent": true
},
{
"name": "webcomponent.foobar",
"type": "script",
"uri": "com_example/foobar-custom-element.js",
"webcomponent": true
}
...
</source>


Alternatively you can register them in PHP:
<source lang="php">
$wa->registerStyle('webcomponent.foobar', 'com_example/foobar-custom-element.css', ['webcomponent' => true])
->registerScript('webcomponent.foobar', 'com_example/foobar-custom-element.js', ['webcomponent' => true]);
</source>


Attach to document:
<source lang="php">
$wa->useStyle('webcomponent.foobar')
->useScript('webcomponent.foobar');
</source>


'''Note:''' It is preferred to prefix the asset name with "webcomponent." to make it easily to spot, and distinct it from regular scripts in a layout.

=== Methods to work with web component === 


All methods to work with a web component are the same as methods to work with script asset item.

== Working with a presets == 


"Preset" is a special kind of asset item that hold a list of items that has to be enabled, in same way as direct call of useAsset() to each of item in the list.
Preset can hold mixed types of assets (script, style, another preset, etc), the type should be provided after # symbol and follows after an asset name, example: foo#style, bar#script.


Example json defination of item in joomla.asset.json:
<source lang="json">
...
{
"name": "foobar",
"type": "preset",
"uri": "",
"dependencies": [
"core#script",
"foobar#style",
"foobar#script",
]
}
...
</source>

=== Methods to work with preset === 
AssetManager offer next methods to work with preset items:
<source lang="php">
/** @var Joomla\CMS\WebAsset\WebAssetManager $wa */
$wa = Factory::getApplication()->getDocument()->getWebAssetManager();


// Attach all items from foobar preset to the document
$wa->usePreset('foobar');


// Disable all items from foobar preset from being attached
$wa->disablePreset('foobar');


// Register custom item without json defination
$wa->registerPreset('bar', '', [], [], ['core#script', 'bar#script']);
// And use it later
$wa->usePreset('bar');


// Register and attach a custom item in one run
$wa->registerAndUsePreset('bar','', [], [], ['core#script', 'bar#script']);
</source>

== Advanced: Custom WebAssetItem class == 
</translate>

<translate> The default class for all WebAsset items is '''Joomla\CMS\WebAsset\WebAssetItem'''.</translate>

<translate> You are also allowed to use a custom class, which must implement '''Joomla\CMS\WebAsset\WebAssetItemInterface''' or extend '''Joomla\CMS\WebAsset\WebAssetItem'''.</translate>

<translate> A custom class can allow you to do advanced actions, for example, including a script file depending on an active language:</translate>
<source lang="php">
class MyComExampleAssetItem extends WebAssetItem
{
public function getUri($resolvePath = true): string
{
$langTag = Factory::getApplication()->getLanguage()->getTag();
// For script asset use ".js", for style we would use ".css"
$path = 'com_example/bar-' . $langTag . '.js';

if ($resolvePath)
{
// For script asset use "script", for style we would use "stylesheet"
$path = $this->resolvePath($path, 'script');
}

return $path;
}
}
</source>

<translate> Additionally, implementing '''Joomla\CMS\WebAsset\WebAssetAttachBehaviorInterface''' allows you to add a script options (which may depend on the environment) when your asset is enabled and attached to the Document.</translate>

<source lang="php">
class MyFancyFoobarAssetItem extends WebAssetItem implements WebAssetAttachBehaviorInterface
{
public function onAttachCallback(Document $doc): void
{
$user = Factory::getApplication()->getIdentity();
$doc->addScriptOptions('com_example.fancyfoobar', ['userName' => $user->username]);
}
}
</source>

'''Important note:''' An asset item that implements '''WebAssetAttachBehaviorInterface''' should be enabled before [https://docs.joomla.org/Plugin/Events/System#onBeforeCompileHead onBeforeCompileHead] event, otherwise 'onAttachCallback' will be ignored.

<translate>
=== Defining a custom WebAssetItem class in joomla.asset.json === 
</translate>

<translate> In joomla.asset.json you can define which Class should be used with specific AssetItem.</translate>
<translate> For this you can use 2 properties '''namespace''' and '''class'''. '''namespace''' can be defined at Root level (then it will be used as default namespace for all Asset items in joomla.asset.json) or in the Item level. For example:</translate>

<source lang="json">
{
"$schema": "https://developer.joomla.org/schemas/json-schema/web_assets.json",
"name": "com_example",
"version": "4.0.0",
"namespace": "Joomla\Component\Example\WebAsset",
"assets": [
{
"name": "foo",
"type": "script",
"class": "FooAssetItem",
"uri": "com_example/foo.js"
},
{
"name": "bar",
"type": "script",
"namespace": "MyFooBar\Library\Example\WebAsset",
"class": "BarAssetItem",
"uri": "com_example/bar.js"
}
]
}
</source>
<translate> Here the asset '''foo''' will be associated with class '''Joomla\Component\Example\WebAsset\FooAssetItem''', and '''bar''' with class '''MyFooBar\Library\Example\WebAsset\BarAssetItem'''.</translate>

<translate> '''Note:''' If '''namespace''' are not defined then by default will be used '''Joomla\CMS\WebAsset'''. When '''namespace''' is defined but empty, then no namespace will be used, only '''class'''. Example:</translate>
<source lang="json">
{
"$schema": "https://developer.joomla.org/schemas/json-schema/web_assets.json",
"name": "com_example",
"assets": [
{
"name": "foo",
"type": "script",
"class": "FooAssetItem",
"uri": "com_example/foo.js"
},
{
"name": "bar",
"type": "script",
"namespace": "",
"class": "BarAssetItem",
"uri": "com_example/bar.js"
}
]
}
</source>
<translate> Here the asset '''foo''' will be associated with class '''Joomla\CMS\WebAsset\FooAssetItem''', and '''bar''' with class '''BarAssetItem''' (without namespace).</translate>

<noinclude>
[[Category:Joomla! 4.x{{#translation:}}]]
[[Category:Joomla! 4.0{{#translation:}}]]
[[Category:Tutorials{{#translation:}}]]
[[Category:Development{{#translation:}}]]
</noinclude>

J4.x:Namespace Conventions In Joomla

2020-08-20T04:18:38Z

Garkell:

<noinclude><languages /></noinclude>
<noinclude>{{Joomla version|version=4.0}}</noinclude>

<translate>
=== Base Namespaces === 
</translate>
<translate> The recommended naming conventions in Joomla 4 are the following:</translate>

<translate>
=== Components === 
</translate>

<translate>
==== Core Components ==== 
</translate>

* Joomla\Component\<ComponentName>\<ClientName>
** Joomla\Component\Content\Site
** Joomla\Component\Content\Administrator

<translate>
==== 3rd Party Components ==== 
</translate>
* <CompanyName>\<ComponentName>\<ClientName>
** Acme\Backup\Site
** Acme\Backup\Administrator

<translate>
==== Example locations ==== 
</translate>
''Joomla\Component\Content\Site\Controller''<br />
components/com_content/Controller/ArticleController.php

''Joomla\Component\Content\Administrator\Controller''<br />
administrator/components/com_content/Controller/ArticlesController.php

<translate>
=== Modules === 
</translate>

<translate>
==== Core Modules ==== 
</translate>
* Joomla\Module\<ModuleName>\<ClientName>
** Joomla\Module\UsersLatest\Site
** Joomla\Module\Quickicon\Administrator

<translate>
==== 3rd Party Modules ==== 
</translate>
* <CompanyName>\Module\<ModuleName>\<ClientName>
** Acme\Module\SubscriptionStatus\Site
** Acme\Module\LastBackupStatus\Administrator

<translate>
==== Example locations ==== 
</translate>
''Joomla\Module\Quickicon\Administrator\Dispatcher''<br />
administrator/modules/mod_quickicon/Dispatcher/Dispatcher.php

''Joomla\Module\UsersLatest\Site\Helper''<br />
modules/mod_users_latest/Helper/UsersLatestHelper.php

<translate>
=== Plugins === 
</translate>

<translate>
==== Core Plugins ==== 
</translate>
* Joomla\Plugin\<PluginGroup>\<PluginName>
** Joomla\Plugin\System\Debug
** Joomla\Plugin\Quickicon\Joomlaupdate

<translate>
==== 3rd Party Plugins ==== 
</translate>
* <CompanyName>\Plugin\<PluginGroup>\<PluginName>\
** Acme\Plugin\System\BackupOnDemand

<translate>
==== Example locations ==== 
</translate>
''Joomla\Plugin\System\Debug''<br />
plugins/system/debug/DataFormatter.php

''Joomla\Plugin\Quickicon\Joomlaupdate\Extension''<br />
plugins/quickicon/joomlaupdate/Extension/Joomlaupdate.php

<translate>
=== Framework === 
</translate>

<translate>
==== Joomla Framework Library ==== 
</translate>
* Joomla
** Joomla\Session
** Joomla\Image

<translate>
==== Joomla CMS Library ==== 
</translate>
* Joomla\CMS
** Joomla\CMS\Mail
** Joomla\CMS\MVC

<translate>
==== Example locations ==== 
</translate>
''Joomla\Session''<br />
libraries/vendor/joomla/session/src/Session.php

''Joomla\CMS\Mail''<br />
libraries/src/Mail/Mail.php

<noinclude>
[[Category:Development{{#translation:}}]]
[[Category:Joomla! 4.x{{#translation:}}]]
[[Category:Joomla! 4.0{{#translation:}}]]
</noinclude>

J4.x:Namespace Conventions In Joomla

2020-08-20T04:17:25Z

Garkell: Added extra headings to make it more defined

<noinclude><languages /></noinclude>
<noinclude>{{Joomla version|version=4.0}}</noinclude>

<translate>
=== Base Namespaces === 
</translate>
<translate> The recommended naming conventions in Joomla 4 are the following:</translate>

<translate>
=== Components === 
</translate>

<translate>
==== Core Components ==== 
</translate>

* Joomla\Component\<ComponentName>\<ClientName>
** Joomla\Component\Content\Site
** Joomla\Component\Content\Administrator

<translate>
==== 3rd Party Components ==== 
</translate>
* <CompanyName>\<ComponentName>\<ClientName>
** Acme\Backup\Site
** Acme\Backup\Administrator

<translate>
===== Example locations ===== 
</translate>
''Joomla\Component\Content\Site\Controller''<br />
components/com_content/Controller/ArticleController.php

''Joomla\Component\Content\Administrator\Controller''<br />
administrator/components/com_content/Controller/ArticlesController.php

<translate>
=== Modules === 
</translate>

<translate>
==== Core Modules ==== 
</translate>
* Joomla\Module\<ModuleName>\<ClientName>
** Joomla\Module\UsersLatest\Site
** Joomla\Module\Quickicon\Administrator

<translate>
==== 3rd Party Modules ==== 
</translate>
* <CompanyName>\Module\<ModuleName>\<ClientName>
** Acme\Module\SubscriptionStatus\Site
** Acme\Module\LastBackupStatus\Administrator

<translate>
===== Example locations ===== 
</translate>
''Joomla\Module\Quickicon\Administrator\Dispatcher''<br />
administrator/modules/mod_quickicon/Dispatcher/Dispatcher.php

''Joomla\Module\UsersLatest\Site\Helper''<br />
modules/mod_users_latest/Helper/UsersLatestHelper.php

<translate>
=== Plugins === 
</translate>

<translate>
==== Core Plugins ==== 
</translate>
* Joomla\Plugin\<PluginGroup>\<PluginName>
** Joomla\Plugin\System\Debug
** Joomla\Plugin\Quickicon\Joomlaupdate

<translate>
==== 3rd Party Plugins ==== 
</translate>
* <CompanyName>\Plugin\<PluginGroup>\<PluginName>\
** Acme\Plugin\System\BackupOnDemand

<translate>
===== Example locations ===== 
</translate>
''Joomla\Plugin\System\Debug''<br />
plugins/system/debug/DataFormatter.php

''Joomla\Plugin\Quickicon\Joomlaupdate\Extension''<br />
plugins/quickicon/joomlaupdate/Extension/Joomlaupdate.php

<translate>
=== Framework === 
</translate>

<translate>
==== Joomla Framework Library ==== 
</translate>
* Joomla
** Joomla\Session
** Joomla\Image

<translate>
==== Joomla CMS Library ==== 
</translate>
* Joomla\CMS
** Joomla\CMS\Mail
** Joomla\CMS\MVC

<translate>
===== Example locations ===== 
</translate>
''Joomla\Session''<br />
libraries/vendor/joomla/session/src/Session.php

''Joomla\CMS\Mail''<br />
libraries/src/Mail/Mail.php

<noinclude>
[[Category:Development{{#translation:}}]]
[[Category:Joomla! 4.x{{#translation:}}]]
[[Category:Joomla! 4.0{{#translation:}}]]
</noinclude>

Package

2019-06-22T00:35:09Z

Garkell: Spelling

<noinclude><languages /></noinclude>
<translate>
== Note on component dependent modules== 


Sometimes modules (or plugins etc.) use a component's models and helpers and such. In these occasions it would be nice to be able to package your module in this way that it gets uninstalled when the component itself gets uninstalled. This is called dependency management which has been desired in joomla but hasn't been done yet.
It is suggested to follow the standards and just using a package as is described below.
</translate>

<translate>
== What is a package? == 


A package is a extension that is used to install multiple extensions in one go. This is used if you have for example a component and a module that are depending on each other. Combining them in a package will let the user install and uninstall both extensions in one go. Package extensions can be used with Joomla {{JVer|2.5}} and higher.
</translate>

<translate>
== How do I create a package? == 


A package extension is created by zipping all zip files of the extensions together with a xml manifest file. For example if you have a package composed by:
</translate>

<translate>

* '''component''' helloworld
* '''module''' helloworld
* '''library''' helloworld
* '''system plugin''' helloworld
* '''template''' helloworld


The package should have the following tree in your zipfile:
</translate>

-- pkg_helloworld.xml
-- packages <dir>
|-- com_helloworld.zip
|-- mod_helloworld.zip
|-- lib_helloworld.zip
|-- plg_sys_helloworld.zip
|-- tpl_helloworld.zip
-- pkg_script.php

<translate>

The pkg_helloworld.xml could have the following contents:
</translate>

<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<extension type="package" version="1.6" method="upgrade">
<name>Hello World Package</name>
<author>Hello World Package Team</author>
<creationDate>May 2012</creationDate>
<packagename>helloworld</packagename>
<version>1.0.0</version>
<url>http://www.yoururl.com/</url>
<packager>Hello World Package Team</packager>
<packagerurl>http://www.yoururl.com/</packagerurl>
<description>Example package to combine multiple extensions</description>
<update>http://www.updateurl.com/update</update>
<scriptfile>pkg_script.php</scriptfile>
<files folder="packages">
<file type="component" id="com_helloworld" >com_helloworld.zip</file>
<file type="module" id="helloworld" client="site">mod_helloworld.zip</file>
<file type="library" id="helloworld">lib_helloworld.zip</file>
<file type="plugin" id="helloworld" group="system">plg_sys_helloworld.zip</file>
<file type="template" id="helloworld" client="site">tpl_helloworld.zip</file>
</files>
</extension>
</source>

<translate>

When you zip this and try to install it, you will see that every extension will be installed. Also the package will be visible in the extension list to uninstall all the extension of this package.
</translate>

<translate>

Remember to use the package uninstaller instead of individual subpackage uninstallers to avoid orphan extension entries in the extension manager.
</translate>

<translate>
=== Id= <file id="not_arbitrary"> === 
The id element in <file ..> tag are NOT arbitrary!. The "id=" should be set to the value of the "element" column in the "#__extensions" table. If they are not set correctly, upon uninstalling of the package the children ( <file> ) will NOT be found and uninstalled.
</translate>

<translate>
=== Manifest filename and packagename === 
The naming of the manifest file and the ability to uninstall the package file itself are closely related.
The manifest file must have a "pkg_" prefix, the remainder of the manifest name ( without .xml extension ) is to be used as <packagename>. Or, the other way around, a package you want to identify as "blurpblurp_J3" get that as its <packagename> and should be in a manifest file named "pkg_blurpblurp_J3.xml". Failure to do so will make it impossible to uninstall the package itself.</translate>

<translate>
An optional <pkg_script.php> which contains a class pkg_<packagename>InstallerScript with public function postflight can be used (works in Joomla! 3.6).</translate>

<translate>
=== Extension tag === 
</translate>
<translate>
As of Joomla! 3.4, you should include method="upgrade" in the <extension> tag if you wish for your package to succeed in updating itself on subsequent installations.</translate>

<translate>
The version attribute of the <extension> tag should be set to the minimum supported version of Joomla for this package. For example, if your package only supports Joomla! 3.2 and above set this to 3.2.</translate>

<translate>
=== Extension Uninstall Dependency === 
</translate>
<translate>
As of 3.7.0, a package extension can declare that its child elements cannot be uninstalled independently with a "<blockChildUninstall>true</blockChildUninstall>" element in your package manifest. So if your package needs all it's extensions to operate effectively, set this to true or 1.
</translate>

<noinclude>
<translate>

[[Category:Extensions]]
</translate>
</noinclude>

Package

2019-06-22T00:30:32Z

Garkell: Add Uninstall dependency.

<noinclude><languages /></noinclude>
<translate>
== Note on component dependent modules== 


Sometimes modules (or plugins etc.) use a component's models and helpers and such. In these occasions it would be nice to be able to package your module in this way that it gets uninstalled when the component itself gets uninstalled. This is called dependency management which has been desired in joomla but hasn't been done yet.
It is suggested to follow the standards and just using a package as is described below.
</translate>

<translate>
== What is a package? == 


A package is a extension that is used to install multiple extensions in one go. This is used if you have for example a component and a module that are depending on each other. Combining them in a package will let the user install and uninstall both extensions in one go. Package extensions can be used with Joomla {{JVer|2.5}} and higher.
</translate>

<translate>
== How do I create a package? == 


A package extension is created by zipping all zip files of the extensions together with a xml manifest file. For example if you have a package composed by:
</translate>

<translate>

* '''component''' helloworld
* '''module''' helloworld
* '''library''' helloworld
* '''system plugin''' helloworld
* '''template''' helloworld


The package should have the following tree in your zipfile:
</translate>

-- pkg_helloworld.xml
-- packages <dir>
|-- com_helloworld.zip
|-- mod_helloworld.zip
|-- lib_helloworld.zip
|-- plg_sys_helloworld.zip
|-- tpl_helloworld.zip
-- pkg_script.php

<translate>

The pkg_helloworld.xml could have the following contents:
</translate>

<source lang="xml">
<?xml version="1.0" encoding="UTF-8" ?>
<extension type="package" version="1.6" method="upgrade">
<name>Hello World Package</name>
<author>Hello World Package Team</author>
<creationDate>May 2012</creationDate>
<packagename>helloworld</packagename>
<version>1.0.0</version>
<url>http://www.yoururl.com/</url>
<packager>Hello World Package Team</packager>
<packagerurl>http://www.yoururl.com/</packagerurl>
<description>Example package to combine multiple extensions</description>
<update>http://www.updateurl.com/update</update>
<scriptfile>pkg_script.php</scriptfile>
<files folder="packages">
<file type="component" id="com_helloworld" >com_helloworld.zip</file>
<file type="module" id="helloworld" client="site">mod_helloworld.zip</file>
<file type="library" id="helloworld">lib_helloworld.zip</file>
<file type="plugin" id="helloworld" group="system">plg_sys_helloworld.zip</file>
<file type="template" id="helloworld" client="site">tpl_helloworld.zip</file>
</files>
</extension>
</source>

<translate>

When you zip this and try to install it, you will see that every extension will be installed. Also the package will be visible in the extension list to uninstall all the extension of this package.
</translate>

<translate>

Remember to use the package uninstaller instead of individual subpackage uninstallers to avoid orphan extension entries in the extension manager.
</translate>

<translate>
=== Id= <file id="not_arbitrary"> === 
The id element in <file ..> tag are NOT arbitrary!. The "id=" should be set to the value of the "element" column in the "#__extensions" table. If they are not set correctly, upon uninstalling of the package the children ( <file> ) will NOT be found and uninstalled.
</translate>

<translate>
=== Manifest filename and packagename === 
The naming of the manifest file and the ability to uninstall the package file itself are closely related.
The manifest file must have a "pkg_" prefix, the remainder of the manifest name ( without .xml extension ) is to be used as <packagename>. Or, the other way around, a package you want to identify as "blurpblurp_J3" get that as its <packagename> and should be in a manifest file named "pkg_blurpblurp_J3.xml". Failure to do so will make it impossible to uninstall the package itself.</translate>

<translate>
An optional <pkg_script.php> which contains a class pkg_<packagename>InstallerScript with public function postflight can be used (works in Joomla! 3.6).</translate>

<translate>
=== Extension tag === 
</translate>
<translate>
As of Joomla! 3.4, you should include method="upgrade" in the <extension> tag if you wish for your package to succeed in updating itself on subsequent installations.</translate>

<translate>
The version attribute of the <extension> tag should be set to the minimum supported version of Joomla for this package. For example, if your package only supports Joomla! 3.2 and above set this to 3.2.</translate>

<translate>
=== Extension Uninstall Dependancy === 
</translate>
<translate>
As of 3.7.0, a package extension can declare that its child elements cannot be uninstalled independently with a "<blockChildUninstall>true</blockChildUninstall>" element in your package manifest. So if your package needs all it's extensions to operate effectively, set this to true or 1.
</translate>

<noinclude>
<translate>

[[Category:Extensions]]
</translate>
</noinclude>

J4.x:Creating a Simple Module

2019-06-21T07:07:43Z

Garkell: Changed to point to modules rather than plugin boilerplate

<noinclude><languages /></noinclude>
{{Joomla version|version=4.x|comment=><translate> Tutorial</translate>}}
{{-}}
{{Top portal heading|color=white-bkgd|icon=file-code-o|icon-color=#5091cd|size=5x|text-color=#333|title=<translate> Creating a Simple Module for Joomla 4.x</translate>}}
{{-}}

<translate> This is a tutorial on how to Create a simple module for Joomla Version 4x.</translate>
<translate>
== Introduction == 
</translate>
<translate> Joomlaǃ 4 provides five types of extensionsː</translate>
* '''[[S:MyLanguage/Component|<translate> Components</translate>]]'''<br /><translate> A component is the main part of the site. A component handles data manipulation as well as input and storage into the database. A component on most sites is the primary focus of the page.</translate>
* '''[[S:MyLanguage/Module|<translate> Modules</translate>]]''' <br /><translate> A module is an add-on to the site that extends the functionality. A module usually occupies a secondary portion of the web page and is not considered the primary focus of a page. It can be displayed on different positions and you can choose on which active menu items it should be displayed. Modules are lightweight and flexible extensions. They are used for small bits of the page that are generally less complex and are able to be seen across different components.</translate>
* '''[[S:MyLanguage/Plugin|<translate> Plugins</translate>]]'''<br /><translate> A Plugin manipulates output that is already generated by the system. It typically does not run as separate part of the site. It takes data from other sources (i.e. the content) and manipulates this data before displaying. A plugin typically work behind the scenes.</translate>
* '''[[S:MyLanguage/Languages|<translate> Languages</translate>]]'''<br />Probably the most basic extensions are languages. In essence the language package files consist of key/value pairs, which provide the translation of static text strings, assigned within the Joomla! source code.
* '''[[S:MyLanguage/Templates|<translate> Templates</translate>]]'''<br /><translate> A template is basically the design of your Joomla! powered website.</translate>

<translate> Joomla! 4 is constructed using five different applications:</translate>
<translate>
* Installation (used for installing Joomla and have to delete after installation)
* Administrator (backend - used for managing content)
* Public or site (frontend - used for displaying content)
* CLI (used for accessing Joomla on the command line and for cron jobs)
* API (web services - used for creating APIs for machine accessible content)</translate>
<translate>

The installation application is used once. The administrator and public are used through the concept of ''components'' with ''modules''. Each module has a single entry point located in the ''modules'' and accordingly ''administrator/modules'' directory. This entry point is called <tt>''mod_modulename/mod_modulename.php''</tt> (the ''mod_'' prefix is a historical trace). The entry point for the login module is for ''example /mod_login/mod_login.php''.</translate>

<translate>
=== Requirements === 
</translate>
<translate> You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)</translate>

<translate> You can download Joomla! 4 at [https://github.com/joomla/joomla-cms/tree/4.0-dev GitHub], on the [https://developer.joomla.org/nightly-builds.html Developer website] or you can create a free website at https://launch.joomla.org.</translate>

<translate>
== Creating a simple module/Developing a Basic Module - Part 1 == 
</translate>
<translate> You can see many examples of modules in the standard Joomla! install. For example:</translate>
<translate>
* Menus
* Latest News
* Login form
* and many more.</translate>

<translate> This tutorial will explain how to create a simple module. Through this tutorial you will learn the basic file structure of a Joomlaǃ 4 module. This basic structure can then be expanded to produce more elaborate modules.</translate>

<translate>
=== File Structure === 
</translate>
<translate> There are a few basic files that are used in the standard pattern of module development:</translate>
<translate> * <tt>mod_foo.php</tt> - This file is the main entry point for the module. It will perform any necessary initialization routines, call helper routines to collect any necessary data, and include the template which will display the module output.</translate>
<translate> * <tt>mod_foo.xml</tt> - This file contains information about the module. It defines the files that need to be installed by the Joomla! installer and specifies configuration parameters for the module.</translate>
<translate> * <tt>tmpl/default.php</tt> - This is the module template. This file will take the data collected by mod_foo.php and generate the HTML to be displayed on the page.</translate>
<translate> * <tt>language/en-GB/en-GB.mod_foo.ini</tt> and <tt>language/en-GB/en-GB.mod_foo.sys.ini</tt>- This are the files that provide the text in United Kingdom English.</translate>

<translate>
=== Creating mod_foo.php === 
</translate>
<translate> The <tt>mod_foo.php</tt> file will perform following tasks:</translate>
<translate> * Import the class <tt>ModuleHelper</tt> to the current scope. We need it later for displaying the output.</translate>
<translate> * Include the template to display the output.</translate>

<translate> The helper class is imported to our current scope at the begin of the file.</translate>

<source lang="php">use Joomla\CMS\Helper\ModuleHelper;</source>

<translate> Last we include the template to display the output via</translate>

<source lang="php">require ModuleHelper::getLayoutPath('mod_foo', $params->get('layout', 'default'));</source>

<translate>
==== Completed mod_foo.php file ==== 
</translate>
<translate> The complete <tt>mod_foo.php</tt> file is as follows:</translate>

<source lang="php">
<?php
/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/

use Joomla\CMS\Helper\ModuleHelper;

defined('_JEXEC') or die;

require ModuleHelper::getLayoutPath('mod_foo', $params->get('layout', 'default'));

</source>

<translate> ''Side note''ː In Joomla 3x you usually used a line like <tt>$moduleclass_sfx = htmlspecialchars($params->get('moduleclass_sfx'));</tt>. You don't need this anymore. See this PRː https://github.com/joomla/joomla-cms/pull/17447.</translate>

<translate> The one line that we haven’t explained so far is the first line <tt>defined('_JEXEC') or die;</tt>. This line checks to make sure that this file is being included from the Joomla application. This is necessary to prevent variable injection and other potential security concerns.</translate>

<translate>
=== Creating tmpl/default.php === 
</translate>
<translate> The <tt>default.php</tt> file is the template which displays the module output.</translate>

<translate>
==== Completed tmpl/default.php file ==== 
</translate>
<translate> The code for the tmpl/default.php file is as follows:</translate>

<source lang="php">
<?php
/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/

defined('_JEXEC') or die;

echo '[PROJECT_NAME]';

</source>

<translate> An important point to note is that the template file has the same scope as the <tt>mod_foo.php</tt> file. It means that a variable can be defined in the <tt>mod_foo.php</tt> file and then used in the template file without any extra declarations or function calls.</translate>

<translate>
=== Creating mod_foo.xml === 
</translate>
<translate> The <tt>mod_foo.xml</tt> file is the installation file. Most entries are self-explanatory.</translate>

<translate>
==== Completed mod_foo.xml file ==== 
</translate>
<translate> The code for the <tt>mod_foo.xml</tt> file is as follows:</translate>

<source lang="xml">

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.8" client="site" method="upgrade">
<name>MOD_FOO</name>
<creationDate>[DATE]</creationDate>
<author>[AUTHOR]</author>
<authorEmail>[AUTHOR_EMAIL]</authorEmail>
<authorUrl>[AUTHOR_URL]</authorUrl>
<copyright>[COPYRIGHT]</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<version>1.0</version>
<description>MOD_FOO_XML_DESCRIPTION</description>

<files>
<filename module="mod_foo">mod_foo.php</filename>
<folder>tmpl</folder>
<folder>language</folder>
<filename>mod_foo.xml</filename>
</files>

</extension>

</source>

<translate>
=== Creating the language files === 
</translate>
<translate> The files <tt>language/en-GB/en-GB.mod̠foo.ini</tt> and <tt>language/en-GB/en-GB.mod̠foo.sys.ini</tt> are used to translate text in the frontend and in the backend.</translate>

<translate> The code for <tt>language/en-GB/en-GB.mod̠foo.sys.ini</tt> is as follows:</translate>

<source lang="xml">

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"

</source>

<source lang="xml">

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"

</source>

<translate> The <tt>.sys.ini</tt> file is used to translate the description of the extension upon installation, where as the <tt>.ini</tt> file is used to translate the remaining strings and the description when viewing your extension.</translate>

<translate> More information about language files can be found [[S:MyLanguage/Specification_of_language_files|here]].</translate>

<translate>
== Test your module == 
</translate>
<translate> Now you can zip all files and install them via the Joomla Extension Manager.<br /></translate>
<translate> After that you can choose your module in the module manager, when you create a new site module.</translate>
{{-}}
[[File:moduletutorial1-<translate> en</translate>.png|700px|center]]
{{-}}
[[File:moduletutorial2-<translate> en</translate>.png|700px|center]]

<translate> In the frontend, you will see your module like displayed in the next image.</translate>
{{-}}
[[File:moduletutorial3-<translate> en</translate>.png|700px|center]]

<translate>
== Conclusion == 
</translate>
<translate> Module development for Joomla is a fairly simple, straightforward process. Using the techniques described in this tutorial, an endless variety of modules can be developed with little hassle.</translate>

<translate> You can find boilerplates hereː</translate>
* https://github.com/joomla-extensions/boilerplate/tree/master/module
<translate> The sample files for this Tutorial can be found hereː</translate>
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

<translate>

== Add a helper class using namespaces - Part 2== 
</translate>

<translate>
=== Requirements === 
</translate>
<translate> You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)</translate>

<translate>
== Namespaces == 
</translate>
<translate> With PHP 5.3, the namespaces came into their own. In other programming languages for a long time in use, these small structures now also help us with the clarity of our code.</translate>

<translate> Namespaces are separate areas in which certain logical things (in our case, classes, interfaces, functions, and constants) can live. These areas provide ncapsulation of the code and prevent name conflicts.</translate>

<translate> Let's take a look how to use them in Joomla 4. We use the helper file for this.</translate>

<translate>
=== File Structure === 
</translate>
<translate> We will create/change the following files:</translate>
<translate>
* <code>Helper/FooHelper.php</code> - This is the file we use here as an example. We have to create it.
* <code>mod_foo.php</code> - In this file we will mainly load the namespace.
* <code>tmpl/default.php</code> - In this file demonstrate how the data of a helper can be displayed.
* <code>mod_foo.xml</code> - We create a new directory with a new file. This must be installed during the installation. For this we have to specify them in this file.</translate>

<translate>
=== Creating Helper/FooHelper.php === 
</translate>
<translate> Our new helper class should belong to a namespace. We achieve this with the following code. It is important, that this line is at the beginning of the file.</translate>

<source lang="php">namespace Joomla\Module\Foo\Site\Helper;</source>

<translate> Then we create a simple class with a simple method. Of course you can do a lot more here. Take a look at the Joomla core methods. Here are many examples. They show you first-hand what options you have.</translate>

<translate>
==== Completed Helper/FooHelper.php ==== 
</translate>
<translate> The complete <tt>mod_foo.php</tt> file is as follows:</translate>

<source lang="php">

<?php
/**
* @package Joomla.Site
* @subpackage mod_foo
*
* @copyright Copyright (C) 2005 - 2018 Open Source Matters, Inc. All rights reserved.
* @license GNU General Public License version 2 or later; see LICENSE.txt
*/

namespace Joomla\Module\Foo\Site\Helper;

defined('_JEXEC') or die;

/**
* Helper for mod_foo
*
* @since 4.0
*/
class FooHelper
{
/**
* Retrieve foo test
*
* @param Registry $params The module parameters
* @param CMSApplication $app The application
*
* @return array
*/
public static function getText()
{
return 'FooHelpertest';
}
}

</source>

<translate>

=== Editing mod_foo.php === 
</translate>
<translate> Our new helper class is imported to our current scope at the begin of the file.</translate>

<source lang="php">use Joomla\Module\Foo\Site\Helper\FooHelper;</source>

<translate> Last use the helper file for testing if it is loaded correctlyː</translate>

<source lang="php">$test = FooHelper::getText($params, $app);</source>

<translate>
==== Completed mod_foo.php file ==== 
</translate>
<translate> The complete <tt>mod_foo.php</tt> file is as follows:</translate>

<source lang="php">

<?php
/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/

defined('_JEXEC') or die;

use Joomla\CMS\Helper\ModuleHelper;
use Joomla\Module\Foo\Site\Helper\FooHelper;

$test = FooHelper::getText();

require ModuleHelper::getLayoutPath('mod_foo', $params->get('layout', 'default'));

</source>

<translate>
=== Editing tmpl/default.php === 
</translate>
<translate> In this file you make only a small change to demonstrate in the frontend that your helper file is working properly. You only add the value of the variable at the end of the current output.</translate>

<source lang="php"><?php echo '[PROJECT_NAME]' . $test;</source>

<translate>
==== Completed tmpl/default.php ==== 
</translate>
<translate> The complete <tt>tmpl/default.php</tt> file is as follows:</translate>

<source lang="php">

<?php
/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/

defined('_JEXEC') or die;

?>

<?php echo '[PROJECT_NAME]' . $test;

</source>

<translate>
=== Editing mod_foo.xml === 
</translate>
<translate> First you have to add a line, so that the namespace is set automatically in Joomla. After this change, you have to re-install your module. A simple change in an already installed module is not enough. If you are doing local development you can also delete the files libraries/autoload_psr4.php and it will automatically be re-created. After inserting and installing, the namespace is known by the loader <tt>JPATH_LIBRARIES . '/autoload_psr4.php'</tt>.</translate>

<source lang="xml"><namespace>Joomla\Module\Foo</namespace></source>

<translate> Joomla! should copy your helper file when installing the module. So Joomla! needs to know your helper file. For this, you need to add the following line to your XML file.</translate>

<source lang="xml"><folder>Helper</folder></source>

<translate>
==== Completed mod_foo.xml ==== 
</translate>
<translate> The complete <tt>mod_foo.xml</tt> file is as follows:</translate>

<source lang="xml">

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.8" client="site" method="upgrade">
<name>MOD_FOO</name>
<creationDate>[DATE]</creationDate>
<author>[AUTHOR]</author>
<authorEmail>[AUTHOR_EMAIL]</authorEmail>
<authorUrl>[AUTHOR_URL]</authorUrl>
<copyright>[COPYRIGHT]</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<version>1.0</version>
<description>MOD_FOO_XML_DESCRIPTION</description>
<namespace>Joomla\Module\Foo</namespace>
<files>
<filename module="mod_foo">mod_foo.php</filename>
<folder>tmpl</folder>
<folder>Helper</folder>
<folder>language</folder>
<filename>mod_foo.xml</filename>
</files>

</extension>

</source>

<translate>
== Test your module == 
</translate>
<translate> Now you can zip all files and install them via the Joomla Extension Manager.</translate>
<translate> After that you can choose your module in the module manager, when you create a new site module.</translate>

<translate> In the frontend you will see your module like displayed in the next image. The text form your helper file is displayed.</translate>
{{-}}
[[File:moduletutorial23-<translate> en</translate>.png|700px|center]]

<translate>
== Conclusion == 
</translate>
<translate> As you can see, once you get a bit into the namespaces, they are not that complicated anymore. In big projects they can bring a lot of benefits. However, we should plan namespaces, as otherwise it will soon be more time-consuming.</translate>

<translate> You can find boilerplates hereː</translate>
* https://github.com/joomla-extensions/boilerplate/tree/master/module
<translate> The sample files for this Tutorial can be found hereː</translate>
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

<translate>

== Customizationː Add parameters via form fields - Part 3 == 
</translate>

<translate>
=== Requirements === 
</translate>
<translate> You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)</translate>

<translate>
== Customization with form fields and parameters == 
</translate>
<translate> Form fields give a great deal of customization in Joomla and for modules are the sole way of allowing the user to tweak the module to the needs of their site.</translate>

<translate> In this case we are going to extend our previous example using a url field for inserting a domain that we can use as link in the front end. To allow this to happen we will use the [[S:MyLanguage/URL_form_field_type|URL Form Field]] type.</translate>

<translate> After that, we insert parameters that allow to use standard functionality of Joomla.</translate>

<translate> Let's take a look on how to use them in Joomla 4.</translate>

<translate>
=== File Structure === 
</translate>
<translate> We will change the following files:</translate>
<translate>
* <tt>mod_foo.xml</tt> - This is the file where we add the fields.
* <tt>tmpl/default.php</tt> - In this file demonstrate how the data of a field can be used.
* <tt>language/en-GB/en-GB.mod_foo.ini</tt> - Here we use a language string so that the field can be labeled correctly in different languages.</translate>

<translate>
=== Editing mod_foo.xml === 
</translate>
<translate> First we set a custom parameter.</translate>

<source lang="xml">

<field
name="domain"
type="url"
label="MOD_FOO_FIELD_URL_LABEL"
filter="url"
/>

</source>

<translate> Then we insert Joomla default fields, so that we can use cache, moduleclass-suffix and layouts.</translate>

<source lang="xml">
<field
name="layout"
type="modulelayout"
label="JFIELD_ALT_LAYOUT_LABEL"
class="custom-select"
/>

<field
name="moduleclass_sfx"
type="textarea"
label="COM_MODULES_FIELD_MODULECLASS_SFX_LABEL"
rows="3"
/>

<field
name="cache"
type="list"
label="COM_MODULES_FIELD_CACHING_LABEL"
default="0"
>
<option value="1">JGLOBAL_USE_GLOBAL</option>
<option value="0">COM_MODULES_FIELD_VALUE_NOCACHING</option>
</field>

<field
name="cache_time"
type="number"
label="COM_MODULES_FIELD_CACHE_TIME_LABEL"
default="0"
/>

<field
name="cachemode"
type="hidden"
default="itemid"
>
<option value="itemid"></option>
</field>

</source>

<translate>
==== Completed mod_foo.xml ==== 
</translate>
<translate> The complete <tt>mod_foo.xml</tt> file is as follows:</translate>

<source lang="xml">

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.8" client="site" method="upgrade">
<name>MOD_FOO</name>
<creationDate>[DATE]</creationDate>
<author>[AUTHOR]</author>
<authorEmail>[AUTHOR_EMAIL]</authorEmail>
<authorUrl>[AUTHOR_URL]</authorUrl>
<copyright>[COPYRIGHT]</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<version>1.0</version>
<description>MOD_FOO_XML_DESCRIPTION</description>
<namespace>Joomla\Module\Foo</namespace>
<files>
<filename module="mod_foo">mod_foo.php</filename>
<folder>tmpl</folder>
<folder>Helper</folder>
<folder>language</folder>
<filename>mod_foo.xml</filename>
</files>
<config>
<fields name="params">
<fieldset name="basic">
<field
name="domain"
type="url"
label="MOD_FOO_FIELD_URL_LABEL"
filter="url"
/>
</fieldset>
<fieldset name="advanced">
<field
name="layout"
type="modulelayout"
label="JFIELD_ALT_LAYOUT_LABEL"
class="custom-select"
/>

<field
name="moduleclass_sfx"
type="textarea"
label="COM_MODULES_FIELD_MODULECLASS_SFX_LABEL"
rows="3"
/>

<field
name="cache"
type="list"
label="COM_MODULES_FIELD_CACHING_LABEL"
default="0"
>
<option value="1">JGLOBAL_USE_GLOBAL</option>
<option value="0">COM_MODULES_FIELD_VALUE_NOCACHING</option>
</field>

<field
name="cache_time"
type="number"
label="COM_MODULES_FIELD_CACHE_TIME_LABEL"
default="0"
/>

<field
name="cachemode"
type="hidden"
default="itemid"
>
<option value="itemid"></option>
</field>
</fieldset>
</fields>
</config>
</extension>

</source>

<translate>
=== Editing tmpl/default.php === 
</translate>
<translate> We can use the value of the parameter for creating an hyperlink in the frontend. We can access the value via the variable via the variable $params.</translate>

<source lang="php">$domain = $params->get('domain', 'https://www.joomla.org');</source>

<translate> Later we set use this value for creating the hyperlink.</translate>

<source lang="php">

<a href="<?php echo $domain; ?>">
<?php echo '[PROJECT_NAME]' . $test; ?>
</a>

</source>

<translate>
==== Completed tmpl/default.php file ==== 
</translate>
<translate> The complete <tt>tmpl/default.php</tt> file is as follows:</translate>

<source lang="php">

<?php
/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/

defined('_JEXEC') or die;

$domain = $params->get('domain', 'https://www.joomla.org');
?>

<a href="<?php echo $domain; ?>">
<?php echo '[PROJECT_NAME]' . $test; ?>
</a>

</source>

<translate>
=== Editing language/en-GB/en-GB.mod_foo.ini === 
</translate>
<translate> Here we can specify the text for the English version of the field label.</translate>

<source lang="php">MOD_FOO_FIELD_URL_LABEL="Url"</source>

<translate>
==== Completed language/en-GB/en-GB.mod_foo.ini ==== 
</translate>
<translate> The complete <tt>language/en-GB/en-GB.mod_foo.ini</tt> file is as follows:</translate>

<source lang="php">

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"
MOD_FOO_FIELD_URL_LABEL="Url"

</source>

<translate>
== Test your module == 
</translate>
<translate> Now you can zip all files and install them via the Joomla Extension Manager.</translate>
<translate> After that you can choose your module in the module manager, when you create a new site module.</translate>

<translate> In the backend, you will see your module like displayed in the next image.</translate>

<translate> In the basic tab, you will see the custom field where you can insert a domain. The text for the label is fetched from the language file.</translate>
{{-}}
[[File:moduletutorial31-<translate> en</translate>.png|700px|center]]

<translate> In the advanced tab, you will see all default options except the cache mode because of this is a hidden field.</translate>
{{-}}
[[File:moduletutorial32-<translate> en</translate>.png|700px|center]]

<translate> In the frontend, you will see your module like displayed in the next image. The text form your helper file is displayed and you should see a hyperlink.</translate>
{{-}}
[[File:moduletutorial33-<translate> en</translate>.png|700px|center]]

<translate>
== Conclusion == 
</translate>
<translate> Form fields give the user an easy way to customize the module to their sites settings. This allows the modules scope to be increased.</translate>

<translate> You can find boilerplates hereː</translate>
* https://github.com/joomla-extensions/boilerplate/tree/master/module
<translate> The sample files for this Tutorial can be found hereː</translate>
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules
<translate> See this issue for possible future changes:</translate>
* https://github.com/joomla/joomla-cms/pull/23553

<translate>

== Use Install, Update and Uninstall script - Part 4 == 
</translate>

<translate>
=== Requirements === 
</translate>
<translate> You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)</translate>

<translate>
=== Scripts === 
</translate>
<translate> Installing, updating and uninstalling a module may require additional operations that cannot be achieved by the basic operations described in the main XML file. Joomla offers a new approach to solve this problem. It consists in using a PHP script file containing a class using five methods:</translate>
<translate>
* preflight which is executed before install and update
* install
* update
* uninstall
* postflight which is executed after install and update</translate>

<translate> Let's take a look how to use them in Joomla 4. We use the helper file for this.</translate>

<translate>
=== File Structure === 
</translate>
<translate> We will create/change the following files:</translate>
<translate>
* <tt>script.php</tt> - This is the file we use here as an example. We have to create it.
* <tt>language/en-GB/en-GB.mod_foo.sys.ini</tt> - In this file we will add text.
* <tt>mod_foo.xml</tt> - We create a new file. This must be installed during the installation. For this we have to specify it in this file.</translate>

<translate>
=== Creating script.php === 
</translate>
<translate> Writing an extension script consists in declaring a class whose name is <tt>mod_ModuleNameInstallerScripʈ</tt> with these 5 methods. See the comments in the file for more information. In this comments I explain when a method is called.</translate>

<translate> In this example, I only use text to show when which method will be executed. In addition, I show you how to check the minimum requirements. Of course you can do much more. For example, you can delete files that are no longer needed in a new version of your module. This can be seen in the file. Another idea for this file is to create sample content, to show a success message with the current installed version number or you can redirect after a successful installation to the page with the module settings.</translate>

<translate>
==== Completed script.php ==== 
</translate>
<translate> The complete <tt>script.php</tt> file is as follows:</translate>

<source lang="php">

<?php

/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/
// No direct access to this file
defined('_JEXEC') or die;

use Joomla\CMS\Language\Text;
use Joomla\CMS\Log\Log;

/**
* Script file of Foo module
*/
class mod_fooInstallerScript {

/**
* Extension script constructor.
*
* @return void
*/
public function __construct() {
$this->minimumJoomla = '4.0';
$this->minimumPhp = JOOMLA_MINIMUM_PHP;
}

/**
* Method to install the extension
*
* @param InstallerAdapter $parent The class calling this method
*
* @return boolean True on success
*/
function install($parent) {
echo Text::_('MOD_FOO_INSTALLERSCRIPT_UNINSTALL');

return true;
}

/**
* Method to uninstall the extension
*
* @param InstallerAdapter $parent The class calling this method
*
* @return boolean True on success
*/
function uninstall($parent) {
echo Text::_('MOD_FOO_INSTALLERSCRIPT_UNINSTALL');

return true;
}

/**
* Method to update the extension
*
* @param InstallerAdapter $parent The class calling this method
*
* @return boolean True on success
*/
function update($parent) {
echo Text::_('MOD_FOO_INSTALLERSCRIPT_UPDATE');

return true;
}

/**
* Function called before extension installation/update/removal procedure commences
*
* @param string $type The type of change (install, update or discover_install, not uninstall)
* @param InstallerAdapter $parent The class calling this method
*
* @return boolean True on success
*/
function preflight($type, $parent) {
// Check for the minimum PHP version before continuing
if (!empty($this->minimumPhp) && version_compare(PHP_VERSION, $this->minimumPhp, '<')) {
Log::add(Text::sprintf('JLIB_INSTALLER_MINIMUM_PHP', $this->minimumPhp), Log::WARNING, 'jerror');

return false;
}

// Check for the minimum Joomla version before continuing
if (!empty($this->minimumJoomla) && version_compare(JVERSION, $this->minimumJoomla, '<')) {
Log::add(Text::sprintf('JLIB_INSTALLER_MINIMUM_JOOMLA', $this->minimumJoomla), Log::WARNING, 'jerror');

return false;
}

echo Text::_('MOD_FOO_INSTALLERSCRIPT_PREFLIGHT');
echo $this->minimumJoomla . ' ' . $this->minimumPhp;

return true;
}

/**
* Function called after extension installation/update/removal procedure commences
*
* @param string $type The type of change (install, update or discover_install, not uninstall)
* @param InstallerAdapter $parent The class calling this method
*
* @return boolean True on success
*/
function postflight($type, $parent) {
echo Text::_('MOD_FOO_INSTALLERSCRIPT_POSTFLIGHT');

return true;
}

}

</source>

<translate>
=== Editing language/en-GB/en-GB.mod_foo.sys.ini === 
</translate>
<translate> There is not much to explain here. Write the text for the translation into this file.</translate>

<translate>
==== Completed language/en-GB/en-GB.mod_foo.sys.ini file ==== 
</translate>
<translate> The complete <tt>language/en-GB/en-GB.mod_foo.sys.ini</tt> file is as follows:</translate>

<source lang="php">

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"
MOD_FOO_INSTALLERSCRIPT_PREFLIGHT="<p>Anything here happens before the installation/update/uninstallation of the module</p>"
MOD_FOO_INSTALLERSCRIPT_UPDATE="<p>The module has been updated</p>"
MOD_FOO_INSTALLERSCRIPT_UNINSTALL="<p>The module has been uninstalled</p>"
MOD_FOO_INSTALLERSCRIPT_INSTALL="<p>The module has been installed</p>"
MOD_FOO_INSTALLERSCRIPT_POSTFLIGHT="<p>Anything here happens after the installation/update/uninstallation of the module</p>"

</source>

<translate>
=== Editing mod_foo.xml === 
</translate>
<translate> You have to add a line, so that the script is called automatically in Joomla.</translate>

<source lang="xml"><scriptfile>script.php</scriptfile></source>

<translate>
==== Completed mod_foo.xml ==== 
</translate>
<translate> The complete <tt>mod_foo.xml</tt> file is as follows:</translate>

<source lang="xml">

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="4.0" client="site" method="upgrade">
<name>MOD_FOO</name>
<creationDate>[DATE]</creationDate>
<author>[AUTHOR]</author>
<authorEmail>[AUTHOR_EMAIL]</authorEmail>
<authorUrl>[AUTHOR_URL]</authorUrl>
<copyright>[COPYRIGHT]</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<version>1.0</version>
<description>MOD_FOO_XML_DESCRIPTION</description>
<namespace>Joomla\Module\Foo</namespace>
<scriptfile>script.php</scriptfile>
<files>
<filename module="mod_foo">mod_foo.php</filename>
<folder>tmpl</folder>
<folder>Helper</folder>
<folder>language</folder>
<filename>mod_foo.xml</filename>
</files>
<config>
<fields name="params">
<fieldset name="basic">
<field
name="domain"
type="url"
label="MOD_FOO_FIELD_URL_LABEL"
filter="url"
/>
</fieldset>
<fieldset name="advanced">
<field
name="layout"
type="modulelayout"
label="JFIELD_ALT_LAYOUT_LABEL"
class="custom-select"
/>

<field
name="moduleclass_sfx"
type="textarea"
label="COM_MODULES_FIELD_MODULECLASS_SFX_LABEL"
rows="3"
/>

<field
name="cache"
type="list"
label="COM_MODULES_FIELD_CACHING_LABEL"
default="0"
>
<option value="1">JGLOBAL_USE_GLOBAL</option>
<option value="0">COM_MODULES_FIELD_VALUE_NOCACHING</option>
</field>

<field
name="cache_time"
type="number"
label="COM_MODULES_FIELD_CACHE_TIME_LABEL"
default="0"
/>

<field
name="cachemode"
type="hidden"
default="itemid"
>
<option value="itemid"></option>
</field>
</fieldset>
</fields>
</config>
</extension>
</source>

<translate>
== Test your module == 
</translate>
<translate> Now you can zip all files and install them via the Joomla Extension Manager.</translate>
<translate> Immediately after the installation, you will see the following information. This you had entered in the script so.</translate>
{{-}}
[[File:moduletutorial14-<translate> en</translate>.png|700px|center]]

<translate>
== Conclusion == 
</translate>
<translate> As you can see, Joomla offers you a lot to make your extension easy to use - right from the start.</translate>

<translate> You can find boilerplates hereː</translate>
* https://github.com/joomla-extensions/boilerplate/tree/master/module
<translate> The sample files for this Tutorial can be found hereː</translate>
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

<translate>

== Use Joomla Updaterː Adding Auto Update - Part 5 == 
</translate>

<translate>
=== Requirements === 
</translate>
<translate> You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)</translate>

<translate>
=== Joomla Updater === 
</translate>
<translate> The first thing to do is to read the [[S:MyLanguage/J2.5:Managing_Component_Updates|Managing Component Upgrades with Joomla 2.5 - Part 1]] tutorial to give an idea of how the upgrade process works in Joomla. Whilst written for 2.5 the process hasn't changed. Also read [[S:MyLanguage/Deploying_an_Update_Server|Deploying an update server]] - this is what we'll be implementing in this tutorial.</translate>

<translate>
=== File Structure === 
</translate>
<translate> We will create/change the following files:</translate>
<translate> * <tt>mod_foo.xml</tt> - The only way to update our existing module is to add in a update server - for example <tt><nowiki>http://www.example.com/foo_update.xmɭ</nowiki></tt> - into the xml file.</translate>
<translate> * <tt>foo_update.xml</tt> - Then we have to create the XML file for the update server at <tt><nowiki>http://www.example.com/foo_update.xmɭ</nowiki></tt> to let Joomla know an update is available.</translate>

<translate>
==== Editing mod_foo.xml ==== 
</translate>
<translate> To add our update server, we need to insert the following lines in your XML-File</translate>

<source lang="php">

<updateservers>
<server type="extension" priority="1" name="[PROJECT_NAME]">https://www.example.com/mod_foo.xml</server>
</updateservers>

</source>

<translate>
==== Completed mod_foo.xml ==== 
</translate>
<translate> The complete <tt>mod_foo.xml</tt> file is as follows:</translate>

<source lang="xml">

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="4.0" client="site" method="upgrade">
<name>MOD_FOO</name>
<creationDate>[DATE]</creationDate>
<author>[AUTHOR]</author>
<authorEmail>[AUTHOR_EMAIL]</authorEmail>
<authorUrl>[AUTHOR_URL]</authorUrl>
<copyright>[COPYRIGHT]</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<version>1.0</version>
<description>MOD_FOO_XML_DESCRIPTION</description>
<namespace>Joomla\Module\Foo</namespace>
<files>
<filename module="mod_foo">mod_foo.php</filename>
<folder>tmpl</folder>
<folder>Helper</folder>
<folder>language</folder>
<filename>mod_foo.xml</filename>
</files>
<updateservers>
<server type="extension" priority="1" name="[PROJECT_NAME]">https://www.example.com/mod_foo.xml</server>
</updateservers>
<config>
<fields name="params">
<fieldset name="basic">
<field
name="domain"
type="url"
label="MOD_FOO_FIELD_URL_LABEL"
filter="url"
/>
</fieldset>
<fieldset name="advanced">
<field
name="layout"
type="modulelayout"
label="JFIELD_ALT_LAYOUT_LABEL"
class="custom-select"
/>

<field
name="moduleclass_sfx"
type="textarea"
label="COM_MODULES_FIELD_MODULECLASS_SFX_LABEL"
rows="3"
/>

<field
name="cache"
type="list"
label="COM_MODULES_FIELD_CACHING_LABEL"
default="0"
>
<option value="1">JGLOBAL_USE_GLOBAL</option>
<option value="0">COM_MODULES_FIELD_VALUE_NOCACHING</option>
</field>

<field
name="cache_time"
type="number"
label="COM_MODULES_FIELD_CACHE_TIME_LABEL"
default="0"
/>

<field
name="cachemode"
type="hidden"
default="itemid"
>
<option value="itemid"></option>
</field>
</fieldset>
</fields>
</config>
</extension>

</source>

<translate> So now that Joomla is searching for updates to our extension - let's create one to test out our process. But first we need to create the file <tt>foo_update.xml</tt>. So far we have only described the update server. We do not know yet if there is an update. In the file <tt>foo_update.xml</tt> we indicate when a new version is published and where it can be downloaded.</translate>

<translate>
=== Creating foo_update.xml === 
</translate>
<translate> Now we have to create the XML file at <tt><nowiki>http://www.example.com/foo_update.xml</nowiki></tt> to let Joomla know an update is available.</translate>

<translate>
==== Completed foo_update.xml ==== 
</translate>
<translate> The complete <tt>foo_update.xml</tt> file is as follows:</translate>

<source lang="xml">

<?xml version="1.0" ?>

<updates>
<update>
<name>Foo</name>
<description>This is mod_foo 1.0.1</description>
<element>mod_foo</element>
<type>module</type>
<version>1.0.1</version>
<downloads>
<downloadurl type="full" format="zip">http://www.example.com/mod_foo_101.zip</downloadurl>
</downloads>
<maintainer>Joomla</maintainer>
<maintainerurl>http://www.example.com</maintainerurl>
<targetplatform name="joomla" version="4.0"/>
<client>site</client>
</update>
</updates>

</source>

<translate> After uploading this file to the address <tt><nowiki>https://www.example.com/mod_foo.xml</nowiki></tt> the update will be displayed in the Joomla backend.</translate>

<translate>
=== Test your module update === 
</translate>
<translate> Create a copy of the module as it is now. Then let's update the version number to 1.0.1. Now you can zip all files. After that you should load your zip to the URL <tt><nowiki>http://www.example.com/mod_foo_101.zip</nowiki></tt>. Now you can update your module via the Joomla Updater.</translate>

<translate>
=== Commercial Modules === 
</translate>
<translate> Note that in our files we have linked to the extensions updates xml file. And from that xml file we have a location for the zip of the module. This means that if someone was to track this backwards they could find the physical source of your modules zip file. If you don't do like this, you can find a solution in this PRː https://github.com/joomla/joomla-cms/pull/15185 .</translate>

<translate>
=== Conclusion === 
</translate>
<translate> With the Joomla updater, you can easily reach all users and tell them that there is a new version. Even the update itself is easy.</translate>

<translate> Each extension should use an update server. Especially for security reasons.</translate>

<translate> You can find boilerplates hereː</translate>
* https://github.com/joomla-extensions/boilerplate/tree/master/module
<translate> The sample files for this Tutorial can be found hereː</translate>
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

<noinclude>
[[Category:Beginner Development{{#translation:}}]]
[[Category:Tutorials{{#translation:}}]]
[[Category:Tutorials in a Series{{#translation:}}]]
[[Category:Development{{#translation:}}]]
[[Category:Module Development{{#translation:}}]]
[[Category:Joomla! 4.x{{#translation:}}]]
[[Category:Joomla! 4.0{{#translation:}}]]
</noinclude>

J4.x:Creating a Simple Module

2019-06-21T07:05:24Z

Garkell: Changed to point to modules rather than plugin boilerplate

<noinclude><languages /></noinclude>
{{Joomla version|version=4.x|comment=><translate> Tutorial</translate>}}
{{-}}
{{Top portal heading|color=white-bkgd|icon=file-code-o|icon-color=#5091cd|size=5x|text-color=#333|title=<translate> Creating a Simple Module for Joomla 4.x</translate>}}
{{-}}

<translate> This is a tutorial on how to Create a simple module for Joomla Version 4x.</translate>
<translate>
== Introduction == 
</translate>
<translate> Joomlaǃ 4 provides five types of extensionsː</translate>
* '''[[S:MyLanguage/Component|<translate> Components</translate>]]'''<br /><translate> A component is the main part of the site. A component handles data manipulation as well as input and storage into the database. A component on most sites is the primary focus of the page.</translate>
* '''[[S:MyLanguage/Module|<translate> Modules</translate>]]''' <br /><translate> A module is an add-on to the site that extends the functionality. A module usually occupies a secondary portion of the web page and is not considered the primary focus of a page. It can be displayed on different positions and you can choose on which active menu items it should be displayed. Modules are lightweight and flexible extensions. They are used for small bits of the page that are generally less complex and are able to be seen across different components.</translate>
* '''[[S:MyLanguage/Plugin|<translate> Plugins</translate>]]'''<br /><translate> A Plugin manipulates output that is already generated by the system. It typically does not run as separate part of the site. It takes data from other sources (i.e. the content) and manipulates this data before displaying. A plugin typically work behind the scenes.</translate>
* '''[[S:MyLanguage/Languages|<translate> Languages</translate>]]'''<br />Probably the most basic extensions are languages. In essence the language package files consist of key/value pairs, which provide the translation of static text strings, assigned within the Joomla! source code.
* '''[[S:MyLanguage/Templates|<translate> Templates</translate>]]'''<br /><translate> A template is basically the design of your Joomla! powered website.</translate>

<translate> Joomla! 4 is constructed using five different applications:</translate>
<translate>
* Installation (used for installing Joomla and have to delete after installation)
* Administrator (backend - used for managing content)
* Public or site (frontend - used for displaying content)
* CLI (used for accessing Joomla on the command line and for cron jobs)
* API (web services - used for creating APIs for machine accessible content)</translate>
<translate>

The installation application is used once. The administrator and public are used through the concept of ''components'' with ''modules''. Each module has a single entry point located in the ''modules'' and accordingly ''administrator/modules'' directory. This entry point is called <tt>''mod_modulename/mod_modulename.php''</tt> (the ''mod_'' prefix is a historical trace). The entry point for the login module is for ''example /mod_login/mod_login.php''.</translate>

<translate>
=== Requirements === 
</translate>
<translate> You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)</translate>

<translate> You can download Joomla! 4 at [https://github.com/joomla/joomla-cms/tree/4.0-dev GitHub], on the [https://developer.joomla.org/nightly-builds.html Developer website] or you can create a free website at https://launch.joomla.org.</translate>

<translate>
== Creating a simple module/Developing a Basic Module - Part 1 == 
</translate>
<translate> You can see many examples of modules in the standard Joomla! install. For example:</translate>
<translate>
* Menus
* Latest News
* Login form
* and many more.</translate>

<translate> This tutorial will explain how to create a simple module. Through this tutorial you will learn the basic file structure of a Joomlaǃ 4 module. This basic structure can then be expanded to produce more elaborate modules.</translate>

<translate>
=== File Structure === 
</translate>
<translate> There are a few basic files that are used in the standard pattern of module development:</translate>
<translate> * <tt>mod_foo.php</tt> - This file is the main entry point for the module. It will perform any necessary initialization routines, call helper routines to collect any necessary data, and include the template which will display the module output.</translate>
<translate> * <tt>mod_foo.xml</tt> - This file contains information about the module. It defines the files that need to be installed by the Joomla! installer and specifies configuration parameters for the module.</translate>
<translate> * <tt>tmpl/default.php</tt> - This is the module template. This file will take the data collected by mod_foo.php and generate the HTML to be displayed on the page.</translate>
<translate> * <tt>language/en-GB/en-GB.mod_foo.ini</tt> and <tt>language/en-GB/en-GB.mod_foo.sys.ini</tt>- This are the files that provide the text in United Kingdom English.</translate>

<translate>
=== Creating mod_foo.php === 
</translate>
<translate> The <tt>mod_foo.php</tt> file will perform following tasks:</translate>
<translate> * Import the class <tt>ModuleHelper</tt> to the current scope. We need it later for displaying the output.</translate>
<translate> * Include the template to display the output.</translate>

<translate> The helper class is imported to our current scope at the begin of the file.</translate>

<source lang="php">use Joomla\CMS\Helper\ModuleHelper;</source>

<translate> Last we include the template to display the output via</translate>

<source lang="php">require ModuleHelper::getLayoutPath('mod_foo', $params->get('layout', 'default'));</source>

<translate>
==== Completed mod_foo.php file ==== 
</translate>
<translate> The complete <tt>mod_foo.php</tt> file is as follows:</translate>

<source lang="php">
<?php
/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/

use Joomla\CMS\Helper\ModuleHelper;

defined('_JEXEC') or die;

require ModuleHelper::getLayoutPath('mod_foo', $params->get('layout', 'default'));

</source>

<translate> ''Side note''ː In Joomla 3x you usually used a line like <tt>$moduleclass_sfx = htmlspecialchars($params->get('moduleclass_sfx'));</tt>. You don't need this anymore. See this PRː https://github.com/joomla/joomla-cms/pull/17447.</translate>

<translate> The one line that we haven’t explained so far is the first line <tt>defined('_JEXEC') or die;</tt>. This line checks to make sure that this file is being included from the Joomla application. This is necessary to prevent variable injection and other potential security concerns.</translate>

<translate>
=== Creating tmpl/default.php === 
</translate>
<translate> The <tt>default.php</tt> file is the template which displays the module output.</translate>

<translate>
==== Completed tmpl/default.php file ==== 
</translate>
<translate> The code for the tmpl/default.php file is as follows:</translate>

<source lang="php">
<?php
/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/

defined('_JEXEC') or die;

echo '[PROJECT_NAME]';

</source>

<translate> An important point to note is that the template file has the same scope as the <tt>mod_foo.php</tt> file. It means that a variable can be defined in the <tt>mod_foo.php</tt> file and then used in the template file without any extra declarations or function calls.</translate>

<translate>
=== Creating mod_foo.xml === 
</translate>
<translate> The <tt>mod_foo.xml</tt> file is the installation file. Most entries are self-explanatory.</translate>

<translate>
==== Completed mod_foo.xml file ==== 
</translate>
<translate> The code for the <tt>mod_foo.xml</tt> file is as follows:</translate>

<source lang="xml">

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.8" client="site" method="upgrade">
<name>MOD_FOO</name>
<creationDate>[DATE]</creationDate>
<author>[AUTHOR]</author>
<authorEmail>[AUTHOR_EMAIL]</authorEmail>
<authorUrl>[AUTHOR_URL]</authorUrl>
<copyright>[COPYRIGHT]</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<version>1.0</version>
<description>MOD_FOO_XML_DESCRIPTION</description>

<files>
<filename module="mod_foo">mod_foo.php</filename>
<folder>tmpl</folder>
<folder>language</folder>
<filename>mod_foo.xml</filename>
</files>

</extension>

</source>

<translate>
=== Creating the language files === 
</translate>
<translate> The files <tt>language/en-GB/en-GB.mod̠foo.ini</tt> and <tt>language/en-GB/en-GB.mod̠foo.sys.ini</tt> are used to translate text in the frontend and in the backend.</translate>

<translate> The code for <tt>language/en-GB/en-GB.mod̠foo.sys.ini</tt> is as follows:</translate>

<source lang="xml">

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"

</source>

<source lang="xml">

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"

</source>

<translate> The <tt>.sys.ini</tt> file is used to translate the description of the extension upon installation, where as the <tt>.ini</tt> file is used to translate the remaining strings and the description when viewing your extension.</translate>

<translate> More information about language files can be found [[S:MyLanguage/Specification_of_language_files|here]].</translate>

<translate>
== Test your module == 
</translate>
<translate> Now you can zip all files and install them via the Joomla Extension Manager.<br /></translate>
<translate> After that you can choose your module in the module manager, when you create a new site module.</translate>
{{-}}
[[File:moduletutorial1-<translate> en</translate>.png|700px|center]]
{{-}}
[[File:moduletutorial2-<translate> en</translate>.png|700px|center]]

<translate> In the frontend, you will see your module like displayed in the next image.</translate>
{{-}}
[[File:moduletutorial3-<translate> en</translate>.png|700px|center]]

<translate>
== Conclusion == 
</translate>
<translate> Module development for Joomla is a fairly simple, straightforward process. Using the techniques described in this tutorial, an endless variety of modules can be developed with little hassle.</translate>

<translate> You can find boilerplates hereː</translate>
* https://github.com/joomla-extensions/boilerplate/tree/master/module
<translate> The sample files for this Tutorial can be found hereː</translate>
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

<translate>

== Add a helper class using namespaces - Part 2== 
</translate>

<translate>
=== Requirements === 
</translate>
<translate> You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)</translate>

<translate>
== Namespaces == 
</translate>
<translate> With PHP 5.3, the namespaces came into their own. In other programming languages for a long time in use, these small structures now also help us with the clarity of our code.</translate>

<translate> Namespaces are separate areas in which certain logical things (in our case, classes, interfaces, functions, and constants) can live. These areas provide ncapsulation of the code and prevent name conflicts.</translate>

<translate> Let's take a look how to use them in Joomla 4. We use the helper file for this.</translate>

<translate>
=== File Structure === 
</translate>
<translate> We will create/change the following files:</translate>
<translate>
* <code>Helper/FooHelper.php</code> - This is the file we use here as an example. We have to create it.
* <code>mod_foo.php</code> - In this file we will mainly load the namespace.
* <code>tmpl/default.php</code> - In this file demonstrate how the data of a helper can be displayed.
* <code>mod_foo.xml</code> - We create a new directory with a new file. This must be installed during the installation. For this we have to specify them in this file.</translate>

<translate>
=== Creating Helper/FooHelper.php === 
</translate>
<translate> Our new helper class should belong to a namespace. We achieve this with the following code. It is important, that this line is at the beginning of the file.</translate>

<source lang="php">namespace Joomla\Module\Foo\Site\Helper;</source>

<translate> Then we create a simple class with a simple method. Of course you can do a lot more here. Take a look at the Joomla core methods. Here are many examples. They show you first-hand what options you have.</translate>

<translate>
==== Completed Helper/FooHelper.php ==== 
</translate>
<translate> The complete <tt>mod_foo.php</tt> file is as follows:</translate>

<source lang="php">

<?php
/**
* @package Joomla.Site
* @subpackage mod_foo
*
* @copyright Copyright (C) 2005 - 2018 Open Source Matters, Inc. All rights reserved.
* @license GNU General Public License version 2 or later; see LICENSE.txt
*/

namespace Joomla\Module\Foo\Site\Helper;

defined('_JEXEC') or die;

/**
* Helper for mod_foo
*
* @since 4.0
*/
class FooHelper
{
/**
* Retrieve foo test
*
* @param Registry $params The module parameters
* @param CMSApplication $app The application
*
* @return array
*/
public static function getText()
{
return 'FooHelpertest';
}
}

</source>

<translate>

=== Editing mod_foo.php === 
</translate>
<translate> Our new helper class is imported to our current scope at the begin of the file.</translate>

<source lang="php">use Joomla\Module\Foo\Site\Helper\FooHelper;</source>

<translate> Last use the helper file for testing if it is loaded correctlyː</translate>

<source lang="php">$test = FooHelper::getText($params, $app);</source>

<translate>
==== Completed mod_foo.php file ==== 
</translate>
<translate> The complete <tt>mod_foo.php</tt> file is as follows:</translate>

<source lang="php">

<?php
/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/

defined('_JEXEC') or die;

use Joomla\CMS\Helper\ModuleHelper;
use Joomla\Module\Foo\Site\Helper\FooHelper;

$test = FooHelper::getText();

require ModuleHelper::getLayoutPath('mod_foo', $params->get('layout', 'default'));

</source>

<translate>
=== Editing tmpl/default.php === 
</translate>
<translate> In this file you make only a small change to demonstrate in the frontend that your helper file is working properly. You only add the value of the variable at the end of the current output.</translate>

<source lang="php"><?php echo '[PROJECT_NAME]' . $test;</source>

<translate>
==== Completed tmpl/default.php ==== 
</translate>
<translate> The complete <tt>tmpl/default.php</tt> file is as follows:</translate>

<source lang="php">

<?php
/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/

defined('_JEXEC') or die;

?>

<?php echo '[PROJECT_NAME]' . $test;

</source>

<translate>
=== Editing mod_foo.xml === 
</translate>
<translate> First you have to add a line, so that the namespace is set automatically in Joomla. After this change, you have to re-install your module. A simple change in an already installed module is not enough. If you are doing local development you can also delete the files libraries/autoload_psr4.php and it will automatically be re-created. After inserting and installing, the namespace is known by the loader <tt>JPATH_LIBRARIES . '/autoload_psr4.php'</tt>.</translate>

<source lang="xml"><namespace>Joomla\Module\Foo</namespace></source>

<translate> Joomla! should copy your helper file when installing the module. So Joomla! needs to know your helper file. For this, you need to add the following line to your XML file.</translate>

<source lang="xml"><folder>Helper</folder></source>

<translate>
==== Completed mod_foo.xml ==== 
</translate>
<translate> The complete <tt>mod_foo.xml</tt> file is as follows:</translate>

<source lang="xml">

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.8" client="site" method="upgrade">
<name>MOD_FOO</name>
<creationDate>[DATE]</creationDate>
<author>[AUTHOR]</author>
<authorEmail>[AUTHOR_EMAIL]</authorEmail>
<authorUrl>[AUTHOR_URL]</authorUrl>
<copyright>[COPYRIGHT]</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<version>1.0</version>
<description>MOD_FOO_XML_DESCRIPTION</description>
<namespace>Joomla\Module\Foo</namespace>
<files>
<filename module="mod_foo">mod_foo.php</filename>
<folder>tmpl</folder>
<folder>Helper</folder>
<folder>language</folder>
<filename>mod_foo.xml</filename>
</files>

</extension>

</source>

<translate>
== Test your module == 
</translate>
<translate> Now you can zip all files and install them via the Joomla Extension Manager.</translate>
<translate> After that you can choose your module in the module manager, when you create a new site module.</translate>

<translate> In the frontend you will see your module like displayed in the next image. The text form your helper file is displayed.</translate>
{{-}}
[[File:moduletutorial23-<translate> en</translate>.png|700px|center]]

<translate>
== Conclusion == 
</translate>
<translate> As you can see, once you get a bit into the namespaces, they are not that complicated anymore. In big projects they can bring a lot of benefits. However, we should plan namespaces, as otherwise it will soon be more time-consuming.</translate>

<translate> You can find boilerplates hereː</translate>
* https://github.com/joomla-extensions/boilerplate/tree/master/module
<translate> The sample files for this Tutorial can be found hereː</translate>
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

<translate>

== Customizationː Add parameters via form fields - Part 3 == 
</translate>

<translate>
=== Requirements === 
</translate>
<translate> You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)</translate>

<translate>
== Customization with form fields and parameters == 
</translate>
<translate> Form fields give a great deal of customization in Joomla and for modules are the sole way of allowing the user to tweak the module to the needs of their site.</translate>

<translate> In this case we are going to extend our previous example using a url field for inserting a domain that we can use as link in the front end. To allow this to happen we will use the [[S:MyLanguage/URL_form_field_type|URL Form Field]] type.</translate>

<translate> After that, we insert parameters that allow to use standard functionality of Joomla.</translate>

<translate> Let's take a look on how to use them in Joomla 4.</translate>

<translate>
=== File Structure === 
</translate>
<translate> We will change the following files:</translate>
<translate>
* <tt>mod_foo.xml</tt> - This is the file where we add the fields.
* <tt>tmpl/default.php</tt> - In this file demonstrate how the data of a field can be used.
* <tt>language/en-GB/en-GB.mod_foo.ini</tt> - Here we use a language string so that the field can be labeled correctly in different languages.</translate>

<translate>
=== Editing mod_foo.xml === 
</translate>
<translate> First we set a custom parameter.</translate>

<source lang="xml">

<field
name="domain"
type="url"
label="MOD_FOO_FIELD_URL_LABEL"
filter="url"
/>

</source>

<translate> Then we insert Joomla default fields, so that we can use cache, moduleclass-suffix and layouts.</translate>

<source lang="xml">
<field
name="layout"
type="modulelayout"
label="JFIELD_ALT_LAYOUT_LABEL"
class="custom-select"
/>

<field
name="moduleclass_sfx"
type="textarea"
label="COM_MODULES_FIELD_MODULECLASS_SFX_LABEL"
rows="3"
/>

<field
name="cache"
type="list"
label="COM_MODULES_FIELD_CACHING_LABEL"
default="0"
>
<option value="1">JGLOBAL_USE_GLOBAL</option>
<option value="0">COM_MODULES_FIELD_VALUE_NOCACHING</option>
</field>

<field
name="cache_time"
type="number"
label="COM_MODULES_FIELD_CACHE_TIME_LABEL"
default="0"
/>

<field
name="cachemode"
type="hidden"
default="itemid"
>
<option value="itemid"></option>
</field>

</source>

<translate>
==== Completed mod_foo.xml ==== 
</translate>
<translate> The complete <tt>mod_foo.xml</tt> file is as follows:</translate>

<source lang="xml">

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.8" client="site" method="upgrade">
<name>MOD_FOO</name>
<creationDate>[DATE]</creationDate>
<author>[AUTHOR]</author>
<authorEmail>[AUTHOR_EMAIL]</authorEmail>
<authorUrl>[AUTHOR_URL]</authorUrl>
<copyright>[COPYRIGHT]</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<version>1.0</version>
<description>MOD_FOO_XML_DESCRIPTION</description>
<namespace>Joomla\Module\Foo</namespace>
<files>
<filename module="mod_foo">mod_foo.php</filename>
<folder>tmpl</folder>
<folder>Helper</folder>
<folder>language</folder>
<filename>mod_foo.xml</filename>
</files>
<config>
<fields name="params">
<fieldset name="basic">
<field
name="domain"
type="url"
label="MOD_FOO_FIELD_URL_LABEL"
filter="url"
/>
</fieldset>
<fieldset name="advanced">
<field
name="layout"
type="modulelayout"
label="JFIELD_ALT_LAYOUT_LABEL"
class="custom-select"
/>

<field
name="moduleclass_sfx"
type="textarea"
label="COM_MODULES_FIELD_MODULECLASS_SFX_LABEL"
rows="3"
/>

<field
name="cache"
type="list"
label="COM_MODULES_FIELD_CACHING_LABEL"
default="0"
>
<option value="1">JGLOBAL_USE_GLOBAL</option>
<option value="0">COM_MODULES_FIELD_VALUE_NOCACHING</option>
</field>

<field
name="cache_time"
type="number"
label="COM_MODULES_FIELD_CACHE_TIME_LABEL"
default="0"
/>

<field
name="cachemode"
type="hidden"
default="itemid"
>
<option value="itemid"></option>
</field>
</fieldset>
</fields>
</config>
</extension>

</source>

<translate>
=== Editing tmpl/default.php === 
</translate>
<translate> We can use the value of the parameter for creating an hyperlink in the frontend. We can access the value via the variable via the variable $params.</translate>

<source lang="php">$domain = $params->get('domain', 'https://www.joomla.org');</source>

<translate> Later we set use this value for creating the hyperlink.</translate>

<source lang="php">

<a href="<?php echo $domain; ?>">
<?php echo '[PROJECT_NAME]' . $test; ?>
</a>

</source>

<translate>
==== Completed tmpl/default.php file ==== 
</translate>
<translate> The complete <tt>tmpl/default.php</tt> file is as follows:</translate>

<source lang="php">

<?php
/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/

defined('_JEXEC') or die;

$domain = $params->get('domain', 'https://www.joomla.org');
?>

<a href="<?php echo $domain; ?>">
<?php echo '[PROJECT_NAME]' . $test; ?>
</a>

</source>

<translate>
=== Editing language/en-GB/en-GB.mod_foo.ini === 
</translate>
<translate> Here we can specify the text for the English version of the field label.</translate>

<source lang="php">MOD_FOO_FIELD_URL_LABEL="Url"</source>

<translate>
==== Completed language/en-GB/en-GB.mod_foo.ini ==== 
</translate>
<translate> The complete <tt>language/en-GB/en-GB.mod_foo.ini</tt> file is as follows:</translate>

<source lang="php">

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"
MOD_FOO_FIELD_URL_LABEL="Url"

</source>

<translate>
== Test your module == 
</translate>
<translate> Now you can zip all files and install them via the Joomla Extension Manager.</translate>
<translate> After that you can choose your module in the module manager, when you create a new site module.</translate>

<translate> In the backend, you will see your module like displayed in the next image.</translate>

<translate> In the basic tab, you will see the custom field where you can insert a domain. The text for the label is fetched from the language file.</translate>
{{-}}
[[File:moduletutorial31-<translate> en</translate>.png|700px|center]]

<translate> In the advanced tab, you will see all default options except the cache mode because of this is a hidden field.</translate>
{{-}}
[[File:moduletutorial32-<translate> en</translate>.png|700px|center]]

<translate> In the frontend, you will see your module like displayed in the next image. The text form your helper file is displayed and you should see a hyperlink.</translate>
{{-}}
[[File:moduletutorial33-<translate> en</translate>.png|700px|center]]

<translate>
== Conclusion == 
</translate>
<translate> Form fields give the user an easy way to customize the module to their sites settings. This allows the modules scope to be increased.</translate>

<translate> You can find boilerplates hereː</translate>
* https://github.com/joomla-extensions/boilerplate/tree/master/module
<translate> The sample files for this Tutorial can be found hereː</translate>
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules
<translate> See this issue for possible future changes:</translate>
* https://github.com/joomla/joomla-cms/pull/23553

<translate>

== Use Install, Update and Uninstall script - Part 4 == 
</translate>

<translate>
=== Requirements === 
</translate>
<translate> You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)</translate>

<translate>
=== Scripts === 
</translate>
<translate> Installing, updating and uninstalling a module may require additional operations that cannot be achieved by the basic operations described in the main XML file. Joomla offers a new approach to solve this problem. It consists in using a PHP script file containing a class using five methods:</translate>
<translate>
* preflight which is executed before install and update
* install
* update
* uninstall
* postflight which is executed after install and update</translate>

<translate> Let's take a look how to use them in Joomla 4. We use the helper file for this.</translate>

<translate>
=== File Structure === 
</translate>
<translate> We will create/change the following files:</translate>
<translate>
* <tt>script.php</tt> - This is the file we use here as an example. We have to create it.
* <tt>language/en-GB/en-GB.mod_foo.sys.ini</tt> - In this file we will add text.
* <tt>mod_foo.xml</tt> - We create a new file. This must be installed during the installation. For this we have to specify it in this file.</translate>

<translate>
=== Creating script.php === 
</translate>
<translate> Writing an extension script consists in declaring a class whose name is <tt>mod_ModuleNameInstallerScripʈ</tt> with these 5 methods. See the comments in the file for more information. In this comments I explain when a method is called.</translate>

<translate> In this example, I only use text to show when which method will be executed. In addition, I show you how to check the minimum requirements. Of course you can do much more. For example, you can delete files that are no longer needed in a new version of your module. This can be seen in the file. Another idea for this file is to create sample content, to show a success message with the current installed version number or you can redirect after a successful installation to the page with the module settings.</translate>

<translate>
==== Completed script.php ==== 
</translate>
<translate> The complete <tt>script.php</tt> file is as follows:</translate>

<source lang="php">

<?php

/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/
// No direct access to this file
defined('_JEXEC') or die;

use Joomla\CMS\Language\Text;
use Joomla\CMS\Log\Log;

/**
* Script file of Foo module
*/
class mod_fooInstallerScript {

/**
* Extension script constructor.
*
* @return void
*/
public function __construct() {
$this->minimumJoomla = '4.0';
$this->minimumPhp = JOOMLA_MINIMUM_PHP;
}

/**
* Method to install the extension
*
* @param InstallerAdapter $parent The class calling this method
*
* @return boolean True on success
*/
function install($parent) {
echo Text::_('MOD_FOO_INSTALLERSCRIPT_UNINSTALL');

return true;
}

/**
* Method to uninstall the extension
*
* @param InstallerAdapter $parent The class calling this method
*
* @return boolean True on success
*/
function uninstall($parent) {
echo Text::_('MOD_FOO_INSTALLERSCRIPT_UNINSTALL');

return true;
}

/**
* Method to update the extension
*
* @param InstallerAdapter $parent The class calling this method
*
* @return boolean True on success
*/
function update($parent) {
echo Text::_('MOD_FOO_INSTALLERSCRIPT_UPDATE');

return true;
}

/**
* Function called before extension installation/update/removal procedure commences
*
* @param string $type The type of change (install, update or discover_install, not uninstall)
* @param InstallerAdapter $parent The class calling this method
*
* @return boolean True on success
*/
function preflight($type, $parent) {
// Check for the minimum PHP version before continuing
if (!empty($this->minimumPhp) && version_compare(PHP_VERSION, $this->minimumPhp, '<')) {
Log::add(Text::sprintf('JLIB_INSTALLER_MINIMUM_PHP', $this->minimumPhp), Log::WARNING, 'jerror');

return false;
}

// Check for the minimum Joomla version before continuing
if (!empty($this->minimumJoomla) && version_compare(JVERSION, $this->minimumJoomla, '<')) {
Log::add(Text::sprintf('JLIB_INSTALLER_MINIMUM_JOOMLA', $this->minimumJoomla), Log::WARNING, 'jerror');

return false;
}

echo Text::_('MOD_FOO_INSTALLERSCRIPT_PREFLIGHT');
echo $this->minimumJoomla . ' ' . $this->minimumPhp;

return true;
}

/**
* Function called after extension installation/update/removal procedure commences
*
* @param string $type The type of change (install, update or discover_install, not uninstall)
* @param InstallerAdapter $parent The class calling this method
*
* @return boolean True on success
*/
function postflight($type, $parent) {
echo Text::_('MOD_FOO_INSTALLERSCRIPT_POSTFLIGHT');

return true;
}

}

</source>

<translate>
=== Editing language/en-GB/en-GB.mod_foo.sys.ini === 
</translate>
<translate> There is not much to explain here. Write the text for the translation into this file.</translate>

<translate>
==== Completed language/en-GB/en-GB.mod_foo.sys.ini file ==== 
</translate>
<translate> The complete <tt>language/en-GB/en-GB.mod_foo.sys.ini</tt> file is as follows:</translate>

<source lang="php">

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"
MOD_FOO_INSTALLERSCRIPT_PREFLIGHT="<p>Anything here happens before the installation/update/uninstallation of the module</p>"
MOD_FOO_INSTALLERSCRIPT_UPDATE="<p>The module has been updated</p>"
MOD_FOO_INSTALLERSCRIPT_UNINSTALL="<p>The module has been uninstalled</p>"
MOD_FOO_INSTALLERSCRIPT_INSTALL="<p>The module has been installed</p>"
MOD_FOO_INSTALLERSCRIPT_POSTFLIGHT="<p>Anything here happens after the installation/update/uninstallation of the module</p>"

</source>

<translate>
=== Editing mod_foo.xml === 
</translate>
<translate> You have to add a line, so that the script is called automatically in Joomla.</translate>

<source lang="xml"><scriptfile>script.php</scriptfile></source>

<translate>
==== Completed mod_foo.xml ==== 
</translate>
<translate> The complete <tt>mod_foo.xml</tt> file is as follows:</translate>

<source lang="xml">

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="4.0" client="site" method="upgrade">
<name>MOD_FOO</name>
<creationDate>[DATE]</creationDate>
<author>[AUTHOR]</author>
<authorEmail>[AUTHOR_EMAIL]</authorEmail>
<authorUrl>[AUTHOR_URL]</authorUrl>
<copyright>[COPYRIGHT]</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<version>1.0</version>
<description>MOD_FOO_XML_DESCRIPTION</description>
<namespace>Joomla\Module\Foo</namespace>
<scriptfile>script.php</scriptfile>
<files>
<filename module="mod_foo">mod_foo.php</filename>
<folder>tmpl</folder>
<folder>Helper</folder>
<folder>language</folder>
<filename>mod_foo.xml</filename>
</files>
<config>
<fields name="params">
<fieldset name="basic">
<field
name="domain"
type="url"
label="MOD_FOO_FIELD_URL_LABEL"
filter="url"
/>
</fieldset>
<fieldset name="advanced">
<field
name="layout"
type="modulelayout"
label="JFIELD_ALT_LAYOUT_LABEL"
class="custom-select"
/>

<field
name="moduleclass_sfx"
type="textarea"
label="COM_MODULES_FIELD_MODULECLASS_SFX_LABEL"
rows="3"
/>

<field
name="cache"
type="list"
label="COM_MODULES_FIELD_CACHING_LABEL"
default="0"
>
<option value="1">JGLOBAL_USE_GLOBAL</option>
<option value="0">COM_MODULES_FIELD_VALUE_NOCACHING</option>
</field>

<field
name="cache_time"
type="number"
label="COM_MODULES_FIELD_CACHE_TIME_LABEL"
default="0"
/>

<field
name="cachemode"
type="hidden"
default="itemid"
>
<option value="itemid"></option>
</field>
</fieldset>
</fields>
</config>
</extension>
</source>

<translate>
== Test your module == 
</translate>
<translate> Now you can zip all files and install them via the Joomla Extension Manager.</translate>
<translate> Immediately after the installation, you will see the following information. This you had entered in the script so.</translate>
{{-}}
[[File:moduletutorial14-<translate> en</translate>.png|700px|center]]

<translate>
== Conclusion == 
</translate>
<translate> As you can see, Joomla offers you a lot to make your extension easy to use - right from the start.</translate>

<translate> You can find boilerplates hereː</translate>
* https://github.com/joomla-extensions/boilerplate/tree/master/module
<translate> The sample files for this Tutorial can be found hereː</translate>
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

<translate>

== Use Joomla Updaterː Adding Auto Update - Part 5 == 
</translate>

<translate>
=== Requirements === 
</translate>
<translate> You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)</translate>

<translate>
=== Joomla Updater === 
</translate>
<translate> The first thing to do is to read the [[S:MyLanguage/J2.5:Managing_Component_Updates|Managing Component Upgrades with Joomla 2.5 - Part 1]] tutorial to give an idea of how the upgrade process works in Joomla. Whilst written for 2.5 the process hasn't changed. Also read [[S:MyLanguage/Deploying_an_Update_Server|Deploying an update server]] - this is what we'll be implementing in this tutorial.</translate>

<translate>
=== File Structure === 
</translate>
<translate> We will create/change the following files:</translate>
<translate> * <tt>mod_foo.xml</tt> - The only way to update our existing module is to add in a update server - for example <tt><nowiki>http://www.example.com/foo_update.xmɭ</nowiki></tt> - into the xml file.</translate>
<translate> * <tt>foo_update.xml</tt> - Then we have to create the XML file for the update server at <tt><nowiki>http://www.example.com/foo_update.xmɭ</nowiki></tt> to let Joomla know an update is available.</translate>

<translate>
==== Editing mod_foo.xml ==== 
</translate>
<translate> To add our update server, we need to insert the following lines in your XML-File</translate>

<source lang="php">

<updateservers>
<server type="extension" priority="1" name="[PROJECT_NAME]">https://www.example.com/mod_foo.xml</server>
</updateservers>

</source>

<translate>
==== Completed mod_foo.xml ==== 
</translate>
<translate> The complete <tt>mod_foo.xml</tt> file is as follows:</translate>

<source lang="xml">

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="4.0" client="site" method="upgrade">
<name>MOD_FOO</name>
<creationDate>[DATE]</creationDate>
<author>[AUTHOR]</author>
<authorEmail>[AUTHOR_EMAIL]</authorEmail>
<authorUrl>[AUTHOR_URL]</authorUrl>
<copyright>[COPYRIGHT]</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<version>1.0</version>
<description>MOD_FOO_XML_DESCRIPTION</description>
<namespace>Joomla\Module\Foo</namespace>
<files>
<filename module="mod_foo">mod_foo.php</filename>
<folder>tmpl</folder>
<folder>Helper</folder>
<folder>language</folder>
<filename>mod_foo.xml</filename>
</files>
<updateservers>
<server type="extension" priority="1" name="[PROJECT_NAME]">https://www.example.com/mod_foo.xml</server>
</updateservers>
<config>
<fields name="params">
<fieldset name="basic">
<field
name="domain"
type="url"
label="MOD_FOO_FIELD_URL_LABEL"
filter="url"
/>
</fieldset>
<fieldset name="advanced">
<field
name="layout"
type="modulelayout"
label="JFIELD_ALT_LAYOUT_LABEL"
class="custom-select"
/>

<field
name="moduleclass_sfx"
type="textarea"
label="COM_MODULES_FIELD_MODULECLASS_SFX_LABEL"
rows="3"
/>

<field
name="cache"
type="list"
label="COM_MODULES_FIELD_CACHING_LABEL"
default="0"
>
<option value="1">JGLOBAL_USE_GLOBAL</option>
<option value="0">COM_MODULES_FIELD_VALUE_NOCACHING</option>
</field>

<field
name="cache_time"
type="number"
label="COM_MODULES_FIELD_CACHE_TIME_LABEL"
default="0"
/>

<field
name="cachemode"
type="hidden"
default="itemid"
>
<option value="itemid"></option>
</field>
</fieldset>
</fields>
</config>
</extension>

</source>

<translate> So now that Joomla is searching for updates to our extension - let's create one to test out our process. But first we need to create the file <tt>foo_update.xml</tt>. So far we have only described the update server. We do not know yet if there is an update. In the file <tt>foo_update.xml</tt> we indicate when a new version is published and where it can be downloaded.</translate>

<translate>
=== Creating foo_update.xml === 
</translate>
<translate> Now we have to create the XML file at <tt><nowiki>http://www.example.com/foo_update.xml</nowiki></tt> to let Joomla know an update is available.</translate>

<translate>
==== Completed foo_update.xml ==== 
</translate>
<translate> The complete <tt>foo_update.xml</tt> file is as follows:</translate>

<source lang="xml">

<?xml version="1.0" ?>

<updates>
<update>
<name>Foo</name>
<description>This is mod_foo 1.0.1</description>
<element>mod_foo</element>
<type>module</type>
<version>1.0.1</version>
<downloads>
<downloadurl type="full" format="zip">http://www.example.com/mod_foo_101.zip</downloadurl>
</downloads>
<maintainer>Joomla</maintainer>
<maintainerurl>http://www.example.com</maintainerurl>
<targetplatform name="joomla" version="4.0"/>
<client>site</client>
</update>
</updates>

</source>

<translate> After uploading this file to the address <tt><nowiki>https://www.example.com/mod_foo.xml</nowiki></tt> the update will be displayed in the Joomla backend.</translate>

<translate>
=== Test your module update === 
</translate>
<translate> Create a copy of the module as it is now. Then let's update the version number to 1.0.1. Now you can zip all files. After that you should load your zip to the URL <tt><nowiki>http://www.example.com/mod_foo_101.zip</nowiki></tt>. Now you can update your module via the Joomla Updater.</translate>

<translate>
=== Commercial Modules === 
</translate>
<translate> Note that in our files we have linked to the extensions updates xml file. And from that xml file we have a location for the zip of the module. This means that if someone was to track this backwards they could find the physical source of your modules zip file. If you don't do like this, you can find a solution in this PRː https://github.com/joomla/joomla-cms/pull/15185 .</translate>

<translate>
=== Conclusion === 
</translate>
<translate> With the Joomla updater, you can easily reach all users and tell them that there is a new version. Even the update itself is easy.</translate>

<translate> Each extension should use an update server. Especially for security reasons.</translate>

<translate> You can find boilerplates hereː</translate>
* https://github.com/joomla-extensions/boilerplate/tree/master/plugins/system
<translate> The sample files for this Tutorial can be found hereː</translate>
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

<noinclude>
[[Category:Beginner Development{{#translation:}}]]
[[Category:Tutorials{{#translation:}}]]
[[Category:Tutorials in a Series{{#translation:}}]]
[[Category:Development{{#translation:}}]]
[[Category:Module Development{{#translation:}}]]
[[Category:Joomla! 4.x{{#translation:}}]]
[[Category:Joomla! 4.0{{#translation:}}]]
</noinclude>

J4.x:Creating a Simple Module

2019-06-21T07:02:34Z

Garkell: Changed to point to modules rather than plugin boilerplate

<noinclude><languages /></noinclude>
{{Joomla version|version=4.x|comment=><translate> Tutorial</translate>}}
{{-}}
{{Top portal heading|color=white-bkgd|icon=file-code-o|icon-color=#5091cd|size=5x|text-color=#333|title=<translate> Creating a Simple Module for Joomla 4.x</translate>}}
{{-}}

<translate> This is a tutorial on how to Create a simple module for Joomla Version 4x.</translate>
<translate>
== Introduction == 
</translate>
<translate> Joomlaǃ 4 provides five types of extensionsː</translate>
* '''[[S:MyLanguage/Component|<translate> Components</translate>]]'''<br /><translate> A component is the main part of the site. A component handles data manipulation as well as input and storage into the database. A component on most sites is the primary focus of the page.</translate>
* '''[[S:MyLanguage/Module|<translate> Modules</translate>]]''' <br /><translate> A module is an add-on to the site that extends the functionality. A module usually occupies a secondary portion of the web page and is not considered the primary focus of a page. It can be displayed on different positions and you can choose on which active menu items it should be displayed. Modules are lightweight and flexible extensions. They are used for small bits of the page that are generally less complex and are able to be seen across different components.</translate>
* '''[[S:MyLanguage/Plugin|<translate> Plugins</translate>]]'''<br /><translate> A Plugin manipulates output that is already generated by the system. It typically does not run as separate part of the site. It takes data from other sources (i.e. the content) and manipulates this data before displaying. A plugin typically work behind the scenes.</translate>
* '''[[S:MyLanguage/Languages|<translate> Languages</translate>]]'''<br />Probably the most basic extensions are languages. In essence the language package files consist of key/value pairs, which provide the translation of static text strings, assigned within the Joomla! source code.
* '''[[S:MyLanguage/Templates|<translate> Templates</translate>]]'''<br /><translate> A template is basically the design of your Joomla! powered website.</translate>

<translate> Joomla! 4 is constructed using five different applications:</translate>
<translate>
* Installation (used for installing Joomla and have to delete after installation)
* Administrator (backend - used for managing content)
* Public or site (frontend - used for displaying content)
* CLI (used for accessing Joomla on the command line and for cron jobs)
* API (web services - used for creating APIs for machine accessible content)</translate>
<translate>

The installation application is used once. The administrator and public are used through the concept of ''components'' with ''modules''. Each module has a single entry point located in the ''modules'' and accordingly ''administrator/modules'' directory. This entry point is called <tt>''mod_modulename/mod_modulename.php''</tt> (the ''mod_'' prefix is a historical trace). The entry point for the login module is for ''example /mod_login/mod_login.php''.</translate>

<translate>
=== Requirements === 
</translate>
<translate> You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)</translate>

<translate> You can download Joomla! 4 at [https://github.com/joomla/joomla-cms/tree/4.0-dev GitHub], on the [https://developer.joomla.org/nightly-builds.html Developer website] or you can create a free website at https://launch.joomla.org.</translate>

<translate>
== Creating a simple module/Developing a Basic Module - Part 1 == 
</translate>
<translate> You can see many examples of modules in the standard Joomla! install. For example:</translate>
<translate>
* Menus
* Latest News
* Login form
* and many more.</translate>

<translate> This tutorial will explain how to create a simple module. Through this tutorial you will learn the basic file structure of a Joomlaǃ 4 module. This basic structure can then be expanded to produce more elaborate modules.</translate>

<translate>
=== File Structure === 
</translate>
<translate> There are a few basic files that are used in the standard pattern of module development:</translate>
<translate> * <tt>mod_foo.php</tt> - This file is the main entry point for the module. It will perform any necessary initialization routines, call helper routines to collect any necessary data, and include the template which will display the module output.</translate>
<translate> * <tt>mod_foo.xml</tt> - This file contains information about the module. It defines the files that need to be installed by the Joomla! installer and specifies configuration parameters for the module.</translate>
<translate> * <tt>tmpl/default.php</tt> - This is the module template. This file will take the data collected by mod_foo.php and generate the HTML to be displayed on the page.</translate>
<translate> * <tt>language/en-GB/en-GB.mod_foo.ini</tt> and <tt>language/en-GB/en-GB.mod_foo.sys.ini</tt>- This are the files that provide the text in United Kingdom English.</translate>

<translate>
=== Creating mod_foo.php === 
</translate>
<translate> The <tt>mod_foo.php</tt> file will perform following tasks:</translate>
<translate> * Import the class <tt>ModuleHelper</tt> to the current scope. We need it later for displaying the output.</translate>
<translate> * Include the template to display the output.</translate>

<translate> The helper class is imported to our current scope at the begin of the file.</translate>

<source lang="php">use Joomla\CMS\Helper\ModuleHelper;</source>

<translate> Last we include the template to display the output via</translate>

<source lang="php">require ModuleHelper::getLayoutPath('mod_foo', $params->get('layout', 'default'));</source>

<translate>
==== Completed mod_foo.php file ==== 
</translate>
<translate> The complete <tt>mod_foo.php</tt> file is as follows:</translate>

<source lang="php">
<?php
/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/

use Joomla\CMS\Helper\ModuleHelper;

defined('_JEXEC') or die;

require ModuleHelper::getLayoutPath('mod_foo', $params->get('layout', 'default'));

</source>

<translate> ''Side note''ː In Joomla 3x you usually used a line like <tt>$moduleclass_sfx = htmlspecialchars($params->get('moduleclass_sfx'));</tt>. You don't need this anymore. See this PRː https://github.com/joomla/joomla-cms/pull/17447.</translate>

<translate> The one line that we haven’t explained so far is the first line <tt>defined('_JEXEC') or die;</tt>. This line checks to make sure that this file is being included from the Joomla application. This is necessary to prevent variable injection and other potential security concerns.</translate>

<translate>
=== Creating tmpl/default.php === 
</translate>
<translate> The <tt>default.php</tt> file is the template which displays the module output.</translate>

<translate>
==== Completed tmpl/default.php file ==== 
</translate>
<translate> The code for the tmpl/default.php file is as follows:</translate>

<source lang="php">
<?php
/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/

defined('_JEXEC') or die;

echo '[PROJECT_NAME]';

</source>

<translate> An important point to note is that the template file has the same scope as the <tt>mod_foo.php</tt> file. It means that a variable can be defined in the <tt>mod_foo.php</tt> file and then used in the template file without any extra declarations or function calls.</translate>

<translate>
=== Creating mod_foo.xml === 
</translate>
<translate> The <tt>mod_foo.xml</tt> file is the installation file. Most entries are self-explanatory.</translate>

<translate>
==== Completed mod_foo.xml file ==== 
</translate>
<translate> The code for the <tt>mod_foo.xml</tt> file is as follows:</translate>

<source lang="xml">

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.8" client="site" method="upgrade">
<name>MOD_FOO</name>
<creationDate>[DATE]</creationDate>
<author>[AUTHOR]</author>
<authorEmail>[AUTHOR_EMAIL]</authorEmail>
<authorUrl>[AUTHOR_URL]</authorUrl>
<copyright>[COPYRIGHT]</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<version>1.0</version>
<description>MOD_FOO_XML_DESCRIPTION</description>

<files>
<filename module="mod_foo">mod_foo.php</filename>
<folder>tmpl</folder>
<folder>language</folder>
<filename>mod_foo.xml</filename>
</files>

</extension>

</source>

<translate>
=== Creating the language files === 
</translate>
<translate> The files <tt>language/en-GB/en-GB.mod̠foo.ini</tt> and <tt>language/en-GB/en-GB.mod̠foo.sys.ini</tt> are used to translate text in the frontend and in the backend.</translate>

<translate> The code for <tt>language/en-GB/en-GB.mod̠foo.sys.ini</tt> is as follows:</translate>

<source lang="xml">

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"

</source>

<source lang="xml">

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"

</source>

<translate> The <tt>.sys.ini</tt> file is used to translate the description of the extension upon installation, where as the <tt>.ini</tt> file is used to translate the remaining strings and the description when viewing your extension.</translate>

<translate> More information about language files can be found [[S:MyLanguage/Specification_of_language_files|here]].</translate>

<translate>
== Test your module == 
</translate>
<translate> Now you can zip all files and install them via the Joomla Extension Manager.<br /></translate>
<translate> After that you can choose your module in the module manager, when you create a new site module.</translate>
{{-}}
[[File:moduletutorial1-<translate> en</translate>.png|700px|center]]
{{-}}
[[File:moduletutorial2-<translate> en</translate>.png|700px|center]]

<translate> In the frontend, you will see your module like displayed in the next image.</translate>
{{-}}
[[File:moduletutorial3-<translate> en</translate>.png|700px|center]]

<translate>
== Conclusion == 
</translate>
<translate> Module development for Joomla is a fairly simple, straightforward process. Using the techniques described in this tutorial, an endless variety of modules can be developed with little hassle.</translate>

<translate> You can find boilerplates hereː</translate>
* https://github.com/joomla-extensions/boilerplate/tree/master/module
<translate> The sample files for this Tutorial can be found hereː</translate>
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

<translate>

== Add a helper class using namespaces - Part 2== 
</translate>

<translate>
=== Requirements === 
</translate>
<translate> You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)</translate>

<translate>
== Namespaces == 
</translate>
<translate> With PHP 5.3, the namespaces came into their own. In other programming languages for a long time in use, these small structures now also help us with the clarity of our code.</translate>

<translate> Namespaces are separate areas in which certain logical things (in our case, classes, interfaces, functions, and constants) can live. These areas provide ncapsulation of the code and prevent name conflicts.</translate>

<translate> Let's take a look how to use them in Joomla 4. We use the helper file for this.</translate>

<translate>
=== File Structure === 
</translate>
<translate> We will create/change the following files:</translate>
<translate>
* <code>Helper/FooHelper.php</code> - This is the file we use here as an example. We have to create it.
* <code>mod_foo.php</code> - In this file we will mainly load the namespace.
* <code>tmpl/default.php</code> - In this file demonstrate how the data of a helper can be displayed.
* <code>mod_foo.xml</code> - We create a new directory with a new file. This must be installed during the installation. For this we have to specify them in this file.</translate>

<translate>
=== Creating Helper/FooHelper.php === 
</translate>
<translate> Our new helper class should belong to a namespace. We achieve this with the following code. It is important, that this line is at the beginning of the file.</translate>

<source lang="php">namespace Joomla\Module\Foo\Site\Helper;</source>

<translate> Then we create a simple class with a simple method. Of course you can do a lot more here. Take a look at the Joomla core methods. Here are many examples. They show you first-hand what options you have.</translate>

<translate>
==== Completed Helper/FooHelper.php ==== 
</translate>
<translate> The complete <tt>mod_foo.php</tt> file is as follows:</translate>

<source lang="php">

<?php
/**
* @package Joomla.Site
* @subpackage mod_foo
*
* @copyright Copyright (C) 2005 - 2018 Open Source Matters, Inc. All rights reserved.
* @license GNU General Public License version 2 or later; see LICENSE.txt
*/

namespace Joomla\Module\Foo\Site\Helper;

defined('_JEXEC') or die;

/**
* Helper for mod_foo
*
* @since 4.0
*/
class FooHelper
{
/**
* Retrieve foo test
*
* @param Registry $params The module parameters
* @param CMSApplication $app The application
*
* @return array
*/
public static function getText()
{
return 'FooHelpertest';
}
}

</source>

<translate>

=== Editing mod_foo.php === 
</translate>
<translate> Our new helper class is imported to our current scope at the begin of the file.</translate>

<source lang="php">use Joomla\Module\Foo\Site\Helper\FooHelper;</source>

<translate> Last use the helper file for testing if it is loaded correctlyː</translate>

<source lang="php">$test = FooHelper::getText($params, $app);</source>

<translate>
==== Completed mod_foo.php file ==== 
</translate>
<translate> The complete <tt>mod_foo.php</tt> file is as follows:</translate>

<source lang="php">

<?php
/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/

defined('_JEXEC') or die;

use Joomla\CMS\Helper\ModuleHelper;
use Joomla\Module\Foo\Site\Helper\FooHelper;

$test = FooHelper::getText();

require ModuleHelper::getLayoutPath('mod_foo', $params->get('layout', 'default'));

</source>

<translate>
=== Editing tmpl/default.php === 
</translate>
<translate> In this file you make only a small change to demonstrate in the frontend that your helper file is working properly. You only add the value of the variable at the end of the current output.</translate>

<source lang="php"><?php echo '[PROJECT_NAME]' . $test;</source>

<translate>
==== Completed tmpl/default.php ==== 
</translate>
<translate> The complete <tt>tmpl/default.php</tt> file is as follows:</translate>

<source lang="php">

<?php
/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/

defined('_JEXEC') or die;

?>

<?php echo '[PROJECT_NAME]' . $test;

</source>

<translate>
=== Editing mod_foo.xml === 
</translate>
<translate> First you have to add a line, so that the namespace is set automatically in Joomla. After this change, you have to re-install your module. A simple change in an already installed module is not enough. If you are doing local development you can also delete the files libraries/autoload_psr4.php and it will automatically be re-created. After inserting and installing, the namespace is known by the loader <tt>JPATH_LIBRARIES . '/autoload_psr4.php'</tt>.</translate>

<source lang="xml"><namespace>Joomla\Module\Foo</namespace></source>

<translate> Joomla! should copy your helper file when installing the module. So Joomla! needs to know your helper file. For this, you need to add the following line to your XML file.</translate>

<source lang="xml"><folder>Helper</folder></source>

<translate>
==== Completed mod_foo.xml ==== 
</translate>
<translate> The complete <tt>mod_foo.xml</tt> file is as follows:</translate>

<source lang="xml">

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.8" client="site" method="upgrade">
<name>MOD_FOO</name>
<creationDate>[DATE]</creationDate>
<author>[AUTHOR]</author>
<authorEmail>[AUTHOR_EMAIL]</authorEmail>
<authorUrl>[AUTHOR_URL]</authorUrl>
<copyright>[COPYRIGHT]</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<version>1.0</version>
<description>MOD_FOO_XML_DESCRIPTION</description>
<namespace>Joomla\Module\Foo</namespace>
<files>
<filename module="mod_foo">mod_foo.php</filename>
<folder>tmpl</folder>
<folder>Helper</folder>
<folder>language</folder>
<filename>mod_foo.xml</filename>
</files>

</extension>

</source>

<translate>
== Test your module == 
</translate>
<translate> Now you can zip all files and install them via the Joomla Extension Manager.</translate>
<translate> After that you can choose your module in the module manager, when you create a new site module.</translate>

<translate> In the frontend you will see your module like displayed in the next image. The text form your helper file is displayed.</translate>
{{-}}
[[File:moduletutorial23-<translate> en</translate>.png|700px|center]]

<translate>
== Conclusion == 
</translate>
<translate> As you can see, once you get a bit into the namespaces, they are not that complicated anymore. In big projects they can bring a lot of benefits. However, we should plan namespaces, as otherwise it will soon be more time-consuming.</translate>

<translate> You can find boilerplates hereː</translate>
* https://github.com/joomla-extensions/boilerplate/tree/master/module
<translate> The sample files for this Tutorial can be found hereː</translate>
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

<translate>

== Customizationː Add parameters via form fields - Part 3 == 
</translate>

<translate>
=== Requirements === 
</translate>
<translate> You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)</translate>

<translate>
== Customization with form fields and parameters == 
</translate>
<translate> Form fields give a great deal of customization in Joomla and for modules are the sole way of allowing the user to tweak the module to the needs of their site.</translate>

<translate> In this case we are going to extend our previous example using a url field for inserting a domain that we can use as link in the front end. To allow this to happen we will use the [[S:MyLanguage/URL_form_field_type|URL Form Field]] type.</translate>

<translate> After that, we insert parameters that allow to use standard functionality of Joomla.</translate>

<translate> Let's take a look on how to use them in Joomla 4.</translate>

<translate>
=== File Structure === 
</translate>
<translate> We will change the following files:</translate>
<translate>
* <tt>mod_foo.xml</tt> - This is the file where we add the fields.
* <tt>tmpl/default.php</tt> - In this file demonstrate how the data of a field can be used.
* <tt>language/en-GB/en-GB.mod_foo.ini</tt> - Here we use a language string so that the field can be labeled correctly in different languages.</translate>

<translate>
=== Editing mod_foo.xml === 
</translate>
<translate> First we set a custom parameter.</translate>

<source lang="xml">

<field
name="domain"
type="url"
label="MOD_FOO_FIELD_URL_LABEL"
filter="url"
/>

</source>

<translate> Then we insert Joomla default fields, so that we can use cache, moduleclass-suffix and layouts.</translate>

<source lang="xml">
<field
name="layout"
type="modulelayout"
label="JFIELD_ALT_LAYOUT_LABEL"
class="custom-select"
/>

<field
name="moduleclass_sfx"
type="textarea"
label="COM_MODULES_FIELD_MODULECLASS_SFX_LABEL"
rows="3"
/>

<field
name="cache"
type="list"
label="COM_MODULES_FIELD_CACHING_LABEL"
default="0"
>
<option value="1">JGLOBAL_USE_GLOBAL</option>
<option value="0">COM_MODULES_FIELD_VALUE_NOCACHING</option>
</field>

<field
name="cache_time"
type="number"
label="COM_MODULES_FIELD_CACHE_TIME_LABEL"
default="0"
/>

<field
name="cachemode"
type="hidden"
default="itemid"
>
<option value="itemid"></option>
</field>

</source>

<translate>
==== Completed mod_foo.xml ==== 
</translate>
<translate> The complete <tt>mod_foo.xml</tt> file is as follows:</translate>

<source lang="xml">

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.8" client="site" method="upgrade">
<name>MOD_FOO</name>
<creationDate>[DATE]</creationDate>
<author>[AUTHOR]</author>
<authorEmail>[AUTHOR_EMAIL]</authorEmail>
<authorUrl>[AUTHOR_URL]</authorUrl>
<copyright>[COPYRIGHT]</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<version>1.0</version>
<description>MOD_FOO_XML_DESCRIPTION</description>
<namespace>Joomla\Module\Foo</namespace>
<files>
<filename module="mod_foo">mod_foo.php</filename>
<folder>tmpl</folder>
<folder>Helper</folder>
<folder>language</folder>
<filename>mod_foo.xml</filename>
</files>
<config>
<fields name="params">
<fieldset name="basic">
<field
name="domain"
type="url"
label="MOD_FOO_FIELD_URL_LABEL"
filter="url"
/>
</fieldset>
<fieldset name="advanced">
<field
name="layout"
type="modulelayout"
label="JFIELD_ALT_LAYOUT_LABEL"
class="custom-select"
/>

<field
name="moduleclass_sfx"
type="textarea"
label="COM_MODULES_FIELD_MODULECLASS_SFX_LABEL"
rows="3"
/>

<field
name="cache"
type="list"
label="COM_MODULES_FIELD_CACHING_LABEL"
default="0"
>
<option value="1">JGLOBAL_USE_GLOBAL</option>
<option value="0">COM_MODULES_FIELD_VALUE_NOCACHING</option>
</field>

<field
name="cache_time"
type="number"
label="COM_MODULES_FIELD_CACHE_TIME_LABEL"
default="0"
/>

<field
name="cachemode"
type="hidden"
default="itemid"
>
<option value="itemid"></option>
</field>
</fieldset>
</fields>
</config>
</extension>

</source>

<translate>
=== Editing tmpl/default.php === 
</translate>
<translate> We can use the value of the parameter for creating an hyperlink in the frontend. We can access the value via the variable via the variable $params.</translate>

<source lang="php">$domain = $params->get('domain', 'https://www.joomla.org');</source>

<translate> Later we set use this value for creating the hyperlink.</translate>

<source lang="php">

<a href="<?php echo $domain; ?>">
<?php echo '[PROJECT_NAME]' . $test; ?>
</a>

</source>

<translate>
==== Completed tmpl/default.php file ==== 
</translate>
<translate> The complete <tt>tmpl/default.php</tt> file is as follows:</translate>

<source lang="php">

<?php
/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/

defined('_JEXEC') or die;

$domain = $params->get('domain', 'https://www.joomla.org');
?>

<a href="<?php echo $domain; ?>">
<?php echo '[PROJECT_NAME]' . $test; ?>
</a>

</source>

<translate>
=== Editing language/en-GB/en-GB.mod_foo.ini === 
</translate>
<translate> Here we can specify the text for the English version of the field label.</translate>

<source lang="php">MOD_FOO_FIELD_URL_LABEL="Url"</source>

<translate>
==== Completed language/en-GB/en-GB.mod_foo.ini ==== 
</translate>
<translate> The complete <tt>language/en-GB/en-GB.mod_foo.ini</tt> file is as follows:</translate>

<source lang="php">

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"
MOD_FOO_FIELD_URL_LABEL="Url"

</source>

<translate>
== Test your module == 
</translate>
<translate> Now you can zip all files and install them via the Joomla Extension Manager.</translate>
<translate> After that you can choose your module in the module manager, when you create a new site module.</translate>

<translate> In the backend, you will see your module like displayed in the next image.</translate>

<translate> In the basic tab, you will see the custom field where you can insert a domain. The text for the label is fetched from the language file.</translate>
{{-}}
[[File:moduletutorial31-<translate> en</translate>.png|700px|center]]

<translate> In the advanced tab, you will see all default options except the cache mode because of this is a hidden field.</translate>
{{-}}
[[File:moduletutorial32-<translate> en</translate>.png|700px|center]]

<translate> In the frontend, you will see your module like displayed in the next image. The text form your helper file is displayed and you should see a hyperlink.</translate>
{{-}}
[[File:moduletutorial33-<translate> en</translate>.png|700px|center]]

<translate>
== Conclusion == 
</translate>
<translate> Form fields give the user an easy way to customize the module to their sites settings. This allows the modules scope to be increased.</translate>

<translate> You can find boilerplates hereː</translate>
* https://github.com/joomla-extensions/boilerplate/tree/master/module
<translate> The sample files for this Tutorial can be found hereː</translate>
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules
<translate> See this issue for possible future changes:</translate>
* https://github.com/joomla/joomla-cms/pull/23553

<translate>

== Use Install, Update and Uninstall script - Part 4 == 
</translate>

<translate>
=== Requirements === 
</translate>
<translate> You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)</translate>

<translate>
=== Scripts === 
</translate>
<translate> Installing, updating and uninstalling a module may require additional operations that cannot be achieved by the basic operations described in the main XML file. Joomla offers a new approach to solve this problem. It consists in using a PHP script file containing a class using five methods:</translate>
<translate>
* preflight which is executed before install and update
* install
* update
* uninstall
* postflight which is executed after install and update</translate>

<translate> Let's take a look how to use them in Joomla 4. We use the helper file for this.</translate>

<translate>
=== File Structure === 
</translate>
<translate> We will create/change the following files:</translate>
<translate>
* <tt>script.php</tt> - This is the file we use here as an example. We have to create it.
* <tt>language/en-GB/en-GB.mod_foo.sys.ini</tt> - In this file we will add text.
* <tt>mod_foo.xml</tt> - We create a new file. This must be installed during the installation. For this we have to specify it in this file.</translate>

<translate>
=== Creating script.php === 
</translate>
<translate> Writing an extension script consists in declaring a class whose name is <tt>mod_ModuleNameInstallerScripʈ</tt> with these 5 methods. See the comments in the file for more information. In this comments I explain when a method is called.</translate>

<translate> In this example, I only use text to show when which method will be executed. In addition, I show you how to check the minimum requirements. Of course you can do much more. For example, you can delete files that are no longer needed in a new version of your module. This can be seen in the file. Another idea for this file is to create sample content, to show a success message with the current installed version number or you can redirect after a successful installation to the page with the module settings.</translate>

<translate>
==== Completed script.php ==== 
</translate>
<translate> The complete <tt>script.php</tt> file is as follows:</translate>

<source lang="php">

<?php

/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/
// No direct access to this file
defined('_JEXEC') or die;

use Joomla\CMS\Language\Text;
use Joomla\CMS\Log\Log;

/**
* Script file of Foo module
*/
class mod_fooInstallerScript {

/**
* Extension script constructor.
*
* @return void
*/
public function __construct() {
$this->minimumJoomla = '4.0';
$this->minimumPhp = JOOMLA_MINIMUM_PHP;
}

/**
* Method to install the extension
*
* @param InstallerAdapter $parent The class calling this method
*
* @return boolean True on success
*/
function install($parent) {
echo Text::_('MOD_FOO_INSTALLERSCRIPT_UNINSTALL');

return true;
}

/**
* Method to uninstall the extension
*
* @param InstallerAdapter $parent The class calling this method
*
* @return boolean True on success
*/
function uninstall($parent) {
echo Text::_('MOD_FOO_INSTALLERSCRIPT_UNINSTALL');

return true;
}

/**
* Method to update the extension
*
* @param InstallerAdapter $parent The class calling this method
*
* @return boolean True on success
*/
function update($parent) {
echo Text::_('MOD_FOO_INSTALLERSCRIPT_UPDATE');

return true;
}

/**
* Function called before extension installation/update/removal procedure commences
*
* @param string $type The type of change (install, update or discover_install, not uninstall)
* @param InstallerAdapter $parent The class calling this method
*
* @return boolean True on success
*/
function preflight($type, $parent) {
// Check for the minimum PHP version before continuing
if (!empty($this->minimumPhp) && version_compare(PHP_VERSION, $this->minimumPhp, '<')) {
Log::add(Text::sprintf('JLIB_INSTALLER_MINIMUM_PHP', $this->minimumPhp), Log::WARNING, 'jerror');

return false;
}

// Check for the minimum Joomla version before continuing
if (!empty($this->minimumJoomla) && version_compare(JVERSION, $this->minimumJoomla, '<')) {
Log::add(Text::sprintf('JLIB_INSTALLER_MINIMUM_JOOMLA', $this->minimumJoomla), Log::WARNING, 'jerror');

return false;
}

echo Text::_('MOD_FOO_INSTALLERSCRIPT_PREFLIGHT');
echo $this->minimumJoomla . ' ' . $this->minimumPhp;

return true;
}

/**
* Function called after extension installation/update/removal procedure commences
*
* @param string $type The type of change (install, update or discover_install, not uninstall)
* @param InstallerAdapter $parent The class calling this method
*
* @return boolean True on success
*/
function postflight($type, $parent) {
echo Text::_('MOD_FOO_INSTALLERSCRIPT_POSTFLIGHT');

return true;
}

}

</source>

<translate>
=== Editing language/en-GB/en-GB.mod_foo.sys.ini === 
</translate>
<translate> There is not much to explain here. Write the text for the translation into this file.</translate>

<translate>
==== Completed language/en-GB/en-GB.mod_foo.sys.ini file ==== 
</translate>
<translate> The complete <tt>language/en-GB/en-GB.mod_foo.sys.ini</tt> file is as follows:</translate>

<source lang="php">

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"
MOD_FOO_INSTALLERSCRIPT_PREFLIGHT="<p>Anything here happens before the installation/update/uninstallation of the module</p>"
MOD_FOO_INSTALLERSCRIPT_UPDATE="<p>The module has been updated</p>"
MOD_FOO_INSTALLERSCRIPT_UNINSTALL="<p>The module has been uninstalled</p>"
MOD_FOO_INSTALLERSCRIPT_INSTALL="<p>The module has been installed</p>"
MOD_FOO_INSTALLERSCRIPT_POSTFLIGHT="<p>Anything here happens after the installation/update/uninstallation of the module</p>"

</source>

<translate>
=== Editing mod_foo.xml === 
</translate>
<translate> You have to add a line, so that the script is called automatically in Joomla.</translate>

<source lang="xml"><scriptfile>script.php</scriptfile></source>

<translate>
==== Completed mod_foo.xml ==== 
</translate>
<translate> The complete <tt>mod_foo.xml</tt> file is as follows:</translate>

<source lang="xml">

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="4.0" client="site" method="upgrade">
<name>MOD_FOO</name>
<creationDate>[DATE]</creationDate>
<author>[AUTHOR]</author>
<authorEmail>[AUTHOR_EMAIL]</authorEmail>
<authorUrl>[AUTHOR_URL]</authorUrl>
<copyright>[COPYRIGHT]</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<version>1.0</version>
<description>MOD_FOO_XML_DESCRIPTION</description>
<namespace>Joomla\Module\Foo</namespace>
<scriptfile>script.php</scriptfile>
<files>
<filename module="mod_foo">mod_foo.php</filename>
<folder>tmpl</folder>
<folder>Helper</folder>
<folder>language</folder>
<filename>mod_foo.xml</filename>
</files>
<config>
<fields name="params">
<fieldset name="basic">
<field
name="domain"
type="url"
label="MOD_FOO_FIELD_URL_LABEL"
filter="url"
/>
</fieldset>
<fieldset name="advanced">
<field
name="layout"
type="modulelayout"
label="JFIELD_ALT_LAYOUT_LABEL"
class="custom-select"
/>

<field
name="moduleclass_sfx"
type="textarea"
label="COM_MODULES_FIELD_MODULECLASS_SFX_LABEL"
rows="3"
/>

<field
name="cache"
type="list"
label="COM_MODULES_FIELD_CACHING_LABEL"
default="0"
>
<option value="1">JGLOBAL_USE_GLOBAL</option>
<option value="0">COM_MODULES_FIELD_VALUE_NOCACHING</option>
</field>

<field
name="cache_time"
type="number"
label="COM_MODULES_FIELD_CACHE_TIME_LABEL"
default="0"
/>

<field
name="cachemode"
type="hidden"
default="itemid"
>
<option value="itemid"></option>
</field>
</fieldset>
</fields>
</config>
</extension>
</source>

<translate>
== Test your module == 
</translate>
<translate> Now you can zip all files and install them via the Joomla Extension Manager.</translate>
<translate> Immediately after the installation, you will see the following information. This you had entered in the script so.</translate>
{{-}}
[[File:moduletutorial14-<translate> en</translate>.png|700px|center]]

<translate>
== Conclusion == 
</translate>
<translate> As you can see, Joomla offers you a lot to make your extension easy to use - right from the start.</translate>

<translate> You can find boilerplates hereː</translate>
* https://github.com/joomla-extensions/boilerplate/tree/master/plugins/system
<translate> The sample files for this Tutorial can be found hereː</translate>
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

<translate>

== Use Joomla Updaterː Adding Auto Update - Part 5 == 
</translate>

<translate>
=== Requirements === 
</translate>
<translate> You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)</translate>

<translate>
=== Joomla Updater === 
</translate>
<translate> The first thing to do is to read the [[S:MyLanguage/J2.5:Managing_Component_Updates|Managing Component Upgrades with Joomla 2.5 - Part 1]] tutorial to give an idea of how the upgrade process works in Joomla. Whilst written for 2.5 the process hasn't changed. Also read [[S:MyLanguage/Deploying_an_Update_Server|Deploying an update server]] - this is what we'll be implementing in this tutorial.</translate>

<translate>
=== File Structure === 
</translate>
<translate> We will create/change the following files:</translate>
<translate> * <tt>mod_foo.xml</tt> - The only way to update our existing module is to add in a update server - for example <tt><nowiki>http://www.example.com/foo_update.xmɭ</nowiki></tt> - into the xml file.</translate>
<translate> * <tt>foo_update.xml</tt> - Then we have to create the XML file for the update server at <tt><nowiki>http://www.example.com/foo_update.xmɭ</nowiki></tt> to let Joomla know an update is available.</translate>

<translate>
==== Editing mod_foo.xml ==== 
</translate>
<translate> To add our update server, we need to insert the following lines in your XML-File</translate>

<source lang="php">

<updateservers>
<server type="extension" priority="1" name="[PROJECT_NAME]">https://www.example.com/mod_foo.xml</server>
</updateservers>

</source>

<translate>
==== Completed mod_foo.xml ==== 
</translate>
<translate> The complete <tt>mod_foo.xml</tt> file is as follows:</translate>

<source lang="xml">

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="4.0" client="site" method="upgrade">
<name>MOD_FOO</name>
<creationDate>[DATE]</creationDate>
<author>[AUTHOR]</author>
<authorEmail>[AUTHOR_EMAIL]</authorEmail>
<authorUrl>[AUTHOR_URL]</authorUrl>
<copyright>[COPYRIGHT]</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<version>1.0</version>
<description>MOD_FOO_XML_DESCRIPTION</description>
<namespace>Joomla\Module\Foo</namespace>
<files>
<filename module="mod_foo">mod_foo.php</filename>
<folder>tmpl</folder>
<folder>Helper</folder>
<folder>language</folder>
<filename>mod_foo.xml</filename>
</files>
<updateservers>
<server type="extension" priority="1" name="[PROJECT_NAME]">https://www.example.com/mod_foo.xml</server>
</updateservers>
<config>
<fields name="params">
<fieldset name="basic">
<field
name="domain"
type="url"
label="MOD_FOO_FIELD_URL_LABEL"
filter="url"
/>
</fieldset>
<fieldset name="advanced">
<field
name="layout"
type="modulelayout"
label="JFIELD_ALT_LAYOUT_LABEL"
class="custom-select"
/>

<field
name="moduleclass_sfx"
type="textarea"
label="COM_MODULES_FIELD_MODULECLASS_SFX_LABEL"
rows="3"
/>

<field
name="cache"
type="list"
label="COM_MODULES_FIELD_CACHING_LABEL"
default="0"
>
<option value="1">JGLOBAL_USE_GLOBAL</option>
<option value="0">COM_MODULES_FIELD_VALUE_NOCACHING</option>
</field>

<field
name="cache_time"
type="number"
label="COM_MODULES_FIELD_CACHE_TIME_LABEL"
default="0"
/>

<field
name="cachemode"
type="hidden"
default="itemid"
>
<option value="itemid"></option>
</field>
</fieldset>
</fields>
</config>
</extension>

</source>

<translate> So now that Joomla is searching for updates to our extension - let's create one to test out our process. But first we need to create the file <tt>foo_update.xml</tt>. So far we have only described the update server. We do not know yet if there is an update. In the file <tt>foo_update.xml</tt> we indicate when a new version is published and where it can be downloaded.</translate>

<translate>
=== Creating foo_update.xml === 
</translate>
<translate> Now we have to create the XML file at <tt><nowiki>http://www.example.com/foo_update.xml</nowiki></tt> to let Joomla know an update is available.</translate>

<translate>
==== Completed foo_update.xml ==== 
</translate>
<translate> The complete <tt>foo_update.xml</tt> file is as follows:</translate>

<source lang="xml">

<?xml version="1.0" ?>

<updates>
<update>
<name>Foo</name>
<description>This is mod_foo 1.0.1</description>
<element>mod_foo</element>
<type>module</type>
<version>1.0.1</version>
<downloads>
<downloadurl type="full" format="zip">http://www.example.com/mod_foo_101.zip</downloadurl>
</downloads>
<maintainer>Joomla</maintainer>
<maintainerurl>http://www.example.com</maintainerurl>
<targetplatform name="joomla" version="4.0"/>
<client>site</client>
</update>
</updates>

</source>

<translate> After uploading this file to the address <tt><nowiki>https://www.example.com/mod_foo.xml</nowiki></tt> the update will be displayed in the Joomla backend.</translate>

<translate>
=== Test your module update === 
</translate>
<translate> Create a copy of the module as it is now. Then let's update the version number to 1.0.1. Now you can zip all files. After that you should load your zip to the URL <tt><nowiki>http://www.example.com/mod_foo_101.zip</nowiki></tt>. Now you can update your module via the Joomla Updater.</translate>

<translate>
=== Commercial Modules === 
</translate>
<translate> Note that in our files we have linked to the extensions updates xml file. And from that xml file we have a location for the zip of the module. This means that if someone was to track this backwards they could find the physical source of your modules zip file. If you don't do like this, you can find a solution in this PRː https://github.com/joomla/joomla-cms/pull/15185 .</translate>

<translate>
=== Conclusion === 
</translate>
<translate> With the Joomla updater, you can easily reach all users and tell them that there is a new version. Even the update itself is easy.</translate>

<translate> Each extension should use an update server. Especially for security reasons.</translate>

<translate> You can find boilerplates hereː</translate>
* https://github.com/joomla-extensions/boilerplate/tree/master/plugins/system
<translate> The sample files for this Tutorial can be found hereː</translate>
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

<noinclude>
[[Category:Beginner Development{{#translation:}}]]
[[Category:Tutorials{{#translation:}}]]
[[Category:Tutorials in a Series{{#translation:}}]]
[[Category:Development{{#translation:}}]]
[[Category:Module Development{{#translation:}}]]
[[Category:Joomla! 4.x{{#translation:}}]]
[[Category:Joomla! 4.0{{#translation:}}]]
</noinclude>

J4.x:Creating a Simple Module

2019-06-21T06:59:50Z

Garkell: Changed to point to modules rather than plugin boilerplate

<noinclude><languages /></noinclude>
{{Joomla version|version=4.x|comment=><translate> Tutorial</translate>}}
{{-}}
{{Top portal heading|color=white-bkgd|icon=file-code-o|icon-color=#5091cd|size=5x|text-color=#333|title=<translate> Creating a Simple Module for Joomla 4.x</translate>}}
{{-}}

<translate> This is a tutorial on how to Create a simple module for Joomla Version 4x.</translate>
<translate>
== Introduction == 
</translate>
<translate> Joomlaǃ 4 provides five types of extensionsː</translate>
* '''[[S:MyLanguage/Component|<translate> Components</translate>]]'''<br /><translate> A component is the main part of the site. A component handles data manipulation as well as input and storage into the database. A component on most sites is the primary focus of the page.</translate>
* '''[[S:MyLanguage/Module|<translate> Modules</translate>]]''' <br /><translate> A module is an add-on to the site that extends the functionality. A module usually occupies a secondary portion of the web page and is not considered the primary focus of a page. It can be displayed on different positions and you can choose on which active menu items it should be displayed. Modules are lightweight and flexible extensions. They are used for small bits of the page that are generally less complex and are able to be seen across different components.</translate>
* '''[[S:MyLanguage/Plugin|<translate> Plugins</translate>]]'''<br /><translate> A Plugin manipulates output that is already generated by the system. It typically does not run as separate part of the site. It takes data from other sources (i.e. the content) and manipulates this data before displaying. A plugin typically work behind the scenes.</translate>
* '''[[S:MyLanguage/Languages|<translate> Languages</translate>]]'''<br />Probably the most basic extensions are languages. In essence the language package files consist of key/value pairs, which provide the translation of static text strings, assigned within the Joomla! source code.
* '''[[S:MyLanguage/Templates|<translate> Templates</translate>]]'''<br /><translate> A template is basically the design of your Joomla! powered website.</translate>

<translate> Joomla! 4 is constructed using five different applications:</translate>
<translate>
* Installation (used for installing Joomla and have to delete after installation)
* Administrator (backend - used for managing content)
* Public or site (frontend - used for displaying content)
* CLI (used for accessing Joomla on the command line and for cron jobs)
* API (web services - used for creating APIs for machine accessible content)</translate>
<translate>

The installation application is used once. The administrator and public are used through the concept of ''components'' with ''modules''. Each module has a single entry point located in the ''modules'' and accordingly ''administrator/modules'' directory. This entry point is called <tt>''mod_modulename/mod_modulename.php''</tt> (the ''mod_'' prefix is a historical trace). The entry point for the login module is for ''example /mod_login/mod_login.php''.</translate>

<translate>
=== Requirements === 
</translate>
<translate> You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)</translate>

<translate> You can download Joomla! 4 at [https://github.com/joomla/joomla-cms/tree/4.0-dev GitHub], on the [https://developer.joomla.org/nightly-builds.html Developer website] or you can create a free website at https://launch.joomla.org.</translate>

<translate>
== Creating a simple module/Developing a Basic Module - Part 1 == 
</translate>
<translate> You can see many examples of modules in the standard Joomla! install. For example:</translate>
<translate>
* Menus
* Latest News
* Login form
* and many more.</translate>

<translate> This tutorial will explain how to create a simple module. Through this tutorial you will learn the basic file structure of a Joomlaǃ 4 module. This basic structure can then be expanded to produce more elaborate modules.</translate>

<translate>
=== File Structure === 
</translate>
<translate> There are a few basic files that are used in the standard pattern of module development:</translate>
<translate> * <tt>mod_foo.php</tt> - This file is the main entry point for the module. It will perform any necessary initialization routines, call helper routines to collect any necessary data, and include the template which will display the module output.</translate>
<translate> * <tt>mod_foo.xml</tt> - This file contains information about the module. It defines the files that need to be installed by the Joomla! installer and specifies configuration parameters for the module.</translate>
<translate> * <tt>tmpl/default.php</tt> - This is the module template. This file will take the data collected by mod_foo.php and generate the HTML to be displayed on the page.</translate>
<translate> * <tt>language/en-GB/en-GB.mod_foo.ini</tt> and <tt>language/en-GB/en-GB.mod_foo.sys.ini</tt>- This are the files that provide the text in United Kingdom English.</translate>

<translate>
=== Creating mod_foo.php === 
</translate>
<translate> The <tt>mod_foo.php</tt> file will perform following tasks:</translate>
<translate> * Import the class <tt>ModuleHelper</tt> to the current scope. We need it later for displaying the output.</translate>
<translate> * Include the template to display the output.</translate>

<translate> The helper class is imported to our current scope at the begin of the file.</translate>

<source lang="php">use Joomla\CMS\Helper\ModuleHelper;</source>

<translate> Last we include the template to display the output via</translate>

<source lang="php">require ModuleHelper::getLayoutPath('mod_foo', $params->get('layout', 'default'));</source>

<translate>
==== Completed mod_foo.php file ==== 
</translate>
<translate> The complete <tt>mod_foo.php</tt> file is as follows:</translate>

<source lang="php">
<?php
/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/

use Joomla\CMS\Helper\ModuleHelper;

defined('_JEXEC') or die;

require ModuleHelper::getLayoutPath('mod_foo', $params->get('layout', 'default'));

</source>

<translate> ''Side note''ː In Joomla 3x you usually used a line like <tt>$moduleclass_sfx = htmlspecialchars($params->get('moduleclass_sfx'));</tt>. You don't need this anymore. See this PRː https://github.com/joomla/joomla-cms/pull/17447.</translate>

<translate> The one line that we haven’t explained so far is the first line <tt>defined('_JEXEC') or die;</tt>. This line checks to make sure that this file is being included from the Joomla application. This is necessary to prevent variable injection and other potential security concerns.</translate>

<translate>
=== Creating tmpl/default.php === 
</translate>
<translate> The <tt>default.php</tt> file is the template which displays the module output.</translate>

<translate>
==== Completed tmpl/default.php file ==== 
</translate>
<translate> The code for the tmpl/default.php file is as follows:</translate>

<source lang="php">
<?php
/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/

defined('_JEXEC') or die;

echo '[PROJECT_NAME]';

</source>

<translate> An important point to note is that the template file has the same scope as the <tt>mod_foo.php</tt> file. It means that a variable can be defined in the <tt>mod_foo.php</tt> file and then used in the template file without any extra declarations or function calls.</translate>

<translate>
=== Creating mod_foo.xml === 
</translate>
<translate> The <tt>mod_foo.xml</tt> file is the installation file. Most entries are self-explanatory.</translate>

<translate>
==== Completed mod_foo.xml file ==== 
</translate>
<translate> The code for the <tt>mod_foo.xml</tt> file is as follows:</translate>

<source lang="xml">

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.8" client="site" method="upgrade">
<name>MOD_FOO</name>
<creationDate>[DATE]</creationDate>
<author>[AUTHOR]</author>
<authorEmail>[AUTHOR_EMAIL]</authorEmail>
<authorUrl>[AUTHOR_URL]</authorUrl>
<copyright>[COPYRIGHT]</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<version>1.0</version>
<description>MOD_FOO_XML_DESCRIPTION</description>

<files>
<filename module="mod_foo">mod_foo.php</filename>
<folder>tmpl</folder>
<folder>language</folder>
<filename>mod_foo.xml</filename>
</files>

</extension>

</source>

<translate>
=== Creating the language files === 
</translate>
<translate> The files <tt>language/en-GB/en-GB.mod̠foo.ini</tt> and <tt>language/en-GB/en-GB.mod̠foo.sys.ini</tt> are used to translate text in the frontend and in the backend.</translate>

<translate> The code for <tt>language/en-GB/en-GB.mod̠foo.sys.ini</tt> is as follows:</translate>

<source lang="xml">

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"

</source>

<source lang="xml">

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"

</source>

<translate> The <tt>.sys.ini</tt> file is used to translate the description of the extension upon installation, where as the <tt>.ini</tt> file is used to translate the remaining strings and the description when viewing your extension.</translate>

<translate> More information about language files can be found [[S:MyLanguage/Specification_of_language_files|here]].</translate>

<translate>
== Test your module == 
</translate>
<translate> Now you can zip all files and install them via the Joomla Extension Manager.<br /></translate>
<translate> After that you can choose your module in the module manager, when you create a new site module.</translate>
{{-}}
[[File:moduletutorial1-<translate> en</translate>.png|700px|center]]
{{-}}
[[File:moduletutorial2-<translate> en</translate>.png|700px|center]]

<translate> In the frontend, you will see your module like displayed in the next image.</translate>
{{-}}
[[File:moduletutorial3-<translate> en</translate>.png|700px|center]]

<translate>
== Conclusion == 
</translate>
<translate> Module development for Joomla is a fairly simple, straightforward process. Using the techniques described in this tutorial, an endless variety of modules can be developed with little hassle.</translate>

<translate> You can find boilerplates hereː</translate>
* https://github.com/joomla-extensions/boilerplate/tree/master/module
<translate> The sample files for this Tutorial can be found hereː</translate>
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

<translate>

== Add a helper class using namespaces - Part 2== 
</translate>

<translate>
=== Requirements === 
</translate>
<translate> You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)</translate>

<translate>
== Namespaces == 
</translate>
<translate> With PHP 5.3, the namespaces came into their own. In other programming languages for a long time in use, these small structures now also help us with the clarity of our code.</translate>

<translate> Namespaces are separate areas in which certain logical things (in our case, classes, interfaces, functions, and constants) can live. These areas provide ncapsulation of the code and prevent name conflicts.</translate>

<translate> Let's take a look how to use them in Joomla 4. We use the helper file for this.</translate>

<translate>
=== File Structure === 
</translate>
<translate> We will create/change the following files:</translate>
<translate>
* <code>Helper/FooHelper.php</code> - This is the file we use here as an example. We have to create it.
* <code>mod_foo.php</code> - In this file we will mainly load the namespace.
* <code>tmpl/default.php</code> - In this file demonstrate how the data of a helper can be displayed.
* <code>mod_foo.xml</code> - We create a new directory with a new file. This must be installed during the installation. For this we have to specify them in this file.</translate>

<translate>
=== Creating Helper/FooHelper.php === 
</translate>
<translate> Our new helper class should belong to a namespace. We achieve this with the following code. It is important, that this line is at the beginning of the file.</translate>

<source lang="php">namespace Joomla\Module\Foo\Site\Helper;</source>

<translate> Then we create a simple class with a simple method. Of course you can do a lot more here. Take a look at the Joomla core methods. Here are many examples. They show you first-hand what options you have.</translate>

<translate>
==== Completed Helper/FooHelper.php ==== 
</translate>
<translate> The complete <tt>mod_foo.php</tt> file is as follows:</translate>

<source lang="php">

<?php
/**
* @package Joomla.Site
* @subpackage mod_foo
*
* @copyright Copyright (C) 2005 - 2018 Open Source Matters, Inc. All rights reserved.
* @license GNU General Public License version 2 or later; see LICENSE.txt
*/

namespace Joomla\Module\Foo\Site\Helper;

defined('_JEXEC') or die;

/**
* Helper for mod_foo
*
* @since 4.0
*/
class FooHelper
{
/**
* Retrieve foo test
*
* @param Registry $params The module parameters
* @param CMSApplication $app The application
*
* @return array
*/
public static function getText()
{
return 'FooHelpertest';
}
}

</source>

<translate>

=== Editing mod_foo.php === 
</translate>
<translate> Our new helper class is imported to our current scope at the begin of the file.</translate>

<source lang="php">use Joomla\Module\Foo\Site\Helper\FooHelper;</source>

<translate> Last use the helper file for testing if it is loaded correctlyː</translate>

<source lang="php">$test = FooHelper::getText($params, $app);</source>

<translate>
==== Completed mod_foo.php file ==== 
</translate>
<translate> The complete <tt>mod_foo.php</tt> file is as follows:</translate>

<source lang="php">

<?php
/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/

defined('_JEXEC') or die;

use Joomla\CMS\Helper\ModuleHelper;
use Joomla\Module\Foo\Site\Helper\FooHelper;

$test = FooHelper::getText();

require ModuleHelper::getLayoutPath('mod_foo', $params->get('layout', 'default'));

</source>

<translate>
=== Editing tmpl/default.php === 
</translate>
<translate> In this file you make only a small change to demonstrate in the frontend that your helper file is working properly. You only add the value of the variable at the end of the current output.</translate>

<source lang="php"><?php echo '[PROJECT_NAME]' . $test;</source>

<translate>
==== Completed tmpl/default.php ==== 
</translate>
<translate> The complete <tt>tmpl/default.php</tt> file is as follows:</translate>

<source lang="php">

<?php
/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/

defined('_JEXEC') or die;

?>

<?php echo '[PROJECT_NAME]' . $test;

</source>

<translate>
=== Editing mod_foo.xml === 
</translate>
<translate> First you have to add a line, so that the namespace is set automatically in Joomla. After this change, you have to re-install your module. A simple change in an already installed module is not enough. If you are doing local development you can also delete the files libraries/autoload_psr4.php and it will automatically be re-created. After inserting and installing, the namespace is known by the loader <tt>JPATH_LIBRARIES . '/autoload_psr4.php'</tt>.</translate>

<source lang="xml"><namespace>Joomla\Module\Foo</namespace></source>

<translate> Joomla! should copy your helper file when installing the module. So Joomla! needs to know your helper file. For this, you need to add the following line to your XML file.</translate>

<source lang="xml"><folder>Helper</folder></source>

<translate>
==== Completed mod_foo.xml ==== 
</translate>
<translate> The complete <tt>mod_foo.xml</tt> file is as follows:</translate>

<source lang="xml">

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.8" client="site" method="upgrade">
<name>MOD_FOO</name>
<creationDate>[DATE]</creationDate>
<author>[AUTHOR]</author>
<authorEmail>[AUTHOR_EMAIL]</authorEmail>
<authorUrl>[AUTHOR_URL]</authorUrl>
<copyright>[COPYRIGHT]</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<version>1.0</version>
<description>MOD_FOO_XML_DESCRIPTION</description>
<namespace>Joomla\Module\Foo</namespace>
<files>
<filename module="mod_foo">mod_foo.php</filename>
<folder>tmpl</folder>
<folder>Helper</folder>
<folder>language</folder>
<filename>mod_foo.xml</filename>
</files>

</extension>

</source>

<translate>
== Test your module == 
</translate>
<translate> Now you can zip all files and install them via the Joomla Extension Manager.</translate>
<translate> After that you can choose your module in the module manager, when you create a new site module.</translate>

<translate> In the frontend you will see your module like displayed in the next image. The text form your helper file is displayed.</translate>
{{-}}
[[File:moduletutorial23-<translate> en</translate>.png|700px|center]]

<translate>
== Conclusion == 
</translate>
<translate> As you can see, once you get a bit into the namespaces, they are not that complicated anymore. In big projects they can bring a lot of benefits. However, we should plan namespaces, as otherwise it will soon be more time-consuming.</translate>

<translate> You can find boilerplates hereː</translate>
* https://github.com/joomla-extensions/boilerplate/tree/master/module
<translate> The sample files for this Tutorial can be found hereː</translate>
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

<translate>

== Customizationː Add parameters via form fields - Part 3 == 
</translate>

<translate>
=== Requirements === 
</translate>
<translate> You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)</translate>

<translate>
== Customization with form fields and parameters == 
</translate>
<translate> Form fields give a great deal of customization in Joomla and for modules are the sole way of allowing the user to tweak the module to the needs of their site.</translate>

<translate> In this case we are going to extend our previous example using a url field for inserting a domain that we can use as link in the front end. To allow this to happen we will use the [[S:MyLanguage/URL_form_field_type|URL Form Field]] type.</translate>

<translate> After that, we insert parameters that allow to use standard functionality of Joomla.</translate>

<translate> Let's take a look on how to use them in Joomla 4.</translate>

<translate>
=== File Structure === 
</translate>
<translate> We will change the following files:</translate>
<translate>
* <tt>mod_foo.xml</tt> - This is the file where we add the fields.
* <tt>tmpl/default.php</tt> - In this file demonstrate how the data of a field can be used.
* <tt>language/en-GB/en-GB.mod_foo.ini</tt> - Here we use a language string so that the field can be labeled correctly in different languages.</translate>

<translate>
=== Editing mod_foo.xml === 
</translate>
<translate> First we set a custom parameter.</translate>

<source lang="xml">

<field
name="domain"
type="url"
label="MOD_FOO_FIELD_URL_LABEL"
filter="url"
/>

</source>

<translate> Then we insert Joomla default fields, so that we can use cache, moduleclass-suffix and layouts.</translate>

<source lang="xml">
<field
name="layout"
type="modulelayout"
label="JFIELD_ALT_LAYOUT_LABEL"
class="custom-select"
/>

<field
name="moduleclass_sfx"
type="textarea"
label="COM_MODULES_FIELD_MODULECLASS_SFX_LABEL"
rows="3"
/>

<field
name="cache"
type="list"
label="COM_MODULES_FIELD_CACHING_LABEL"
default="0"
>
<option value="1">JGLOBAL_USE_GLOBAL</option>
<option value="0">COM_MODULES_FIELD_VALUE_NOCACHING</option>
</field>

<field
name="cache_time"
type="number"
label="COM_MODULES_FIELD_CACHE_TIME_LABEL"
default="0"
/>

<field
name="cachemode"
type="hidden"
default="itemid"
>
<option value="itemid"></option>
</field>

</source>

<translate>
==== Completed mod_foo.xml ==== 
</translate>
<translate> The complete <tt>mod_foo.xml</tt> file is as follows:</translate>

<source lang="xml">

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.8" client="site" method="upgrade">
<name>MOD_FOO</name>
<creationDate>[DATE]</creationDate>
<author>[AUTHOR]</author>
<authorEmail>[AUTHOR_EMAIL]</authorEmail>
<authorUrl>[AUTHOR_URL]</authorUrl>
<copyright>[COPYRIGHT]</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<version>1.0</version>
<description>MOD_FOO_XML_DESCRIPTION</description>
<namespace>Joomla\Module\Foo</namespace>
<files>
<filename module="mod_foo">mod_foo.php</filename>
<folder>tmpl</folder>
<folder>Helper</folder>
<folder>language</folder>
<filename>mod_foo.xml</filename>
</files>
<config>
<fields name="params">
<fieldset name="basic">
<field
name="domain"
type="url"
label="MOD_FOO_FIELD_URL_LABEL"
filter="url"
/>
</fieldset>
<fieldset name="advanced">
<field
name="layout"
type="modulelayout"
label="JFIELD_ALT_LAYOUT_LABEL"
class="custom-select"
/>

<field
name="moduleclass_sfx"
type="textarea"
label="COM_MODULES_FIELD_MODULECLASS_SFX_LABEL"
rows="3"
/>

<field
name="cache"
type="list"
label="COM_MODULES_FIELD_CACHING_LABEL"
default="0"
>
<option value="1">JGLOBAL_USE_GLOBAL</option>
<option value="0">COM_MODULES_FIELD_VALUE_NOCACHING</option>
</field>

<field
name="cache_time"
type="number"
label="COM_MODULES_FIELD_CACHE_TIME_LABEL"
default="0"
/>

<field
name="cachemode"
type="hidden"
default="itemid"
>
<option value="itemid"></option>
</field>
</fieldset>
</fields>
</config>
</extension>

</source>

<translate>
=== Editing tmpl/default.php === 
</translate>
<translate> We can use the value of the parameter for creating an hyperlink in the frontend. We can access the value via the variable via the variable $params.</translate>

<source lang="php">$domain = $params->get('domain', 'https://www.joomla.org');</source>

<translate> Later we set use this value for creating the hyperlink.</translate>

<source lang="php">

<a href="<?php echo $domain; ?>">
<?php echo '[PROJECT_NAME]' . $test; ?>
</a>

</source>

<translate>
==== Completed tmpl/default.php file ==== 
</translate>
<translate> The complete <tt>tmpl/default.php</tt> file is as follows:</translate>

<source lang="php">

<?php
/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/

defined('_JEXEC') or die;

$domain = $params->get('domain', 'https://www.joomla.org');
?>

<a href="<?php echo $domain; ?>">
<?php echo '[PROJECT_NAME]' . $test; ?>
</a>

</source>

<translate>
=== Editing language/en-GB/en-GB.mod_foo.ini === 
</translate>
<translate> Here we can specify the text for the English version of the field label.</translate>

<source lang="php">MOD_FOO_FIELD_URL_LABEL="Url"</source>

<translate>
==== Completed language/en-GB/en-GB.mod_foo.ini ==== 
</translate>
<translate> The complete <tt>language/en-GB/en-GB.mod_foo.ini</tt> file is as follows:</translate>

<source lang="php">

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"
MOD_FOO_FIELD_URL_LABEL="Url"

</source>

<translate>
== Test your module == 
</translate>
<translate> Now you can zip all files and install them via the Joomla Extension Manager.</translate>
<translate> After that you can choose your module in the module manager, when you create a new site module.</translate>

<translate> In the backend, you will see your module like displayed in the next image.</translate>

<translate> In the basic tab, you will see the custom field where you can insert a domain. The text for the label is fetched from the language file.</translate>
{{-}}
[[File:moduletutorial31-<translate> en</translate>.png|700px|center]]

<translate> In the advanced tab, you will see all default options except the cache mode because of this is a hidden field.</translate>
{{-}}
[[File:moduletutorial32-<translate> en</translate>.png|700px|center]]

<translate> In the frontend, you will see your module like displayed in the next image. The text form your helper file is displayed and you should see a hyperlink.</translate>
{{-}}
[[File:moduletutorial33-<translate> en</translate>.png|700px|center]]

<translate>
== Conclusion == 
</translate>
<translate> Form fields give the user an easy way to customize the module to their sites settings. This allows the modules scope to be increased.</translate>

<translate> You can find boilerplates hereː</translate>
* https://github.com/joomla-extensions/boilerplate/tree/master/plugins/system
<translate> The sample files for this Tutorial can be found hereː</translate>
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules
<translate> See this issue for possible future changes:</translate>
* https://github.com/joomla/joomla-cms/pull/23553

<translate>

== Use Install, Update and Uninstall script - Part 4 == 
</translate>

<translate>
=== Requirements === 
</translate>
<translate> You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)</translate>

<translate>
=== Scripts === 
</translate>
<translate> Installing, updating and uninstalling a module may require additional operations that cannot be achieved by the basic operations described in the main XML file. Joomla offers a new approach to solve this problem. It consists in using a PHP script file containing a class using five methods:</translate>
<translate>
* preflight which is executed before install and update
* install
* update
* uninstall
* postflight which is executed after install and update</translate>

<translate> Let's take a look how to use them in Joomla 4. We use the helper file for this.</translate>

<translate>
=== File Structure === 
</translate>
<translate> We will create/change the following files:</translate>
<translate>
* <tt>script.php</tt> - This is the file we use here as an example. We have to create it.
* <tt>language/en-GB/en-GB.mod_foo.sys.ini</tt> - In this file we will add text.
* <tt>mod_foo.xml</tt> - We create a new file. This must be installed during the installation. For this we have to specify it in this file.</translate>

<translate>
=== Creating script.php === 
</translate>
<translate> Writing an extension script consists in declaring a class whose name is <tt>mod_ModuleNameInstallerScripʈ</tt> with these 5 methods. See the comments in the file for more information. In this comments I explain when a method is called.</translate>

<translate> In this example, I only use text to show when which method will be executed. In addition, I show you how to check the minimum requirements. Of course you can do much more. For example, you can delete files that are no longer needed in a new version of your module. This can be seen in the file. Another idea for this file is to create sample content, to show a success message with the current installed version number or you can redirect after a successful installation to the page with the module settings.</translate>

<translate>
==== Completed script.php ==== 
</translate>
<translate> The complete <tt>script.php</tt> file is as follows:</translate>

<source lang="php">

<?php

/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/
// No direct access to this file
defined('_JEXEC') or die;

use Joomla\CMS\Language\Text;
use Joomla\CMS\Log\Log;

/**
* Script file of Foo module
*/
class mod_fooInstallerScript {

/**
* Extension script constructor.
*
* @return void
*/
public function __construct() {
$this->minimumJoomla = '4.0';
$this->minimumPhp = JOOMLA_MINIMUM_PHP;
}

/**
* Method to install the extension
*
* @param InstallerAdapter $parent The class calling this method
*
* @return boolean True on success
*/
function install($parent) {
echo Text::_('MOD_FOO_INSTALLERSCRIPT_UNINSTALL');

return true;
}

/**
* Method to uninstall the extension
*
* @param InstallerAdapter $parent The class calling this method
*
* @return boolean True on success
*/
function uninstall($parent) {
echo Text::_('MOD_FOO_INSTALLERSCRIPT_UNINSTALL');

return true;
}

/**
* Method to update the extension
*
* @param InstallerAdapter $parent The class calling this method
*
* @return boolean True on success
*/
function update($parent) {
echo Text::_('MOD_FOO_INSTALLERSCRIPT_UPDATE');

return true;
}

/**
* Function called before extension installation/update/removal procedure commences
*
* @param string $type The type of change (install, update or discover_install, not uninstall)
* @param InstallerAdapter $parent The class calling this method
*
* @return boolean True on success
*/
function preflight($type, $parent) {
// Check for the minimum PHP version before continuing
if (!empty($this->minimumPhp) && version_compare(PHP_VERSION, $this->minimumPhp, '<')) {
Log::add(Text::sprintf('JLIB_INSTALLER_MINIMUM_PHP', $this->minimumPhp), Log::WARNING, 'jerror');

return false;
}

// Check for the minimum Joomla version before continuing
if (!empty($this->minimumJoomla) && version_compare(JVERSION, $this->minimumJoomla, '<')) {
Log::add(Text::sprintf('JLIB_INSTALLER_MINIMUM_JOOMLA', $this->minimumJoomla), Log::WARNING, 'jerror');

return false;
}

echo Text::_('MOD_FOO_INSTALLERSCRIPT_PREFLIGHT');
echo $this->minimumJoomla . ' ' . $this->minimumPhp;

return true;
}

/**
* Function called after extension installation/update/removal procedure commences
*
* @param string $type The type of change (install, update or discover_install, not uninstall)
* @param InstallerAdapter $parent The class calling this method
*
* @return boolean True on success
*/
function postflight($type, $parent) {
echo Text::_('MOD_FOO_INSTALLERSCRIPT_POSTFLIGHT');

return true;
}

}

</source>

<translate>
=== Editing language/en-GB/en-GB.mod_foo.sys.ini === 
</translate>
<translate> There is not much to explain here. Write the text for the translation into this file.</translate>

<translate>
==== Completed language/en-GB/en-GB.mod_foo.sys.ini file ==== 
</translate>
<translate> The complete <tt>language/en-GB/en-GB.mod_foo.sys.ini</tt> file is as follows:</translate>

<source lang="php">

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"
MOD_FOO_INSTALLERSCRIPT_PREFLIGHT="<p>Anything here happens before the installation/update/uninstallation of the module</p>"
MOD_FOO_INSTALLERSCRIPT_UPDATE="<p>The module has been updated</p>"
MOD_FOO_INSTALLERSCRIPT_UNINSTALL="<p>The module has been uninstalled</p>"
MOD_FOO_INSTALLERSCRIPT_INSTALL="<p>The module has been installed</p>"
MOD_FOO_INSTALLERSCRIPT_POSTFLIGHT="<p>Anything here happens after the installation/update/uninstallation of the module</p>"

</source>

<translate>
=== Editing mod_foo.xml === 
</translate>
<translate> You have to add a line, so that the script is called automatically in Joomla.</translate>

<source lang="xml"><scriptfile>script.php</scriptfile></source>

<translate>
==== Completed mod_foo.xml ==== 
</translate>
<translate> The complete <tt>mod_foo.xml</tt> file is as follows:</translate>

<source lang="xml">

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="4.0" client="site" method="upgrade">
<name>MOD_FOO</name>
<creationDate>[DATE]</creationDate>
<author>[AUTHOR]</author>
<authorEmail>[AUTHOR_EMAIL]</authorEmail>
<authorUrl>[AUTHOR_URL]</authorUrl>
<copyright>[COPYRIGHT]</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<version>1.0</version>
<description>MOD_FOO_XML_DESCRIPTION</description>
<namespace>Joomla\Module\Foo</namespace>
<scriptfile>script.php</scriptfile>
<files>
<filename module="mod_foo">mod_foo.php</filename>
<folder>tmpl</folder>
<folder>Helper</folder>
<folder>language</folder>
<filename>mod_foo.xml</filename>
</files>
<config>
<fields name="params">
<fieldset name="basic">
<field
name="domain"
type="url"
label="MOD_FOO_FIELD_URL_LABEL"
filter="url"
/>
</fieldset>
<fieldset name="advanced">
<field
name="layout"
type="modulelayout"
label="JFIELD_ALT_LAYOUT_LABEL"
class="custom-select"
/>

<field
name="moduleclass_sfx"
type="textarea"
label="COM_MODULES_FIELD_MODULECLASS_SFX_LABEL"
rows="3"
/>

<field
name="cache"
type="list"
label="COM_MODULES_FIELD_CACHING_LABEL"
default="0"
>
<option value="1">JGLOBAL_USE_GLOBAL</option>
<option value="0">COM_MODULES_FIELD_VALUE_NOCACHING</option>
</field>

<field
name="cache_time"
type="number"
label="COM_MODULES_FIELD_CACHE_TIME_LABEL"
default="0"
/>

<field
name="cachemode"
type="hidden"
default="itemid"
>
<option value="itemid"></option>
</field>
</fieldset>
</fields>
</config>
</extension>
</source>

<translate>
== Test your module == 
</translate>
<translate> Now you can zip all files and install them via the Joomla Extension Manager.</translate>
<translate> Immediately after the installation, you will see the following information. This you had entered in the script so.</translate>
{{-}}
[[File:moduletutorial14-<translate> en</translate>.png|700px|center]]

<translate>
== Conclusion == 
</translate>
<translate> As you can see, Joomla offers you a lot to make your extension easy to use - right from the start.</translate>

<translate> You can find boilerplates hereː</translate>
* https://github.com/joomla-extensions/boilerplate/tree/master/plugins/system
<translate> The sample files for this Tutorial can be found hereː</translate>
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

<translate>

== Use Joomla Updaterː Adding Auto Update - Part 5 == 
</translate>

<translate>
=== Requirements === 
</translate>
<translate> You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)</translate>

<translate>
=== Joomla Updater === 
</translate>
<translate> The first thing to do is to read the [[S:MyLanguage/J2.5:Managing_Component_Updates|Managing Component Upgrades with Joomla 2.5 - Part 1]] tutorial to give an idea of how the upgrade process works in Joomla. Whilst written for 2.5 the process hasn't changed. Also read [[S:MyLanguage/Deploying_an_Update_Server|Deploying an update server]] - this is what we'll be implementing in this tutorial.</translate>

<translate>
=== File Structure === 
</translate>
<translate> We will create/change the following files:</translate>
<translate> * <tt>mod_foo.xml</tt> - The only way to update our existing module is to add in a update server - for example <tt><nowiki>http://www.example.com/foo_update.xmɭ</nowiki></tt> - into the xml file.</translate>
<translate> * <tt>foo_update.xml</tt> - Then we have to create the XML file for the update server at <tt><nowiki>http://www.example.com/foo_update.xmɭ</nowiki></tt> to let Joomla know an update is available.</translate>

<translate>
==== Editing mod_foo.xml ==== 
</translate>
<translate> To add our update server, we need to insert the following lines in your XML-File</translate>

<source lang="php">

<updateservers>
<server type="extension" priority="1" name="[PROJECT_NAME]">https://www.example.com/mod_foo.xml</server>
</updateservers>

</source>

<translate>
==== Completed mod_foo.xml ==== 
</translate>
<translate> The complete <tt>mod_foo.xml</tt> file is as follows:</translate>

<source lang="xml">

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="4.0" client="site" method="upgrade">
<name>MOD_FOO</name>
<creationDate>[DATE]</creationDate>
<author>[AUTHOR]</author>
<authorEmail>[AUTHOR_EMAIL]</authorEmail>
<authorUrl>[AUTHOR_URL]</authorUrl>
<copyright>[COPYRIGHT]</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<version>1.0</version>
<description>MOD_FOO_XML_DESCRIPTION</description>
<namespace>Joomla\Module\Foo</namespace>
<files>
<filename module="mod_foo">mod_foo.php</filename>
<folder>tmpl</folder>
<folder>Helper</folder>
<folder>language</folder>
<filename>mod_foo.xml</filename>
</files>
<updateservers>
<server type="extension" priority="1" name="[PROJECT_NAME]">https://www.example.com/mod_foo.xml</server>
</updateservers>
<config>
<fields name="params">
<fieldset name="basic">
<field
name="domain"
type="url"
label="MOD_FOO_FIELD_URL_LABEL"
filter="url"
/>
</fieldset>
<fieldset name="advanced">
<field
name="layout"
type="modulelayout"
label="JFIELD_ALT_LAYOUT_LABEL"
class="custom-select"
/>

<field
name="moduleclass_sfx"
type="textarea"
label="COM_MODULES_FIELD_MODULECLASS_SFX_LABEL"
rows="3"
/>

<field
name="cache"
type="list"
label="COM_MODULES_FIELD_CACHING_LABEL"
default="0"
>
<option value="1">JGLOBAL_USE_GLOBAL</option>
<option value="0">COM_MODULES_FIELD_VALUE_NOCACHING</option>
</field>

<field
name="cache_time"
type="number"
label="COM_MODULES_FIELD_CACHE_TIME_LABEL"
default="0"
/>

<field
name="cachemode"
type="hidden"
default="itemid"
>
<option value="itemid"></option>
</field>
</fieldset>
</fields>
</config>
</extension>

</source>

<translate> So now that Joomla is searching for updates to our extension - let's create one to test out our process. But first we need to create the file <tt>foo_update.xml</tt>. So far we have only described the update server. We do not know yet if there is an update. In the file <tt>foo_update.xml</tt> we indicate when a new version is published and where it can be downloaded.</translate>

<translate>
=== Creating foo_update.xml === 
</translate>
<translate> Now we have to create the XML file at <tt><nowiki>http://www.example.com/foo_update.xml</nowiki></tt> to let Joomla know an update is available.</translate>

<translate>
==== Completed foo_update.xml ==== 
</translate>
<translate> The complete <tt>foo_update.xml</tt> file is as follows:</translate>

<source lang="xml">

<?xml version="1.0" ?>

<updates>
<update>
<name>Foo</name>
<description>This is mod_foo 1.0.1</description>
<element>mod_foo</element>
<type>module</type>
<version>1.0.1</version>
<downloads>
<downloadurl type="full" format="zip">http://www.example.com/mod_foo_101.zip</downloadurl>
</downloads>
<maintainer>Joomla</maintainer>
<maintainerurl>http://www.example.com</maintainerurl>
<targetplatform name="joomla" version="4.0"/>
<client>site</client>
</update>
</updates>

</source>

<translate> After uploading this file to the address <tt><nowiki>https://www.example.com/mod_foo.xml</nowiki></tt> the update will be displayed in the Joomla backend.</translate>

<translate>
=== Test your module update === 
</translate>
<translate> Create a copy of the module as it is now. Then let's update the version number to 1.0.1. Now you can zip all files. After that you should load your zip to the URL <tt><nowiki>http://www.example.com/mod_foo_101.zip</nowiki></tt>. Now you can update your module via the Joomla Updater.</translate>

<translate>
=== Commercial Modules === 
</translate>
<translate> Note that in our files we have linked to the extensions updates xml file. And from that xml file we have a location for the zip of the module. This means that if someone was to track this backwards they could find the physical source of your modules zip file. If you don't do like this, you can find a solution in this PRː https://github.com/joomla/joomla-cms/pull/15185 .</translate>

<translate>
=== Conclusion === 
</translate>
<translate> With the Joomla updater, you can easily reach all users and tell them that there is a new version. Even the update itself is easy.</translate>

<translate> Each extension should use an update server. Especially for security reasons.</translate>

<translate> You can find boilerplates hereː</translate>
* https://github.com/joomla-extensions/boilerplate/tree/master/plugins/system
<translate> The sample files for this Tutorial can be found hereː</translate>
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

<noinclude>
[[Category:Beginner Development{{#translation:}}]]
[[Category:Tutorials{{#translation:}}]]
[[Category:Tutorials in a Series{{#translation:}}]]
[[Category:Development{{#translation:}}]]
[[Category:Module Development{{#translation:}}]]
[[Category:Joomla! 4.x{{#translation:}}]]
[[Category:Joomla! 4.0{{#translation:}}]]
</noinclude>

J4.x:Creating a Simple Module

2019-06-21T06:58:02Z

Garkell: Change mod_breadcrumbs to mod_foo in comment

<noinclude><languages /></noinclude>
{{Joomla version|version=4.x|comment=><translate> Tutorial</translate>}}
{{-}}
{{Top portal heading|color=white-bkgd|icon=file-code-o|icon-color=#5091cd|size=5x|text-color=#333|title=<translate> Creating a Simple Module for Joomla 4.x</translate>}}
{{-}}

<translate> This is a tutorial on how to Create a simple module for Joomla Version 4x.</translate>
<translate>
== Introduction == 
</translate>
<translate> Joomlaǃ 4 provides five types of extensionsː</translate>
* '''[[S:MyLanguage/Component|<translate> Components</translate>]]'''<br /><translate> A component is the main part of the site. A component handles data manipulation as well as input and storage into the database. A component on most sites is the primary focus of the page.</translate>
* '''[[S:MyLanguage/Module|<translate> Modules</translate>]]''' <br /><translate> A module is an add-on to the site that extends the functionality. A module usually occupies a secondary portion of the web page and is not considered the primary focus of a page. It can be displayed on different positions and you can choose on which active menu items it should be displayed. Modules are lightweight and flexible extensions. They are used for small bits of the page that are generally less complex and are able to be seen across different components.</translate>
* '''[[S:MyLanguage/Plugin|<translate> Plugins</translate>]]'''<br /><translate> A Plugin manipulates output that is already generated by the system. It typically does not run as separate part of the site. It takes data from other sources (i.e. the content) and manipulates this data before displaying. A plugin typically work behind the scenes.</translate>
* '''[[S:MyLanguage/Languages|<translate> Languages</translate>]]'''<br />Probably the most basic extensions are languages. In essence the language package files consist of key/value pairs, which provide the translation of static text strings, assigned within the Joomla! source code.
* '''[[S:MyLanguage/Templates|<translate> Templates</translate>]]'''<br /><translate> A template is basically the design of your Joomla! powered website.</translate>

<translate> Joomla! 4 is constructed using five different applications:</translate>
<translate>
* Installation (used for installing Joomla and have to delete after installation)
* Administrator (backend - used for managing content)
* Public or site (frontend - used for displaying content)
* CLI (used for accessing Joomla on the command line and for cron jobs)
* API (web services - used for creating APIs for machine accessible content)</translate>
<translate>

The installation application is used once. The administrator and public are used through the concept of ''components'' with ''modules''. Each module has a single entry point located in the ''modules'' and accordingly ''administrator/modules'' directory. This entry point is called <tt>''mod_modulename/mod_modulename.php''</tt> (the ''mod_'' prefix is a historical trace). The entry point for the login module is for ''example /mod_login/mod_login.php''.</translate>

<translate>
=== Requirements === 
</translate>
<translate> You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)</translate>

<translate> You can download Joomla! 4 at [https://github.com/joomla/joomla-cms/tree/4.0-dev GitHub], on the [https://developer.joomla.org/nightly-builds.html Developer website] or you can create a free website at https://launch.joomla.org.</translate>

<translate>
== Creating a simple module/Developing a Basic Module - Part 1 == 
</translate>
<translate> You can see many examples of modules in the standard Joomla! install. For example:</translate>
<translate>
* Menus
* Latest News
* Login form
* and many more.</translate>

<translate> This tutorial will explain how to create a simple module. Through this tutorial you will learn the basic file structure of a Joomlaǃ 4 module. This basic structure can then be expanded to produce more elaborate modules.</translate>

<translate>
=== File Structure === 
</translate>
<translate> There are a few basic files that are used in the standard pattern of module development:</translate>
<translate> * <tt>mod_foo.php</tt> - This file is the main entry point for the module. It will perform any necessary initialization routines, call helper routines to collect any necessary data, and include the template which will display the module output.</translate>
<translate> * <tt>mod_foo.xml</tt> - This file contains information about the module. It defines the files that need to be installed by the Joomla! installer and specifies configuration parameters for the module.</translate>
<translate> * <tt>tmpl/default.php</tt> - This is the module template. This file will take the data collected by mod_foo.php and generate the HTML to be displayed on the page.</translate>
<translate> * <tt>language/en-GB/en-GB.mod_foo.ini</tt> and <tt>language/en-GB/en-GB.mod_foo.sys.ini</tt>- This are the files that provide the text in United Kingdom English.</translate>

<translate>
=== Creating mod_foo.php === 
</translate>
<translate> The <tt>mod_foo.php</tt> file will perform following tasks:</translate>
<translate> * Import the class <tt>ModuleHelper</tt> to the current scope. We need it later for displaying the output.</translate>
<translate> * Include the template to display the output.</translate>

<translate> The helper class is imported to our current scope at the begin of the file.</translate>

<source lang="php">use Joomla\CMS\Helper\ModuleHelper;</source>

<translate> Last we include the template to display the output via</translate>

<source lang="php">require ModuleHelper::getLayoutPath('mod_foo', $params->get('layout', 'default'));</source>

<translate>
==== Completed mod_foo.php file ==== 
</translate>
<translate> The complete <tt>mod_foo.php</tt> file is as follows:</translate>

<source lang="php">
<?php
/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/

use Joomla\CMS\Helper\ModuleHelper;

defined('_JEXEC') or die;

require ModuleHelper::getLayoutPath('mod_foo', $params->get('layout', 'default'));

</source>

<translate> ''Side note''ː In Joomla 3x you usually used a line like <tt>$moduleclass_sfx = htmlspecialchars($params->get('moduleclass_sfx'));</tt>. You don't need this anymore. See this PRː https://github.com/joomla/joomla-cms/pull/17447.</translate>

<translate> The one line that we haven’t explained so far is the first line <tt>defined('_JEXEC') or die;</tt>. This line checks to make sure that this file is being included from the Joomla application. This is necessary to prevent variable injection and other potential security concerns.</translate>

<translate>
=== Creating tmpl/default.php === 
</translate>
<translate> The <tt>default.php</tt> file is the template which displays the module output.</translate>

<translate>
==== Completed tmpl/default.php file ==== 
</translate>
<translate> The code for the tmpl/default.php file is as follows:</translate>

<source lang="php">
<?php
/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/

defined('_JEXEC') or die;

echo '[PROJECT_NAME]';

</source>

<translate> An important point to note is that the template file has the same scope as the <tt>mod_foo.php</tt> file. It means that a variable can be defined in the <tt>mod_foo.php</tt> file and then used in the template file without any extra declarations or function calls.</translate>

<translate>
=== Creating mod_foo.xml === 
</translate>
<translate> The <tt>mod_foo.xml</tt> file is the installation file. Most entries are self-explanatory.</translate>

<translate>
==== Completed mod_foo.xml file ==== 
</translate>
<translate> The code for the <tt>mod_foo.xml</tt> file is as follows:</translate>

<source lang="xml">

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.8" client="site" method="upgrade">
<name>MOD_FOO</name>
<creationDate>[DATE]</creationDate>
<author>[AUTHOR]</author>
<authorEmail>[AUTHOR_EMAIL]</authorEmail>
<authorUrl>[AUTHOR_URL]</authorUrl>
<copyright>[COPYRIGHT]</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<version>1.0</version>
<description>MOD_FOO_XML_DESCRIPTION</description>

<files>
<filename module="mod_foo">mod_foo.php</filename>
<folder>tmpl</folder>
<folder>language</folder>
<filename>mod_foo.xml</filename>
</files>

</extension>

</source>

<translate>
=== Creating the language files === 
</translate>
<translate> The files <tt>language/en-GB/en-GB.mod̠foo.ini</tt> and <tt>language/en-GB/en-GB.mod̠foo.sys.ini</tt> are used to translate text in the frontend and in the backend.</translate>

<translate> The code for <tt>language/en-GB/en-GB.mod̠foo.sys.ini</tt> is as follows:</translate>

<source lang="xml">

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"

</source>

<source lang="xml">

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"

</source>

<translate> The <tt>.sys.ini</tt> file is used to translate the description of the extension upon installation, where as the <tt>.ini</tt> file is used to translate the remaining strings and the description when viewing your extension.</translate>

<translate> More information about language files can be found [[S:MyLanguage/Specification_of_language_files|here]].</translate>

<translate>
== Test your module == 
</translate>
<translate> Now you can zip all files and install them via the Joomla Extension Manager.<br /></translate>
<translate> After that you can choose your module in the module manager, when you create a new site module.</translate>
{{-}}
[[File:moduletutorial1-<translate> en</translate>.png|700px|center]]
{{-}}
[[File:moduletutorial2-<translate> en</translate>.png|700px|center]]

<translate> In the frontend, you will see your module like displayed in the next image.</translate>
{{-}}
[[File:moduletutorial3-<translate> en</translate>.png|700px|center]]

<translate>
== Conclusion == 
</translate>
<translate> Module development for Joomla is a fairly simple, straightforward process. Using the techniques described in this tutorial, an endless variety of modules can be developed with little hassle.</translate>

<translate> You can find boilerplates hereː</translate>
* https://github.com/joomla-extensions/boilerplate/tree/master/module
<translate> The sample files for this Tutorial can be found hereː</translate>
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

<translate>

== Add a helper class using namespaces - Part 2== 
</translate>

<translate>
=== Requirements === 
</translate>
<translate> You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)</translate>

<translate>
== Namespaces == 
</translate>
<translate> With PHP 5.3, the namespaces came into their own. In other programming languages for a long time in use, these small structures now also help us with the clarity of our code.</translate>

<translate> Namespaces are separate areas in which certain logical things (in our case, classes, interfaces, functions, and constants) can live. These areas provide ncapsulation of the code and prevent name conflicts.</translate>

<translate> Let's take a look how to use them in Joomla 4. We use the helper file for this.</translate>

<translate>
=== File Structure === 
</translate>
<translate> We will create/change the following files:</translate>
<translate>
* <code>Helper/FooHelper.php</code> - This is the file we use here as an example. We have to create it.
* <code>mod_foo.php</code> - In this file we will mainly load the namespace.
* <code>tmpl/default.php</code> - In this file demonstrate how the data of a helper can be displayed.
* <code>mod_foo.xml</code> - We create a new directory with a new file. This must be installed during the installation. For this we have to specify them in this file.</translate>

<translate>
=== Creating Helper/FooHelper.php === 
</translate>
<translate> Our new helper class should belong to a namespace. We achieve this with the following code. It is important, that this line is at the beginning of the file.</translate>

<source lang="php">namespace Joomla\Module\Foo\Site\Helper;</source>

<translate> Then we create a simple class with a simple method. Of course you can do a lot more here. Take a look at the Joomla core methods. Here are many examples. They show you first-hand what options you have.</translate>

<translate>
==== Completed Helper/FooHelper.php ==== 
</translate>
<translate> The complete <tt>mod_foo.php</tt> file is as follows:</translate>

<source lang="php">

<?php
/**
* @package Joomla.Site
* @subpackage mod_foo
*
* @copyright Copyright (C) 2005 - 2018 Open Source Matters, Inc. All rights reserved.
* @license GNU General Public License version 2 or later; see LICENSE.txt
*/

namespace Joomla\Module\Foo\Site\Helper;

defined('_JEXEC') or die;

/**
* Helper for mod_foo
*
* @since 4.0
*/
class FooHelper
{
/**
* Retrieve foo test
*
* @param Registry $params The module parameters
* @param CMSApplication $app The application
*
* @return array
*/
public static function getText()
{
return 'FooHelpertest';
}
}

</source>

<translate>

=== Editing mod_foo.php === 
</translate>
<translate> Our new helper class is imported to our current scope at the begin of the file.</translate>

<source lang="php">use Joomla\Module\Foo\Site\Helper\FooHelper;</source>

<translate> Last use the helper file for testing if it is loaded correctlyː</translate>

<source lang="php">$test = FooHelper::getText($params, $app);</source>

<translate>
==== Completed mod_foo.php file ==== 
</translate>
<translate> The complete <tt>mod_foo.php</tt> file is as follows:</translate>

<source lang="php">

<?php
/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/

defined('_JEXEC') or die;

use Joomla\CMS\Helper\ModuleHelper;
use Joomla\Module\Foo\Site\Helper\FooHelper;

$test = FooHelper::getText();

require ModuleHelper::getLayoutPath('mod_foo', $params->get('layout', 'default'));

</source>

<translate>
=== Editing tmpl/default.php === 
</translate>
<translate> In this file you make only a small change to demonstrate in the frontend that your helper file is working properly. You only add the value of the variable at the end of the current output.</translate>

<source lang="php"><?php echo '[PROJECT_NAME]' . $test;</source>

<translate>
==== Completed tmpl/default.php ==== 
</translate>
<translate> The complete <tt>tmpl/default.php</tt> file is as follows:</translate>

<source lang="php">

<?php
/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/

defined('_JEXEC') or die;

?>

<?php echo '[PROJECT_NAME]' . $test;

</source>

<translate>
=== Editing mod_foo.xml === 
</translate>
<translate> First you have to add a line, so that the namespace is set automatically in Joomla. After this change, you have to re-install your module. A simple change in an already installed module is not enough. If you are doing local development you can also delete the files libraries/autoload_psr4.php and it will automatically be re-created. After inserting and installing, the namespace is known by the loader <tt>JPATH_LIBRARIES . '/autoload_psr4.php'</tt>.</translate>

<source lang="xml"><namespace>Joomla\Module\Foo</namespace></source>

<translate> Joomla! should copy your helper file when installing the module. So Joomla! needs to know your helper file. For this, you need to add the following line to your XML file.</translate>

<source lang="xml"><folder>Helper</folder></source>

<translate>
==== Completed mod_foo.xml ==== 
</translate>
<translate> The complete <tt>mod_foo.xml</tt> file is as follows:</translate>

<source lang="xml">

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.8" client="site" method="upgrade">
<name>MOD_FOO</name>
<creationDate>[DATE]</creationDate>
<author>[AUTHOR]</author>
<authorEmail>[AUTHOR_EMAIL]</authorEmail>
<authorUrl>[AUTHOR_URL]</authorUrl>
<copyright>[COPYRIGHT]</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<version>1.0</version>
<description>MOD_FOO_XML_DESCRIPTION</description>
<namespace>Joomla\Module\Foo</namespace>
<files>
<filename module="mod_foo">mod_foo.php</filename>
<folder>tmpl</folder>
<folder>Helper</folder>
<folder>language</folder>
<filename>mod_foo.xml</filename>
</files>

</extension>

</source>

<translate>
== Test your module == 
</translate>
<translate> Now you can zip all files and install them via the Joomla Extension Manager.</translate>
<translate> After that you can choose your module in the module manager, when you create a new site module.</translate>

<translate> In the frontend you will see your module like displayed in the next image. The text form your helper file is displayed.</translate>
{{-}}
[[File:moduletutorial23-<translate> en</translate>.png|700px|center]]

<translate>
== Conclusion == 
</translate>
<translate> As you can see, once you get a bit into the namespaces, they are not that complicated anymore. In big projects they can bring a lot of benefits. However, we should plan namespaces, as otherwise it will soon be more time-consuming.</translate>

<translate> You can find boilerplates hereː</translate>
* https://github.com/joomla-extensions/boilerplate/tree/master/plugins/system
<translate> The sample files for this Tutorial can be found hereː</translate>
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

<translate>

== Customizationː Add parameters via form fields - Part 3 == 
</translate>

<translate>
=== Requirements === 
</translate>
<translate> You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)</translate>

<translate>
== Customization with form fields and parameters == 
</translate>
<translate> Form fields give a great deal of customization in Joomla and for modules are the sole way of allowing the user to tweak the module to the needs of their site.</translate>

<translate> In this case we are going to extend our previous example using a url field for inserting a domain that we can use as link in the front end. To allow this to happen we will use the [[S:MyLanguage/URL_form_field_type|URL Form Field]] type.</translate>

<translate> After that, we insert parameters that allow to use standard functionality of Joomla.</translate>

<translate> Let's take a look on how to use them in Joomla 4.</translate>

<translate>
=== File Structure === 
</translate>
<translate> We will change the following files:</translate>
<translate>
* <tt>mod_foo.xml</tt> - This is the file where we add the fields.
* <tt>tmpl/default.php</tt> - In this file demonstrate how the data of a field can be used.
* <tt>language/en-GB/en-GB.mod_foo.ini</tt> - Here we use a language string so that the field can be labeled correctly in different languages.</translate>

<translate>
=== Editing mod_foo.xml === 
</translate>
<translate> First we set a custom parameter.</translate>

<source lang="xml">

<field
name="domain"
type="url"
label="MOD_FOO_FIELD_URL_LABEL"
filter="url"
/>

</source>

<translate> Then we insert Joomla default fields, so that we can use cache, moduleclass-suffix and layouts.</translate>

<source lang="xml">
<field
name="layout"
type="modulelayout"
label="JFIELD_ALT_LAYOUT_LABEL"
class="custom-select"
/>

<field
name="moduleclass_sfx"
type="textarea"
label="COM_MODULES_FIELD_MODULECLASS_SFX_LABEL"
rows="3"
/>

<field
name="cache"
type="list"
label="COM_MODULES_FIELD_CACHING_LABEL"
default="0"
>
<option value="1">JGLOBAL_USE_GLOBAL</option>
<option value="0">COM_MODULES_FIELD_VALUE_NOCACHING</option>
</field>

<field
name="cache_time"
type="number"
label="COM_MODULES_FIELD_CACHE_TIME_LABEL"
default="0"
/>

<field
name="cachemode"
type="hidden"
default="itemid"
>
<option value="itemid"></option>
</field>

</source>

<translate>
==== Completed mod_foo.xml ==== 
</translate>
<translate> The complete <tt>mod_foo.xml</tt> file is as follows:</translate>

<source lang="xml">

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.8" client="site" method="upgrade">
<name>MOD_FOO</name>
<creationDate>[DATE]</creationDate>
<author>[AUTHOR]</author>
<authorEmail>[AUTHOR_EMAIL]</authorEmail>
<authorUrl>[AUTHOR_URL]</authorUrl>
<copyright>[COPYRIGHT]</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<version>1.0</version>
<description>MOD_FOO_XML_DESCRIPTION</description>
<namespace>Joomla\Module\Foo</namespace>
<files>
<filename module="mod_foo">mod_foo.php</filename>
<folder>tmpl</folder>
<folder>Helper</folder>
<folder>language</folder>
<filename>mod_foo.xml</filename>
</files>
<config>
<fields name="params">
<fieldset name="basic">
<field
name="domain"
type="url"
label="MOD_FOO_FIELD_URL_LABEL"
filter="url"
/>
</fieldset>
<fieldset name="advanced">
<field
name="layout"
type="modulelayout"
label="JFIELD_ALT_LAYOUT_LABEL"
class="custom-select"
/>

<field
name="moduleclass_sfx"
type="textarea"
label="COM_MODULES_FIELD_MODULECLASS_SFX_LABEL"
rows="3"
/>

<field
name="cache"
type="list"
label="COM_MODULES_FIELD_CACHING_LABEL"
default="0"
>
<option value="1">JGLOBAL_USE_GLOBAL</option>
<option value="0">COM_MODULES_FIELD_VALUE_NOCACHING</option>
</field>

<field
name="cache_time"
type="number"
label="COM_MODULES_FIELD_CACHE_TIME_LABEL"
default="0"
/>

<field
name="cachemode"
type="hidden"
default="itemid"
>
<option value="itemid"></option>
</field>
</fieldset>
</fields>
</config>
</extension>

</source>

<translate>
=== Editing tmpl/default.php === 
</translate>
<translate> We can use the value of the parameter for creating an hyperlink in the frontend. We can access the value via the variable via the variable $params.</translate>

<source lang="php">$domain = $params->get('domain', 'https://www.joomla.org');</source>

<translate> Later we set use this value for creating the hyperlink.</translate>

<source lang="php">

<a href="<?php echo $domain; ?>">
<?php echo '[PROJECT_NAME]' . $test; ?>
</a>

</source>

<translate>
==== Completed tmpl/default.php file ==== 
</translate>
<translate> The complete <tt>tmpl/default.php</tt> file is as follows:</translate>

<source lang="php">

<?php
/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/

defined('_JEXEC') or die;

$domain = $params->get('domain', 'https://www.joomla.org');
?>

<a href="<?php echo $domain; ?>">
<?php echo '[PROJECT_NAME]' . $test; ?>
</a>

</source>

<translate>
=== Editing language/en-GB/en-GB.mod_foo.ini === 
</translate>
<translate> Here we can specify the text for the English version of the field label.</translate>

<source lang="php">MOD_FOO_FIELD_URL_LABEL="Url"</source>

<translate>
==== Completed language/en-GB/en-GB.mod_foo.ini ==== 
</translate>
<translate> The complete <tt>language/en-GB/en-GB.mod_foo.ini</tt> file is as follows:</translate>

<source lang="php">

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"
MOD_FOO_FIELD_URL_LABEL="Url"

</source>

<translate>
== Test your module == 
</translate>
<translate> Now you can zip all files and install them via the Joomla Extension Manager.</translate>
<translate> After that you can choose your module in the module manager, when you create a new site module.</translate>

<translate> In the backend, you will see your module like displayed in the next image.</translate>

<translate> In the basic tab, you will see the custom field where you can insert a domain. The text for the label is fetched from the language file.</translate>
{{-}}
[[File:moduletutorial31-<translate> en</translate>.png|700px|center]]

<translate> In the advanced tab, you will see all default options except the cache mode because of this is a hidden field.</translate>
{{-}}
[[File:moduletutorial32-<translate> en</translate>.png|700px|center]]

<translate> In the frontend, you will see your module like displayed in the next image. The text form your helper file is displayed and you should see a hyperlink.</translate>
{{-}}
[[File:moduletutorial33-<translate> en</translate>.png|700px|center]]

<translate>
== Conclusion == 
</translate>
<translate> Form fields give the user an easy way to customize the module to their sites settings. This allows the modules scope to be increased.</translate>

<translate> You can find boilerplates hereː</translate>
* https://github.com/joomla-extensions/boilerplate/tree/master/plugins/system
<translate> The sample files for this Tutorial can be found hereː</translate>
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules
<translate> See this issue for possible future changes:</translate>
* https://github.com/joomla/joomla-cms/pull/23553

<translate>

== Use Install, Update and Uninstall script - Part 4 == 
</translate>

<translate>
=== Requirements === 
</translate>
<translate> You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)</translate>

<translate>
=== Scripts === 
</translate>
<translate> Installing, updating and uninstalling a module may require additional operations that cannot be achieved by the basic operations described in the main XML file. Joomla offers a new approach to solve this problem. It consists in using a PHP script file containing a class using five methods:</translate>
<translate>
* preflight which is executed before install and update
* install
* update
* uninstall
* postflight which is executed after install and update</translate>

<translate> Let's take a look how to use them in Joomla 4. We use the helper file for this.</translate>

<translate>
=== File Structure === 
</translate>
<translate> We will create/change the following files:</translate>
<translate>
* <tt>script.php</tt> - This is the file we use here as an example. We have to create it.
* <tt>language/en-GB/en-GB.mod_foo.sys.ini</tt> - In this file we will add text.
* <tt>mod_foo.xml</tt> - We create a new file. This must be installed during the installation. For this we have to specify it in this file.</translate>

<translate>
=== Creating script.php === 
</translate>
<translate> Writing an extension script consists in declaring a class whose name is <tt>mod_ModuleNameInstallerScripʈ</tt> with these 5 methods. See the comments in the file for more information. In this comments I explain when a method is called.</translate>

<translate> In this example, I only use text to show when which method will be executed. In addition, I show you how to check the minimum requirements. Of course you can do much more. For example, you can delete files that are no longer needed in a new version of your module. This can be seen in the file. Another idea for this file is to create sample content, to show a success message with the current installed version number or you can redirect after a successful installation to the page with the module settings.</translate>

<translate>
==== Completed script.php ==== 
</translate>
<translate> The complete <tt>script.php</tt> file is as follows:</translate>

<source lang="php">

<?php

/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/
// No direct access to this file
defined('_JEXEC') or die;

use Joomla\CMS\Language\Text;
use Joomla\CMS\Log\Log;

/**
* Script file of Foo module
*/
class mod_fooInstallerScript {

/**
* Extension script constructor.
*
* @return void
*/
public function __construct() {
$this->minimumJoomla = '4.0';
$this->minimumPhp = JOOMLA_MINIMUM_PHP;
}

/**
* Method to install the extension
*
* @param InstallerAdapter $parent The class calling this method
*
* @return boolean True on success
*/
function install($parent) {
echo Text::_('MOD_FOO_INSTALLERSCRIPT_UNINSTALL');

return true;
}

/**
* Method to uninstall the extension
*
* @param InstallerAdapter $parent The class calling this method
*
* @return boolean True on success
*/
function uninstall($parent) {
echo Text::_('MOD_FOO_INSTALLERSCRIPT_UNINSTALL');

return true;
}

/**
* Method to update the extension
*
* @param InstallerAdapter $parent The class calling this method
*
* @return boolean True on success
*/
function update($parent) {
echo Text::_('MOD_FOO_INSTALLERSCRIPT_UPDATE');

return true;
}

/**
* Function called before extension installation/update/removal procedure commences
*
* @param string $type The type of change (install, update or discover_install, not uninstall)
* @param InstallerAdapter $parent The class calling this method
*
* @return boolean True on success
*/
function preflight($type, $parent) {
// Check for the minimum PHP version before continuing
if (!empty($this->minimumPhp) && version_compare(PHP_VERSION, $this->minimumPhp, '<')) {
Log::add(Text::sprintf('JLIB_INSTALLER_MINIMUM_PHP', $this->minimumPhp), Log::WARNING, 'jerror');

return false;
}

// Check for the minimum Joomla version before continuing
if (!empty($this->minimumJoomla) && version_compare(JVERSION, $this->minimumJoomla, '<')) {
Log::add(Text::sprintf('JLIB_INSTALLER_MINIMUM_JOOMLA', $this->minimumJoomla), Log::WARNING, 'jerror');

return false;
}

echo Text::_('MOD_FOO_INSTALLERSCRIPT_PREFLIGHT');
echo $this->minimumJoomla . ' ' . $this->minimumPhp;

return true;
}

/**
* Function called after extension installation/update/removal procedure commences
*
* @param string $type The type of change (install, update or discover_install, not uninstall)
* @param InstallerAdapter $parent The class calling this method
*
* @return boolean True on success
*/
function postflight($type, $parent) {
echo Text::_('MOD_FOO_INSTALLERSCRIPT_POSTFLIGHT');

return true;
}

}

</source>

<translate>
=== Editing language/en-GB/en-GB.mod_foo.sys.ini === 
</translate>
<translate> There is not much to explain here. Write the text for the translation into this file.</translate>

<translate>
==== Completed language/en-GB/en-GB.mod_foo.sys.ini file ==== 
</translate>
<translate> The complete <tt>language/en-GB/en-GB.mod_foo.sys.ini</tt> file is as follows:</translate>

<source lang="php">

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"
MOD_FOO_INSTALLERSCRIPT_PREFLIGHT="<p>Anything here happens before the installation/update/uninstallation of the module</p>"
MOD_FOO_INSTALLERSCRIPT_UPDATE="<p>The module has been updated</p>"
MOD_FOO_INSTALLERSCRIPT_UNINSTALL="<p>The module has been uninstalled</p>"
MOD_FOO_INSTALLERSCRIPT_INSTALL="<p>The module has been installed</p>"
MOD_FOO_INSTALLERSCRIPT_POSTFLIGHT="<p>Anything here happens after the installation/update/uninstallation of the module</p>"

</source>

<translate>
=== Editing mod_foo.xml === 
</translate>
<translate> You have to add a line, so that the script is called automatically in Joomla.</translate>

<source lang="xml"><scriptfile>script.php</scriptfile></source>

<translate>
==== Completed mod_foo.xml ==== 
</translate>
<translate> The complete <tt>mod_foo.xml</tt> file is as follows:</translate>

<source lang="xml">

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="4.0" client="site" method="upgrade">
<name>MOD_FOO</name>
<creationDate>[DATE]</creationDate>
<author>[AUTHOR]</author>
<authorEmail>[AUTHOR_EMAIL]</authorEmail>
<authorUrl>[AUTHOR_URL]</authorUrl>
<copyright>[COPYRIGHT]</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<version>1.0</version>
<description>MOD_FOO_XML_DESCRIPTION</description>
<namespace>Joomla\Module\Foo</namespace>
<scriptfile>script.php</scriptfile>
<files>
<filename module="mod_foo">mod_foo.php</filename>
<folder>tmpl</folder>
<folder>Helper</folder>
<folder>language</folder>
<filename>mod_foo.xml</filename>
</files>
<config>
<fields name="params">
<fieldset name="basic">
<field
name="domain"
type="url"
label="MOD_FOO_FIELD_URL_LABEL"
filter="url"
/>
</fieldset>
<fieldset name="advanced">
<field
name="layout"
type="modulelayout"
label="JFIELD_ALT_LAYOUT_LABEL"
class="custom-select"
/>

<field
name="moduleclass_sfx"
type="textarea"
label="COM_MODULES_FIELD_MODULECLASS_SFX_LABEL"
rows="3"
/>

<field
name="cache"
type="list"
label="COM_MODULES_FIELD_CACHING_LABEL"
default="0"
>
<option value="1">JGLOBAL_USE_GLOBAL</option>
<option value="0">COM_MODULES_FIELD_VALUE_NOCACHING</option>
</field>

<field
name="cache_time"
type="number"
label="COM_MODULES_FIELD_CACHE_TIME_LABEL"
default="0"
/>

<field
name="cachemode"
type="hidden"
default="itemid"
>
<option value="itemid"></option>
</field>
</fieldset>
</fields>
</config>
</extension>
</source>

<translate>
== Test your module == 
</translate>
<translate> Now you can zip all files and install them via the Joomla Extension Manager.</translate>
<translate> Immediately after the installation, you will see the following information. This you had entered in the script so.</translate>
{{-}}
[[File:moduletutorial14-<translate> en</translate>.png|700px|center]]

<translate>
== Conclusion == 
</translate>
<translate> As you can see, Joomla offers you a lot to make your extension easy to use - right from the start.</translate>

<translate> You can find boilerplates hereː</translate>
* https://github.com/joomla-extensions/boilerplate/tree/master/plugins/system
<translate> The sample files for this Tutorial can be found hereː</translate>
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

<translate>

== Use Joomla Updaterː Adding Auto Update - Part 5 == 
</translate>

<translate>
=== Requirements === 
</translate>
<translate> You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)</translate>

<translate>
=== Joomla Updater === 
</translate>
<translate> The first thing to do is to read the [[S:MyLanguage/J2.5:Managing_Component_Updates|Managing Component Upgrades with Joomla 2.5 - Part 1]] tutorial to give an idea of how the upgrade process works in Joomla. Whilst written for 2.5 the process hasn't changed. Also read [[S:MyLanguage/Deploying_an_Update_Server|Deploying an update server]] - this is what we'll be implementing in this tutorial.</translate>

<translate>
=== File Structure === 
</translate>
<translate> We will create/change the following files:</translate>
<translate> * <tt>mod_foo.xml</tt> - The only way to update our existing module is to add in a update server - for example <tt><nowiki>http://www.example.com/foo_update.xmɭ</nowiki></tt> - into the xml file.</translate>
<translate> * <tt>foo_update.xml</tt> - Then we have to create the XML file for the update server at <tt><nowiki>http://www.example.com/foo_update.xmɭ</nowiki></tt> to let Joomla know an update is available.</translate>

<translate>
==== Editing mod_foo.xml ==== 
</translate>
<translate> To add our update server, we need to insert the following lines in your XML-File</translate>

<source lang="php">

<updateservers>
<server type="extension" priority="1" name="[PROJECT_NAME]">https://www.example.com/mod_foo.xml</server>
</updateservers>

</source>

<translate>
==== Completed mod_foo.xml ==== 
</translate>
<translate> The complete <tt>mod_foo.xml</tt> file is as follows:</translate>

<source lang="xml">

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="4.0" client="site" method="upgrade">
<name>MOD_FOO</name>
<creationDate>[DATE]</creationDate>
<author>[AUTHOR]</author>
<authorEmail>[AUTHOR_EMAIL]</authorEmail>
<authorUrl>[AUTHOR_URL]</authorUrl>
<copyright>[COPYRIGHT]</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<version>1.0</version>
<description>MOD_FOO_XML_DESCRIPTION</description>
<namespace>Joomla\Module\Foo</namespace>
<files>
<filename module="mod_foo">mod_foo.php</filename>
<folder>tmpl</folder>
<folder>Helper</folder>
<folder>language</folder>
<filename>mod_foo.xml</filename>
</files>
<updateservers>
<server type="extension" priority="1" name="[PROJECT_NAME]">https://www.example.com/mod_foo.xml</server>
</updateservers>
<config>
<fields name="params">
<fieldset name="basic">
<field
name="domain"
type="url"
label="MOD_FOO_FIELD_URL_LABEL"
filter="url"
/>
</fieldset>
<fieldset name="advanced">
<field
name="layout"
type="modulelayout"
label="JFIELD_ALT_LAYOUT_LABEL"
class="custom-select"
/>

<field
name="moduleclass_sfx"
type="textarea"
label="COM_MODULES_FIELD_MODULECLASS_SFX_LABEL"
rows="3"
/>

<field
name="cache"
type="list"
label="COM_MODULES_FIELD_CACHING_LABEL"
default="0"
>
<option value="1">JGLOBAL_USE_GLOBAL</option>
<option value="0">COM_MODULES_FIELD_VALUE_NOCACHING</option>
</field>

<field
name="cache_time"
type="number"
label="COM_MODULES_FIELD_CACHE_TIME_LABEL"
default="0"
/>

<field
name="cachemode"
type="hidden"
default="itemid"
>
<option value="itemid"></option>
</field>
</fieldset>
</fields>
</config>
</extension>

</source>

<translate> So now that Joomla is searching for updates to our extension - let's create one to test out our process. But first we need to create the file <tt>foo_update.xml</tt>. So far we have only described the update server. We do not know yet if there is an update. In the file <tt>foo_update.xml</tt> we indicate when a new version is published and where it can be downloaded.</translate>

<translate>
=== Creating foo_update.xml === 
</translate>
<translate> Now we have to create the XML file at <tt><nowiki>http://www.example.com/foo_update.xml</nowiki></tt> to let Joomla know an update is available.</translate>

<translate>
==== Completed foo_update.xml ==== 
</translate>
<translate> The complete <tt>foo_update.xml</tt> file is as follows:</translate>

<source lang="xml">

<?xml version="1.0" ?>

<updates>
<update>
<name>Foo</name>
<description>This is mod_foo 1.0.1</description>
<element>mod_foo</element>
<type>module</type>
<version>1.0.1</version>
<downloads>
<downloadurl type="full" format="zip">http://www.example.com/mod_foo_101.zip</downloadurl>
</downloads>
<maintainer>Joomla</maintainer>
<maintainerurl>http://www.example.com</maintainerurl>
<targetplatform name="joomla" version="4.0"/>
<client>site</client>
</update>
</updates>

</source>

<translate> After uploading this file to the address <tt><nowiki>https://www.example.com/mod_foo.xml</nowiki></tt> the update will be displayed in the Joomla backend.</translate>

<translate>
=== Test your module update === 
</translate>
<translate> Create a copy of the module as it is now. Then let's update the version number to 1.0.1. Now you can zip all files. After that you should load your zip to the URL <tt><nowiki>http://www.example.com/mod_foo_101.zip</nowiki></tt>. Now you can update your module via the Joomla Updater.</translate>

<translate>
=== Commercial Modules === 
</translate>
<translate> Note that in our files we have linked to the extensions updates xml file. And from that xml file we have a location for the zip of the module. This means that if someone was to track this backwards they could find the physical source of your modules zip file. If you don't do like this, you can find a solution in this PRː https://github.com/joomla/joomla-cms/pull/15185 .</translate>

<translate>
=== Conclusion === 
</translate>
<translate> With the Joomla updater, you can easily reach all users and tell them that there is a new version. Even the update itself is easy.</translate>

<translate> Each extension should use an update server. Especially for security reasons.</translate>

<translate> You can find boilerplates hereː</translate>
* https://github.com/joomla-extensions/boilerplate/tree/master/plugins/system
<translate> The sample files for this Tutorial can be found hereː</translate>
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

<noinclude>
[[Category:Beginner Development{{#translation:}}]]
[[Category:Tutorials{{#translation:}}]]
[[Category:Tutorials in a Series{{#translation:}}]]
[[Category:Development{{#translation:}}]]
[[Category:Module Development{{#translation:}}]]
[[Category:Joomla! 4.x{{#translation:}}]]
[[Category:Joomla! 4.0{{#translation:}}]]
</noinclude>

J4.x:Creating a Simple Module

2019-06-21T06:55:55Z

Garkell: Changed to point to modules rather than plugin boilerplate

<noinclude><languages /></noinclude>
{{Joomla version|version=4.x|comment=><translate> Tutorial</translate>}}
{{-}}
{{Top portal heading|color=white-bkgd|icon=file-code-o|icon-color=#5091cd|size=5x|text-color=#333|title=<translate> Creating a Simple Module for Joomla 4.x</translate>}}
{{-}}

<translate> This is a tutorial on how to Create a simple module for Joomla Version 4x.</translate>
<translate>
== Introduction == 
</translate>
<translate> Joomlaǃ 4 provides five types of extensionsː</translate>
* '''[[S:MyLanguage/Component|<translate> Components</translate>]]'''<br /><translate> A component is the main part of the site. A component handles data manipulation as well as input and storage into the database. A component on most sites is the primary focus of the page.</translate>
* '''[[S:MyLanguage/Module|<translate> Modules</translate>]]''' <br /><translate> A module is an add-on to the site that extends the functionality. A module usually occupies a secondary portion of the web page and is not considered the primary focus of a page. It can be displayed on different positions and you can choose on which active menu items it should be displayed. Modules are lightweight and flexible extensions. They are used for small bits of the page that are generally less complex and are able to be seen across different components.</translate>
* '''[[S:MyLanguage/Plugin|<translate> Plugins</translate>]]'''<br /><translate> A Plugin manipulates output that is already generated by the system. It typically does not run as separate part of the site. It takes data from other sources (i.e. the content) and manipulates this data before displaying. A plugin typically work behind the scenes.</translate>
* '''[[S:MyLanguage/Languages|<translate> Languages</translate>]]'''<br />Probably the most basic extensions are languages. In essence the language package files consist of key/value pairs, which provide the translation of static text strings, assigned within the Joomla! source code.
* '''[[S:MyLanguage/Templates|<translate> Templates</translate>]]'''<br /><translate> A template is basically the design of your Joomla! powered website.</translate>

<translate> Joomla! 4 is constructed using five different applications:</translate>
<translate>
* Installation (used for installing Joomla and have to delete after installation)
* Administrator (backend - used for managing content)
* Public or site (frontend - used for displaying content)
* CLI (used for accessing Joomla on the command line and for cron jobs)
* API (web services - used for creating APIs for machine accessible content)</translate>
<translate>

The installation application is used once. The administrator and public are used through the concept of ''components'' with ''modules''. Each module has a single entry point located in the ''modules'' and accordingly ''administrator/modules'' directory. This entry point is called <tt>''mod_modulename/mod_modulename.php''</tt> (the ''mod_'' prefix is a historical trace). The entry point for the login module is for ''example /mod_login/mod_login.php''.</translate>

<translate>
=== Requirements === 
</translate>
<translate> You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)</translate>

<translate> You can download Joomla! 4 at [https://github.com/joomla/joomla-cms/tree/4.0-dev GitHub], on the [https://developer.joomla.org/nightly-builds.html Developer website] or you can create a free website at https://launch.joomla.org.</translate>

<translate>
== Creating a simple module/Developing a Basic Module - Part 1 == 
</translate>
<translate> You can see many examples of modules in the standard Joomla! install. For example:</translate>
<translate>
* Menus
* Latest News
* Login form
* and many more.</translate>

<translate> This tutorial will explain how to create a simple module. Through this tutorial you will learn the basic file structure of a Joomlaǃ 4 module. This basic structure can then be expanded to produce more elaborate modules.</translate>

<translate>
=== File Structure === 
</translate>
<translate> There are a few basic files that are used in the standard pattern of module development:</translate>
<translate> * <tt>mod_foo.php</tt> - This file is the main entry point for the module. It will perform any necessary initialization routines, call helper routines to collect any necessary data, and include the template which will display the module output.</translate>
<translate> * <tt>mod_foo.xml</tt> - This file contains information about the module. It defines the files that need to be installed by the Joomla! installer and specifies configuration parameters for the module.</translate>
<translate> * <tt>tmpl/default.php</tt> - This is the module template. This file will take the data collected by mod_foo.php and generate the HTML to be displayed on the page.</translate>
<translate> * <tt>language/en-GB/en-GB.mod_foo.ini</tt> and <tt>language/en-GB/en-GB.mod_foo.sys.ini</tt>- This are the files that provide the text in United Kingdom English.</translate>

<translate>
=== Creating mod_foo.php === 
</translate>
<translate> The <tt>mod_foo.php</tt> file will perform following tasks:</translate>
<translate> * Import the class <tt>ModuleHelper</tt> to the current scope. We need it later for displaying the output.</translate>
<translate> * Include the template to display the output.</translate>

<translate> The helper class is imported to our current scope at the begin of the file.</translate>

<source lang="php">use Joomla\CMS\Helper\ModuleHelper;</source>

<translate> Last we include the template to display the output via</translate>

<source lang="php">require ModuleHelper::getLayoutPath('mod_foo', $params->get('layout', 'default'));</source>

<translate>
==== Completed mod_foo.php file ==== 
</translate>
<translate> The complete <tt>mod_foo.php</tt> file is as follows:</translate>

<source lang="php">
<?php
/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/

use Joomla\CMS\Helper\ModuleHelper;

defined('_JEXEC') or die;

require ModuleHelper::getLayoutPath('mod_foo', $params->get('layout', 'default'));

</source>

<translate> ''Side note''ː In Joomla 3x you usually used a line like <tt>$moduleclass_sfx = htmlspecialchars($params->get('moduleclass_sfx'));</tt>. You don't need this anymore. See this PRː https://github.com/joomla/joomla-cms/pull/17447.</translate>

<translate> The one line that we haven’t explained so far is the first line <tt>defined('_JEXEC') or die;</tt>. This line checks to make sure that this file is being included from the Joomla application. This is necessary to prevent variable injection and other potential security concerns.</translate>

<translate>
=== Creating tmpl/default.php === 
</translate>
<translate> The <tt>default.php</tt> file is the template which displays the module output.</translate>

<translate>
==== Completed tmpl/default.php file ==== 
</translate>
<translate> The code for the tmpl/default.php file is as follows:</translate>

<source lang="php">
<?php
/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/

defined('_JEXEC') or die;

echo '[PROJECT_NAME]';

</source>

<translate> An important point to note is that the template file has the same scope as the <tt>mod_foo.php</tt> file. It means that a variable can be defined in the <tt>mod_foo.php</tt> file and then used in the template file without any extra declarations or function calls.</translate>

<translate>
=== Creating mod_foo.xml === 
</translate>
<translate> The <tt>mod_foo.xml</tt> file is the installation file. Most entries are self-explanatory.</translate>

<translate>
==== Completed mod_foo.xml file ==== 
</translate>
<translate> The code for the <tt>mod_foo.xml</tt> file is as follows:</translate>

<source lang="xml">

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.8" client="site" method="upgrade">
<name>MOD_FOO</name>
<creationDate>[DATE]</creationDate>
<author>[AUTHOR]</author>
<authorEmail>[AUTHOR_EMAIL]</authorEmail>
<authorUrl>[AUTHOR_URL]</authorUrl>
<copyright>[COPYRIGHT]</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<version>1.0</version>
<description>MOD_FOO_XML_DESCRIPTION</description>

<files>
<filename module="mod_foo">mod_foo.php</filename>
<folder>tmpl</folder>
<folder>language</folder>
<filename>mod_foo.xml</filename>
</files>

</extension>

</source>

<translate>
=== Creating the language files === 
</translate>
<translate> The files <tt>language/en-GB/en-GB.mod̠foo.ini</tt> and <tt>language/en-GB/en-GB.mod̠foo.sys.ini</tt> are used to translate text in the frontend and in the backend.</translate>

<translate> The code for <tt>language/en-GB/en-GB.mod̠foo.sys.ini</tt> is as follows:</translate>

<source lang="xml">

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"

</source>

<source lang="xml">

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"

</source>

<translate> The <tt>.sys.ini</tt> file is used to translate the description of the extension upon installation, where as the <tt>.ini</tt> file is used to translate the remaining strings and the description when viewing your extension.</translate>

<translate> More information about language files can be found [[S:MyLanguage/Specification_of_language_files|here]].</translate>

<translate>
== Test your module == 
</translate>
<translate> Now you can zip all files and install them via the Joomla Extension Manager.<br /></translate>
<translate> After that you can choose your module in the module manager, when you create a new site module.</translate>
{{-}}
[[File:moduletutorial1-<translate> en</translate>.png|700px|center]]
{{-}}
[[File:moduletutorial2-<translate> en</translate>.png|700px|center]]

<translate> In the frontend, you will see your module like displayed in the next image.</translate>
{{-}}
[[File:moduletutorial3-<translate> en</translate>.png|700px|center]]

<translate>
== Conclusion == 
</translate>
<translate> Module development for Joomla is a fairly simple, straightforward process. Using the techniques described in this tutorial, an endless variety of modules can be developed with little hassle.</translate>

<translate> You can find boilerplates hereː</translate>
* https://github.com/joomla-extensions/boilerplate/tree/master/module
<translate> The sample files for this Tutorial can be found hereː</translate>
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

<translate>

== Add a helper class using namespaces - Part 2== 
</translate>

<translate>
=== Requirements === 
</translate>
<translate> You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)</translate>

<translate>
== Namespaces == 
</translate>
<translate> With PHP 5.3, the namespaces came into their own. In other programming languages for a long time in use, these small structures now also help us with the clarity of our code.</translate>

<translate> Namespaces are separate areas in which certain logical things (in our case, classes, interfaces, functions, and constants) can live. These areas provide ncapsulation of the code and prevent name conflicts.</translate>

<translate> Let's take a look how to use them in Joomla 4. We use the helper file for this.</translate>

<translate>
=== File Structure === 
</translate>
<translate> We will create/change the following files:</translate>
<translate>
* <code>Helper/FooHelper.php</code> - This is the file we use here as an example. We have to create it.
* <code>mod_foo.php</code> - In this file we will mainly load the namespace.
* <code>tmpl/default.php</code> - In this file demonstrate how the data of a helper can be displayed.
* <code>mod_foo.xml</code> - We create a new directory with a new file. This must be installed during the installation. For this we have to specify them in this file.</translate>

<translate>
=== Creating Helper/FooHelper.php === 
</translate>
<translate> Our new helper class should belong to a namespace. We achieve this with the following code. It is important, that this line is at the beginning of the file.</translate>

<source lang="php">namespace Joomla\Module\Foo\Site\Helper;</source>

<translate> Then we create a simple class with a simple method. Of course you can do a lot more here. Take a look at the Joomla core methods. Here are many examples. They show you first-hand what options you have.</translate>

<translate>
==== Completed Helper/FooHelper.php ==== 
</translate>
<translate> The complete <tt>mod_foo.php</tt> file is as follows:</translate>

<source lang="php">

<?php
/**
* @package Joomla.Site
* @subpackage mod_breadcrumbs
*
* @copyright Copyright (C) 2005 - 2018 Open Source Matters, Inc. All rights reserved.
* @license GNU General Public License version 2 or later; see LICENSE.txt
*/

namespace Joomla\Module\Foo\Site\Helper;

defined('_JEXEC') or die;

/**
* Helper for mod_foo
*
* @since 4.0
*/
class FooHelper
{
/**
* Retrieve foo test
*
* @param Registry $params The module parameters
* @param CMSApplication $app The application
*
* @return array
*/
public static function getText()
{
return 'FooHelpertest';
}
}

</source>

<translate>
=== Editing mod_foo.php === 
</translate>
<translate> Our new helper class is imported to our current scope at the begin of the file.</translate>

<source lang="php">use Joomla\Module\Foo\Site\Helper\FooHelper;</source>

<translate> Last use the helper file for testing if it is loaded correctlyː</translate>

<source lang="php">$test = FooHelper::getText($params, $app);</source>

<translate>
==== Completed mod_foo.php file ==== 
</translate>
<translate> The complete <tt>mod_foo.php</tt> file is as follows:</translate>

<source lang="php">

<?php
/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/

defined('_JEXEC') or die;

use Joomla\CMS\Helper\ModuleHelper;
use Joomla\Module\Foo\Site\Helper\FooHelper;

$test = FooHelper::getText();

require ModuleHelper::getLayoutPath('mod_foo', $params->get('layout', 'default'));

</source>

<translate>
=== Editing tmpl/default.php === 
</translate>
<translate> In this file you make only a small change to demonstrate in the frontend that your helper file is working properly. You only add the value of the variable at the end of the current output.</translate>

<source lang="php"><?php echo '[PROJECT_NAME]' . $test;</source>

<translate>
==== Completed tmpl/default.php ==== 
</translate>
<translate> The complete <tt>tmpl/default.php</tt> file is as follows:</translate>

<source lang="php">

<?php
/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/

defined('_JEXEC') or die;

?>

<?php echo '[PROJECT_NAME]' . $test;

</source>

<translate>
=== Editing mod_foo.xml === 
</translate>
<translate> First you have to add a line, so that the namespace is set automatically in Joomla. After this change, you have to re-install your module. A simple change in an already installed module is not enough. If you are doing local development you can also delete the files libraries/autoload_psr4.php and it will automatically be re-created. After inserting and installing, the namespace is known by the loader <tt>JPATH_LIBRARIES . '/autoload_psr4.php'</tt>.</translate>

<source lang="xml"><namespace>Joomla\Module\Foo</namespace></source>

<translate> Joomla! should copy your helper file when installing the module. So Joomla! needs to know your helper file. For this, you need to add the following line to your XML file.</translate>

<source lang="xml"><folder>Helper</folder></source>

<translate>
==== Completed mod_foo.xml ==== 
</translate>
<translate> The complete <tt>mod_foo.xml</tt> file is as follows:</translate>

<source lang="xml">

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.8" client="site" method="upgrade">
<name>MOD_FOO</name>
<creationDate>[DATE]</creationDate>
<author>[AUTHOR]</author>
<authorEmail>[AUTHOR_EMAIL]</authorEmail>
<authorUrl>[AUTHOR_URL]</authorUrl>
<copyright>[COPYRIGHT]</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<version>1.0</version>
<description>MOD_FOO_XML_DESCRIPTION</description>
<namespace>Joomla\Module\Foo</namespace>
<files>
<filename module="mod_foo">mod_foo.php</filename>
<folder>tmpl</folder>
<folder>Helper</folder>
<folder>language</folder>
<filename>mod_foo.xml</filename>
</files>

</extension>

</source>

<translate>
== Test your module == 
</translate>
<translate> Now you can zip all files and install them via the Joomla Extension Manager.</translate>
<translate> After that you can choose your module in the module manager, when you create a new site module.</translate>

<translate> In the frontend you will see your module like displayed in the next image. The text form your helper file is displayed.</translate>
{{-}}
[[File:moduletutorial23-<translate> en</translate>.png|700px|center]]

<translate>
== Conclusion == 
</translate>
<translate> As you can see, once you get a bit into the namespaces, they are not that complicated anymore. In big projects they can bring a lot of benefits. However, we should plan namespaces, as otherwise it will soon be more time-consuming.</translate>

<translate> You can find boilerplates hereː</translate>
* https://github.com/joomla-extensions/boilerplate/tree/master/plugins/system
<translate> The sample files for this Tutorial can be found hereː</translate>
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

<translate>

== Customizationː Add parameters via form fields - Part 3 == 
</translate>

<translate>
=== Requirements === 
</translate>
<translate> You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)</translate>

<translate>
== Customization with form fields and parameters == 
</translate>
<translate> Form fields give a great deal of customization in Joomla and for modules are the sole way of allowing the user to tweak the module to the needs of their site.</translate>

<translate> In this case we are going to extend our previous example using a url field for inserting a domain that we can use as link in the front end. To allow this to happen we will use the [[S:MyLanguage/URL_form_field_type|URL Form Field]] type.</translate>

<translate> After that, we insert parameters that allow to use standard functionality of Joomla.</translate>

<translate> Let's take a look on how to use them in Joomla 4.</translate>

<translate>
=== File Structure === 
</translate>
<translate> We will change the following files:</translate>
<translate>
* <tt>mod_foo.xml</tt> - This is the file where we add the fields.
* <tt>tmpl/default.php</tt> - In this file demonstrate how the data of a field can be used.
* <tt>language/en-GB/en-GB.mod_foo.ini</tt> - Here we use a language string so that the field can be labeled correctly in different languages.</translate>

<translate>
=== Editing mod_foo.xml === 
</translate>
<translate> First we set a custom parameter.</translate>

<source lang="xml">

<field
name="domain"
type="url"
label="MOD_FOO_FIELD_URL_LABEL"
filter="url"
/>

</source>

<translate> Then we insert Joomla default fields, so that we can use cache, moduleclass-suffix and layouts.</translate>

<source lang="xml">
<field
name="layout"
type="modulelayout"
label="JFIELD_ALT_LAYOUT_LABEL"
class="custom-select"
/>

<field
name="moduleclass_sfx"
type="textarea"
label="COM_MODULES_FIELD_MODULECLASS_SFX_LABEL"
rows="3"
/>

<field
name="cache"
type="list"
label="COM_MODULES_FIELD_CACHING_LABEL"
default="0"
>
<option value="1">JGLOBAL_USE_GLOBAL</option>
<option value="0">COM_MODULES_FIELD_VALUE_NOCACHING</option>
</field>

<field
name="cache_time"
type="number"
label="COM_MODULES_FIELD_CACHE_TIME_LABEL"
default="0"
/>

<field
name="cachemode"
type="hidden"
default="itemid"
>
<option value="itemid"></option>
</field>

</source>

<translate>
==== Completed mod_foo.xml ==== 
</translate>
<translate> The complete <tt>mod_foo.xml</tt> file is as follows:</translate>

<source lang="xml">

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.8" client="site" method="upgrade">
<name>MOD_FOO</name>
<creationDate>[DATE]</creationDate>
<author>[AUTHOR]</author>
<authorEmail>[AUTHOR_EMAIL]</authorEmail>
<authorUrl>[AUTHOR_URL]</authorUrl>
<copyright>[COPYRIGHT]</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<version>1.0</version>
<description>MOD_FOO_XML_DESCRIPTION</description>
<namespace>Joomla\Module\Foo</namespace>
<files>
<filename module="mod_foo">mod_foo.php</filename>
<folder>tmpl</folder>
<folder>Helper</folder>
<folder>language</folder>
<filename>mod_foo.xml</filename>
</files>
<config>
<fields name="params">
<fieldset name="basic">
<field
name="domain"
type="url"
label="MOD_FOO_FIELD_URL_LABEL"
filter="url"
/>
</fieldset>
<fieldset name="advanced">
<field
name="layout"
type="modulelayout"
label="JFIELD_ALT_LAYOUT_LABEL"
class="custom-select"
/>

<field
name="moduleclass_sfx"
type="textarea"
label="COM_MODULES_FIELD_MODULECLASS_SFX_LABEL"
rows="3"
/>

<field
name="cache"
type="list"
label="COM_MODULES_FIELD_CACHING_LABEL"
default="0"
>
<option value="1">JGLOBAL_USE_GLOBAL</option>
<option value="0">COM_MODULES_FIELD_VALUE_NOCACHING</option>
</field>

<field
name="cache_time"
type="number"
label="COM_MODULES_FIELD_CACHE_TIME_LABEL"
default="0"
/>

<field
name="cachemode"
type="hidden"
default="itemid"
>
<option value="itemid"></option>
</field>
</fieldset>
</fields>
</config>
</extension>

</source>

<translate>
=== Editing tmpl/default.php === 
</translate>
<translate> We can use the value of the parameter for creating an hyperlink in the frontend. We can access the value via the variable via the variable $params.</translate>

<source lang="php">$domain = $params->get('domain', 'https://www.joomla.org');</source>

<translate> Later we set use this value for creating the hyperlink.</translate>

<source lang="php">

<a href="<?php echo $domain; ?>">
<?php echo '[PROJECT_NAME]' . $test; ?>
</a>

</source>

<translate>
==== Completed tmpl/default.php file ==== 
</translate>
<translate> The complete <tt>tmpl/default.php</tt> file is as follows:</translate>

<source lang="php">

<?php
/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/

defined('_JEXEC') or die;

$domain = $params->get('domain', 'https://www.joomla.org');
?>

<a href="<?php echo $domain; ?>">
<?php echo '[PROJECT_NAME]' . $test; ?>
</a>

</source>

<translate>
=== Editing language/en-GB/en-GB.mod_foo.ini === 
</translate>
<translate> Here we can specify the text for the English version of the field label.</translate>

<source lang="php">MOD_FOO_FIELD_URL_LABEL="Url"</source>

<translate>
==== Completed language/en-GB/en-GB.mod_foo.ini ==== 
</translate>
<translate> The complete <tt>language/en-GB/en-GB.mod_foo.ini</tt> file is as follows:</translate>

<source lang="php">

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"
MOD_FOO_FIELD_URL_LABEL="Url"

</source>

<translate>
== Test your module == 
</translate>
<translate> Now you can zip all files and install them via the Joomla Extension Manager.</translate>
<translate> After that you can choose your module in the module manager, when you create a new site module.</translate>

<translate> In the backend, you will see your module like displayed in the next image.</translate>

<translate> In the basic tab, you will see the custom field where you can insert a domain. The text for the label is fetched from the language file.</translate>
{{-}}
[[File:moduletutorial31-<translate> en</translate>.png|700px|center]]

<translate> In the advanced tab, you will see all default options except the cache mode because of this is a hidden field.</translate>
{{-}}
[[File:moduletutorial32-<translate> en</translate>.png|700px|center]]

<translate> In the frontend, you will see your module like displayed in the next image. The text form your helper file is displayed and you should see a hyperlink.</translate>
{{-}}
[[File:moduletutorial33-<translate> en</translate>.png|700px|center]]

<translate>
== Conclusion == 
</translate>
<translate> Form fields give the user an easy way to customize the module to their sites settings. This allows the modules scope to be increased.</translate>

<translate> You can find boilerplates hereː</translate>
* https://github.com/joomla-extensions/boilerplate/tree/master/plugins/system
<translate> The sample files for this Tutorial can be found hereː</translate>
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules
<translate> See this issue for possible future changes:</translate>
* https://github.com/joomla/joomla-cms/pull/23553

<translate>

== Use Install, Update and Uninstall script - Part 4 == 
</translate>

<translate>
=== Requirements === 
</translate>
<translate> You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)</translate>

<translate>
=== Scripts === 
</translate>
<translate> Installing, updating and uninstalling a module may require additional operations that cannot be achieved by the basic operations described in the main XML file. Joomla offers a new approach to solve this problem. It consists in using a PHP script file containing a class using five methods:</translate>
<translate>
* preflight which is executed before install and update
* install
* update
* uninstall
* postflight which is executed after install and update</translate>

<translate> Let's take a look how to use them in Joomla 4. We use the helper file for this.</translate>

<translate>
=== File Structure === 
</translate>
<translate> We will create/change the following files:</translate>
<translate>
* <tt>script.php</tt> - This is the file we use here as an example. We have to create it.
* <tt>language/en-GB/en-GB.mod_foo.sys.ini</tt> - In this file we will add text.
* <tt>mod_foo.xml</tt> - We create a new file. This must be installed during the installation. For this we have to specify it in this file.</translate>

<translate>
=== Creating script.php === 
</translate>
<translate> Writing an extension script consists in declaring a class whose name is <tt>mod_ModuleNameInstallerScripʈ</tt> with these 5 methods. See the comments in the file for more information. In this comments I explain when a method is called.</translate>

<translate> In this example, I only use text to show when which method will be executed. In addition, I show you how to check the minimum requirements. Of course you can do much more. For example, you can delete files that are no longer needed in a new version of your module. This can be seen in the file. Another idea for this file is to create sample content, to show a success message with the current installed version number or you can redirect after a successful installation to the page with the module settings.</translate>

<translate>
==== Completed script.php ==== 
</translate>
<translate> The complete <tt>script.php</tt> file is as follows:</translate>

<source lang="php">

<?php

/**
* @package [PACKAGE_NAME]
*
* @author [AUTHOR] <[AUTHOR_EMAIL]>
* @copyright [COPYRIGHT]
* @license GNU General Public License version 2 or later; see LICENSE.txt
* @link [AUTHOR_URL]
*/
// No direct access to this file
defined('_JEXEC') or die;

use Joomla\CMS\Language\Text;
use Joomla\CMS\Log\Log;

/**
* Script file of Foo module
*/
class mod_fooInstallerScript {

/**
* Extension script constructor.
*
* @return void
*/
public function __construct() {
$this->minimumJoomla = '4.0';
$this->minimumPhp = JOOMLA_MINIMUM_PHP;
}

/**
* Method to install the extension
*
* @param InstallerAdapter $parent The class calling this method
*
* @return boolean True on success
*/
function install($parent) {
echo Text::_('MOD_FOO_INSTALLERSCRIPT_UNINSTALL');

return true;
}

/**
* Method to uninstall the extension
*
* @param InstallerAdapter $parent The class calling this method
*
* @return boolean True on success
*/
function uninstall($parent) {
echo Text::_('MOD_FOO_INSTALLERSCRIPT_UNINSTALL');

return true;
}

/**
* Method to update the extension
*
* @param InstallerAdapter $parent The class calling this method
*
* @return boolean True on success
*/
function update($parent) {
echo Text::_('MOD_FOO_INSTALLERSCRIPT_UPDATE');

return true;
}

/**
* Function called before extension installation/update/removal procedure commences
*
* @param string $type The type of change (install, update or discover_install, not uninstall)
* @param InstallerAdapter $parent The class calling this method
*
* @return boolean True on success
*/
function preflight($type, $parent) {
// Check for the minimum PHP version before continuing
if (!empty($this->minimumPhp) && version_compare(PHP_VERSION, $this->minimumPhp, '<')) {
Log::add(Text::sprintf('JLIB_INSTALLER_MINIMUM_PHP', $this->minimumPhp), Log::WARNING, 'jerror');

return false;
}

// Check for the minimum Joomla version before continuing
if (!empty($this->minimumJoomla) && version_compare(JVERSION, $this->minimumJoomla, '<')) {
Log::add(Text::sprintf('JLIB_INSTALLER_MINIMUM_JOOMLA', $this->minimumJoomla), Log::WARNING, 'jerror');

return false;
}

echo Text::_('MOD_FOO_INSTALLERSCRIPT_PREFLIGHT');
echo $this->minimumJoomla . ' ' . $this->minimumPhp;

return true;
}

/**
* Function called after extension installation/update/removal procedure commences
*
* @param string $type The type of change (install, update or discover_install, not uninstall)
* @param InstallerAdapter $parent The class calling this method
*
* @return boolean True on success
*/
function postflight($type, $parent) {
echo Text::_('MOD_FOO_INSTALLERSCRIPT_POSTFLIGHT');

return true;
}

}

</source>

<translate>
=== Editing language/en-GB/en-GB.mod_foo.sys.ini === 
</translate>
<translate> There is not much to explain here. Write the text for the translation into this file.</translate>

<translate>
==== Completed language/en-GB/en-GB.mod_foo.sys.ini file ==== 
</translate>
<translate> The complete <tt>language/en-GB/en-GB.mod_foo.sys.ini</tt> file is as follows:</translate>

<source lang="php">

MOD_FOO="[PROJECT_NAME]"
MOD_FOO_XML_DESCRIPTION="Foo Module"
MOD_FOO_INSTALLERSCRIPT_PREFLIGHT="<p>Anything here happens before the installation/update/uninstallation of the module</p>"
MOD_FOO_INSTALLERSCRIPT_UPDATE="<p>The module has been updated</p>"
MOD_FOO_INSTALLERSCRIPT_UNINSTALL="<p>The module has been uninstalled</p>"
MOD_FOO_INSTALLERSCRIPT_INSTALL="<p>The module has been installed</p>"
MOD_FOO_INSTALLERSCRIPT_POSTFLIGHT="<p>Anything here happens after the installation/update/uninstallation of the module</p>"

</source>

<translate>
=== Editing mod_foo.xml === 
</translate>
<translate> You have to add a line, so that the script is called automatically in Joomla.</translate>

<source lang="xml"><scriptfile>script.php</scriptfile></source>

<translate>
==== Completed mod_foo.xml ==== 
</translate>
<translate> The complete <tt>mod_foo.xml</tt> file is as follows:</translate>

<source lang="xml">

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="4.0" client="site" method="upgrade">
<name>MOD_FOO</name>
<creationDate>[DATE]</creationDate>
<author>[AUTHOR]</author>
<authorEmail>[AUTHOR_EMAIL]</authorEmail>
<authorUrl>[AUTHOR_URL]</authorUrl>
<copyright>[COPYRIGHT]</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<version>1.0</version>
<description>MOD_FOO_XML_DESCRIPTION</description>
<namespace>Joomla\Module\Foo</namespace>
<scriptfile>script.php</scriptfile>
<files>
<filename module="mod_foo">mod_foo.php</filename>
<folder>tmpl</folder>
<folder>Helper</folder>
<folder>language</folder>
<filename>mod_foo.xml</filename>
</files>
<config>
<fields name="params">
<fieldset name="basic">
<field
name="domain"
type="url"
label="MOD_FOO_FIELD_URL_LABEL"
filter="url"
/>
</fieldset>
<fieldset name="advanced">
<field
name="layout"
type="modulelayout"
label="JFIELD_ALT_LAYOUT_LABEL"
class="custom-select"
/>

<field
name="moduleclass_sfx"
type="textarea"
label="COM_MODULES_FIELD_MODULECLASS_SFX_LABEL"
rows="3"
/>

<field
name="cache"
type="list"
label="COM_MODULES_FIELD_CACHING_LABEL"
default="0"
>
<option value="1">JGLOBAL_USE_GLOBAL</option>
<option value="0">COM_MODULES_FIELD_VALUE_NOCACHING</option>
</field>

<field
name="cache_time"
type="number"
label="COM_MODULES_FIELD_CACHE_TIME_LABEL"
default="0"
/>

<field
name="cachemode"
type="hidden"
default="itemid"
>
<option value="itemid"></option>
</field>
</fieldset>
</fields>
</config>
</extension>
</source>

<translate>
== Test your module == 
</translate>
<translate> Now you can zip all files and install them via the Joomla Extension Manager.</translate>
<translate> Immediately after the installation, you will see the following information. This you had entered in the script so.</translate>
{{-}}
[[File:moduletutorial14-<translate> en</translate>.png|700px|center]]

<translate>
== Conclusion == 
</translate>
<translate> As you can see, Joomla offers you a lot to make your extension easy to use - right from the start.</translate>

<translate> You can find boilerplates hereː</translate>
* https://github.com/joomla-extensions/boilerplate/tree/master/plugins/system
<translate> The sample files for this Tutorial can be found hereː</translate>
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

<translate>

== Use Joomla Updaterː Adding Auto Update - Part 5 == 
</translate>

<translate>
=== Requirements === 
</translate>
<translate> You need Joomla! 4.x for this tutorial (as of writing currently Joomla! 4.0.0-alpha6-dev)</translate>

<translate>
=== Joomla Updater === 
</translate>
<translate> The first thing to do is to read the [[S:MyLanguage/J2.5:Managing_Component_Updates|Managing Component Upgrades with Joomla 2.5 - Part 1]] tutorial to give an idea of how the upgrade process works in Joomla. Whilst written for 2.5 the process hasn't changed. Also read [[S:MyLanguage/Deploying_an_Update_Server|Deploying an update server]] - this is what we'll be implementing in this tutorial.</translate>

<translate>
=== File Structure === 
</translate>
<translate> We will create/change the following files:</translate>
<translate> * <tt>mod_foo.xml</tt> - The only way to update our existing module is to add in a update server - for example <tt><nowiki>http://www.example.com/foo_update.xmɭ</nowiki></tt> - into the xml file.</translate>
<translate> * <tt>foo_update.xml</tt> - Then we have to create the XML file for the update server at <tt><nowiki>http://www.example.com/foo_update.xmɭ</nowiki></tt> to let Joomla know an update is available.</translate>

<translate>
==== Editing mod_foo.xml ==== 
</translate>
<translate> To add our update server, we need to insert the following lines in your XML-File</translate>

<source lang="php">

<updateservers>
<server type="extension" priority="1" name="[PROJECT_NAME]">https://www.example.com/mod_foo.xml</server>
</updateservers>

</source>

<translate>
==== Completed mod_foo.xml ==== 
</translate>
<translate> The complete <tt>mod_foo.xml</tt> file is as follows:</translate>

<source lang="xml">

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="4.0" client="site" method="upgrade">
<name>MOD_FOO</name>
<creationDate>[DATE]</creationDate>
<author>[AUTHOR]</author>
<authorEmail>[AUTHOR_EMAIL]</authorEmail>
<authorUrl>[AUTHOR_URL]</authorUrl>
<copyright>[COPYRIGHT]</copyright>
<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
<version>1.0</version>
<description>MOD_FOO_XML_DESCRIPTION</description>
<namespace>Joomla\Module\Foo</namespace>
<files>
<filename module="mod_foo">mod_foo.php</filename>
<folder>tmpl</folder>
<folder>Helper</folder>
<folder>language</folder>
<filename>mod_foo.xml</filename>
</files>
<updateservers>
<server type="extension" priority="1" name="[PROJECT_NAME]">https://www.example.com/mod_foo.xml</server>
</updateservers>
<config>
<fields name="params">
<fieldset name="basic">
<field
name="domain"
type="url"
label="MOD_FOO_FIELD_URL_LABEL"
filter="url"
/>
</fieldset>
<fieldset name="advanced">
<field
name="layout"
type="modulelayout"
label="JFIELD_ALT_LAYOUT_LABEL"
class="custom-select"
/>

<field
name="moduleclass_sfx"
type="textarea"
label="COM_MODULES_FIELD_MODULECLASS_SFX_LABEL"
rows="3"
/>

<field
name="cache"
type="list"
label="COM_MODULES_FIELD_CACHING_LABEL"
default="0"
>
<option value="1">JGLOBAL_USE_GLOBAL</option>
<option value="0">COM_MODULES_FIELD_VALUE_NOCACHING</option>
</field>

<field
name="cache_time"
type="number"
label="COM_MODULES_FIELD_CACHE_TIME_LABEL"
default="0"
/>

<field
name="cachemode"
type="hidden"
default="itemid"
>
<option value="itemid"></option>
</field>
</fieldset>
</fields>
</config>
</extension>

</source>

<translate> So now that Joomla is searching for updates to our extension - let's create one to test out our process. But first we need to create the file <tt>foo_update.xml</tt>. So far we have only described the update server. We do not know yet if there is an update. In the file <tt>foo_update.xml</tt> we indicate when a new version is published and where it can be downloaded.</translate>

<translate>
=== Creating foo_update.xml === 
</translate>
<translate> Now we have to create the XML file at <tt><nowiki>http://www.example.com/foo_update.xml</nowiki></tt> to let Joomla know an update is available.</translate>

<translate>
==== Completed foo_update.xml ==== 
</translate>
<translate> The complete <tt>foo_update.xml</tt> file is as follows:</translate>

<source lang="xml">

<?xml version="1.0" ?>

<updates>
<update>
<name>Foo</name>
<description>This is mod_foo 1.0.1</description>
<element>mod_foo</element>
<type>module</type>
<version>1.0.1</version>
<downloads>
<downloadurl type="full" format="zip">http://www.example.com/mod_foo_101.zip</downloadurl>
</downloads>
<maintainer>Joomla</maintainer>
<maintainerurl>http://www.example.com</maintainerurl>
<targetplatform name="joomla" version="4.0"/>
<client>site</client>
</update>
</updates>

</source>

<translate> After uploading this file to the address <tt><nowiki>https://www.example.com/mod_foo.xml</nowiki></tt> the update will be displayed in the Joomla backend.</translate>

<translate>
=== Test your module update === 
</translate>
<translate> Create a copy of the module as it is now. Then let's update the version number to 1.0.1. Now you can zip all files. After that you should load your zip to the URL <tt><nowiki>http://www.example.com/mod_foo_101.zip</nowiki></tt>. Now you can update your module via the Joomla Updater.</translate>

<translate>
=== Commercial Modules === 
</translate>
<translate> Note that in our files we have linked to the extensions updates xml file. And from that xml file we have a location for the zip of the module. This means that if someone was to track this backwards they could find the physical source of your modules zip file. If you don't do like this, you can find a solution in this PRː https://github.com/joomla/joomla-cms/pull/15185 .</translate>

<translate>
=== Conclusion === 
</translate>
<translate> With the Joomla updater, you can easily reach all users and tell them that there is a new version. Even the update itself is easy.</translate>

<translate> Each extension should use an update server. Especially for security reasons.</translate>

<translate> You can find boilerplates hereː</translate>
* https://github.com/joomla-extensions/boilerplate/tree/master/plugins/system
<translate> The sample files for this Tutorial can be found hereː</translate>
* https://github.com/astridx/boilerplate/tree/tutorial/tutorial/modules

<noinclude>
[[Category:Beginner Development{{#translation:}}]]
[[Category:Tutorials{{#translation:}}]]
[[Category:Tutorials in a Series{{#translation:}}]]
[[Category:Development{{#translation:}}]]
[[Category:Module Development{{#translation:}}]]
[[Category:Joomla! 4.x{{#translation:}}]]
[[Category:Joomla! 4.0{{#translation:}}]]
</noinclude>

J3.x:User Action Logs

2019-02-05T05:15:16Z

Garkell: Include namespace

<noinclude>{{Joomla version|version=3.9}}</noinclude>
{{Top portal heading|color=white-bkgd|icon=magic|icon-color=#5091cd|size=3x|text-color=#333|title=Tutorial<br />
How to Use the New Action Logging System}}

As of Joomla 3.9, Joomla introduced an action logging system.<br />

This system is the finalization of the [https://magazine.joomla.org/issues/issue-aug-2016/item/3111-gsoc-recording-actions-logs-accessible-by-super-admin-status-update "Recording Action Logs" project from GSoC 2016]. This system provides an infrastructure to create an audit log of activity performed on a website and can be fine tuned to the site admin's preferences. Extensions are able to hook into this system to add custom messages or have the system process standard CRUD actions.
<br />

In this tutorial, you will find information on how to set up this new system.

'''Note: Only Super Users have access to the Action Logging system.'''

==Component==

===User Actions Log Dashboard===
Navigate to {{rarr|Users,User Actions Log}} to access the dashboard.

[[Image:Joomla-39-action-logs-dashboard-en.png|800px]]

From this screen a Super User has a global overview of all activities performed on a site by users and has the ability to review, export, delete and purge entries.

To learn more, please see:
*[[S:MyLanguage/Help38:Components_Actionlogs|User Actions Log interface]]
*[[S:MyLanguage/Help38:Components_User_Actionlogs_Options| User Actions Log Options]]

==Plugin==

===System - User Actions Log===
Once enabled, this plugin allows to define the number of days after which the logs will be deleted.

===Action Log===
Once enabled, this plugin allows to record the actions of users for the core extensions.

===Privacy - Action Logs===
Once enabled, this plugin allows to export the action log data for a user's privacy request.

==Module==

===Action Logs - Latest Module===
This admin module shows on the control panel a list of the latest actions performed on a site.

[[Image:Joomla-39-action-logs-latest-module-en.png|800px]]

'''Note:''' The module is not displayed by default on sites upgrading to Joomla 3.9. In order to display it on your control panel, navigate to {{rarr|Extensions,Manage,Manage,Enable the System - User Actions Log plugin}} and then go to {{rarr|Extensions,Modules,Administrator,New,Action Logs-Latest}}

Please see also: [[S:MyLanguage/Help38:Extensions_Module_Manager_Admin_Latestactions|Latest Actions Admin Module]].

==How to hook an extension to the system==
I was very keen to utilise this function from within one of my components and so this is my attempt to help others who wish to do the same. Please feel free to edit this section where my code can be improved or corrected.<br />
===Component Installation Script===
Add the extension to the table (#__action_logs_extensions) so that it will appear in the configuration of User Action Logs.<br />
<source lang="php">
$extension = 'com_mycomponent';
$db = \Joomla\CMS\Factory::getDbo();
$db->setQuery(' INSERT into #__action_logs_extensions (extension) VALUES ('.$db->Quote($extension).') ' );
try {
// If it fails, it will throw a RuntimeException
$result = $db->execute();
} catch (RuntimeException $e) {
\Joomla\CMS\Factory::getApplication()->enqueueMessage($e->getMessage());
return false;
}
</source>
Add the extension configuration to the table (#__action_log_config) so that your actions data will be captured.<br />
<source lang="php">
$logConf = new stdClass();
$logConf->id = 0;
$logConf->type_title = 'transaction';
$logConf->type_alias = $extension;
$logConf->id_holder = 'id';
$logConf->title_holder = 'trans_desc';
$logConf->table_name = '#__mycomponent_transaction';
$logConf->text_prefix = 'COM_MYCOMPONENT_TRANSACTION';

try {
// If it fails, it will throw a RuntimeException
// Insert the object into the table.
$result = Factory::getDbo()->insertObject('#__action_log_config', $logConf);
} catch (RuntimeException $e) {
\Joomla\CMS\Factory::getApplication()->enqueueMessage($e->getMessage());
return false;
}
</source>
Of course it would be best to perform some checking to ensure that the record doesn't already exist.<br />
<br />
===Component Helper===
I utilise my component helper to perform the storing of actions.<br />
<source lang="php">
/**
* Record transaction details in log record
* @param object $user Saves getting the current user again.
* @param int $tran_id The transaction id just created or updated
* @param int $id Passed id reference from the form to identify if new record
* @return boolean True
*/
public static function recordActionLog($user = null, $tran_id = 0, $id = 0)
{
// get the component details such as the id
$extension = MycomponentHelper::getExtensionDetails('com_mycomponent');
// get the transaction details for use in the log for easy reference
$tran = MycomponentHelper::getTransaction($tran_id);
$con_type = "transaction";
if ($id === 0) { $type = 'New '; } else { $type = 'Update '; }

$message = array();
$message['action'] = $con_type;
$message['type'] = $type . $tran->tran_type . ' - '.$tran->tran_desc . ' $' . $tran->tran_amount;
$message['id'] = $tran->id;
$message['title'] = $extension->name;
$message['extension_name'] = $extension->name;
$message['itemlink'] = "index.php?option=com_mycomponent&task=transaction.edit&id=".$tran->id;
$message['userid'] = $user->id;
$message['username'] = $user->username;
$message['accountlink'] = "index.php?option=com_users&task=user.edit&id=".$user->id;

$messages = array($message);

$messageLanguageKey = Text::_('COM_MYCOMPONENT_TRANSACTION_LINK');
$context = $extension->name.'.'.$con_type;

$fmodel = MycomponentHelper::getForeignModel('Actionlog', 'ActionlogsModel');

$fmodel->addLog($messages, $messageLanguageKey, $context, $user->id);

return true;
}

/**
* Get the Model from another component for use
* @param string $name The model name. Optional. Default to my own for safety.
* @param string $prefix The class prefix. Optional
* @param array $config Configuration array for model. Optional
* @return object The model
*/
public function getForeignModel($name = 'Transaction', $prefix = 'MycomponentModel', $config = array('ignore_request' => true))
{
\Joomla\CMS\MVC\Model\ItemModel::addIncludePath(JPATH_ADMINISTRATOR . '/components/com_actionlogs/models', 'ActionlogsModelActionlog');
$fmodel = \Joomla\CMS\MVC\Model\ItemModel::getInstance($name, $prefix, $config);

return $fmodel;
}

</source>
===Front End Transaction Form===
Now that the foundations are set, we just need to trigger the process. I'm capturing information about a transaction that is created or update and I have a model called transactionform.php. It is in the Save method that I want to capture a log.

<source lang="php">
// So the code above this point checks and does what it should do and then after the successful save of the record, we check for the parameter setting to see if logging is required, we pass key elements to recordActionLog.
$table = $this->getTable();

if ($table->save($data) === true) {

/* ---------------------------------------------------------------- */
// trigger transaction log if required
$act_log = $params->get('act_log', 0);
if ($act_log && $table->id) {
// gather information and log in a new action log record
MycomponentHelper::recordActionLog($user, $table->id, $data['id']);
}
/* ---------------------------------------------------------------- */

return $table->id;
} else {
return false;
}
</source>
===Language File===
Finally, to help with the Action Log Listing in the admin side of Joomla!, we want to set some key elements of data to be displayed in the language file en-GB.com_mycomponent.ini.<br />
COM_MYCOMPONENT_TRANSACTION_LINK="User <a href='{accountlink}'>{username}</a> created a transaction ( <a href='{itemlink}'>{type}</a> )"<br />
<br />
Hope this helps.

<noinclude>
[[Category:Components]]
[[Category:Joomla! 3.9]]
[[Category:Plugins]]
[[Category:Modules]]
[[Category:User Action Logs]]
</noinclude>

J3.x:User Action Logs

2019-02-05T04:35:59Z

Garkell: Sample of Hooking into Action Logs

<noinclude>{{Joomla version|version=3.9}}</noinclude>
{{Top portal heading|color=white-bkgd|icon=magic|icon-color=#5091cd|size=3x|text-color=#333|title=Tutorial<br />
How to Use the New Action Logging System}}

As of Joomla 3.9, Joomla introduced an action logging system.<br />

This system is the finalization of the [https://magazine.joomla.org/issues/issue-aug-2016/item/3111-gsoc-recording-actions-logs-accessible-by-super-admin-status-update "Recording Action Logs" project from GSoC 2016]. This system provides an infrastructure to create an audit log of activity performed on a website and can be fine tuned to the site admin's preferences. Extensions are able to hook into this system to add custom messages or have the system process standard CRUD actions.
<br />

In this tutorial, you will find information on how to set up this new system.

'''Note: Only Super Users have access to the Action Logging system.'''

==Component==

===User Actions Log Dashboard===
Navigate to {{rarr|Users,User Actions Log}} to access the dashboard.

[[Image:Joomla-39-action-logs-dashboard-en.png|800px]]

From this screen a Super User has a global overview of all activities performed on a site by users and has the ability to review, export, delete and purge entries.

To learn more, please see:
*[[S:MyLanguage/Help38:Components_Actionlogs|User Actions Log interface]]
*[[S:MyLanguage/Help38:Components_User_Actionlogs_Options| User Actions Log Options]]

==Plugin==

===System - User Actions Log===
Once enabled, this plugin allows to define the number of days after which the logs will be deleted.

===Action Log===
Once enabled, this plugin allows to record the actions of users for the core extensions.

===Privacy - Action Logs===
Once enabled, this plugin allows to export the action log data for a user's privacy request.

==Module==

===Action Logs - Latest Module===
This admin module shows on the control panel a list of the latest actions performed on a site.

[[Image:Joomla-39-action-logs-latest-module-en.png|800px]]

'''Note:''' The module is not displayed by default on sites upgrading to Joomla 3.9. In order to display it on your control panel, navigate to {{rarr|Extensions,Manage,Manage,Enable the System - User Actions Log plugin}} and then go to {{rarr|Extensions,Modules,Administrator,New,Action Logs-Latest}}

Please see also: [[S:MyLanguage/Help38:Extensions_Module_Manager_Admin_Latestactions|Latest Actions Admin Module]].

==How to hook an extension to the system==
I was very keen to utilise this function from within one of my components and so this is my attempt to help others who wish to do the same. Please feel free to edit this section where my code can be improved or corrected.<br />
===Component Installation Script===
Add the extension to the table (#__action_logs_extensions) so that it will appear in the configuration of User Action Logs.<br />
<source lang="php">
$extension = 'com_mycomponent';
$db = Factory::getDbo();
$db->setQuery(' INSERT into #__action_logs_extensions (extension) VALUES ('.$db->Quote($extension).') ' );
try {
// If it fails, it will throw a RuntimeException
$result = $db->execute();
} catch (RuntimeException $e) {
Factory::getApplication()->enqueueMessage($e->getMessage());
return false;
}
</source>
Add the extension configuration to the table (#__action_log_config) so that your actions data will be captured.<br />
<source lang="php">
$logConf = new stdClass();
$logConf->id = 0;
$logConf->type_title = 'transaction';
$logConf->type_alias = $extension;
$logConf->id_holder = 'id';
$logConf->title_holder = 'trans_desc';
$logConf->table_name = '#__mycomponent_transaction';
$logConf->text_prefix = 'COM_MYCOMPONENT_TRANSACTION';

try {
// If it fails, it will throw a RuntimeException
// Insert the object into the table.
$result = Factory::getDbo()->insertObject('#__action_log_config', $logConf);
} catch (RuntimeException $e) {
Factory::getApplication()->enqueueMessage($e->getMessage());
return false;
}
</source>
Of course it would be best to perform some checking to ensure that the record doesn't already exist.<br />
<br />
===Component Helper===
I utilise my component helper to perform the storing of actions.<br />
<source lang="php">
/**
* Record transaction details in log record
* @param object $user Saves getting the current user again.
* @param int $tran_id The transaction id just created or updated
* @param int $id Passed id reference from the form to identify if new record
* @return boolean True
*/
public static function recordActionLog($user = null, $tran_id = 0, $id = 0)
{
// get the component details such as the id
$extension = MycomponentHelper::getExtensionDetails('com_mycomponent');
// get the transaction details for use in the log for easy reference
$tran = MycomponentHelper::getTransaction($tran_id);
$con_type = "transaction";
if ($id === 0) { $type = 'New '; } else { $type = 'Update '; }

$message = array();
$message['action'] = $con_type;
$message['type'] = $type . $tran->tran_type . ' - '.$tran->tran_desc . ' $' . $tran->tran_amount;
$message['id'] = $tran->id;
$message['title'] = $extension->name;
$message['extension_name'] = $extension->name;
$message['itemlink'] = "index.php?option=com_mycomponent&task=transaction.edit&id=".$tran->id;
$message['userid'] = $user->id;
$message['username'] = $user->username;
$message['accountlink'] = "index.php?option=com_users&task=user.edit&id=".$user->id;

$messages = array($message);

$messageLanguageKey = Text::_('COM_MYCOMPONENT_TRANSACTION_LINK');
$context = $extension->name.'.'.$con_type;

$fmodel = MycomponentHelper::getForeignModel('Actionlog', 'ActionlogsModel');

$fmodel->addLog($messages, $messageLanguageKey, $context, $user->id);

return true;
}

/**
* Get the Model from another component for use
* @param string $name The model name. Optional. Default to my own for safety.
* @param string $prefix The class prefix. Optional
* @param array $config Configuration array for model. Optional
* @return object The model
*/
public function getForeignModel($name = 'Transaction', $prefix = 'MycomponentModel', $config = array('ignore_request' => true))
{
ItemModel::addIncludePath(JPATH_ADMINISTRATOR . '/components/com_actionlogs/models', 'ActionlogsModelActionlog');
$fmodel = ItemModel::getInstance($name, $prefix, $config);

return $fmodel;
}

</source>
===Front End Transaction Form===
Now that the foundations are set, we just need to trigger the process. I'm capturing information about a transaction that is created or update and I have a model called transactionform.php. It is in the Save method that I want to capture a log.

<source lang="php">
// So the code above this point checks and does what it should do and then after the successful save of the record, we check for the parameter setting to see if logging is required, we pass key elements to recordActionLog.
$table = $this->getTable();

if ($table->save($data) === true) {

/* ---------------------------------------------------------------- */
// trigger transaction log if required
$act_log = $params->get('act_log', 0);
if ($act_log && $table->id) {
// gather information and log in a new action log record
MycomponentHelper::recordActionLog($user, $table->id, $data['id']);
}
/* ---------------------------------------------------------------- */

return $table->id;
} else {
return false;
}
</source>
===Language File===
Finally, to help with the Action Log Listing in the admin side of Joomla!, we want to set some key elements of data to be displayed in the language file en-GB.com_mycomponent.ini.<br />
COM_MYCOMPONENT_TRANSACTION_LINK="User <a href='{accountlink}'>{username}</a> created a transaction ( <a href='{itemlink}'>{type}</a> )"<br />
<br />
Hope this helps.

<noinclude>
[[Category:Components]]
[[Category:Joomla! 3.9]]
[[Category:Plugins]]
[[Category:Modules]]
[[Category:User Action Logs]]
</noinclude>

Captcha form field type

2015-11-20T04:45:34Z

Garkell: Add namespace but I don't know what it means.

<noinclude><languages /></noinclude>
<translate>
Provides the use of a captcha plugin.</translate>

<translate>
* '''type''' (mandatory) must be ''captcha''.</translate>
<translate>
* '''name''' (mandatory) is the unique name of the field.</translate>
<translate>
* '''validate''' (mandatory optional ?) must be ''captcha''.</translate>
<translate>
* '''label''' (mandatory) (translatable) is the descriptive title of the field.</translate>
<translate>
* '''description''' (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.</translate>
<translate>
* '''namespace''' (optional) this is used on the com_contact component but I don't know enough about it to comment.</translate>

<translate>
Example XML Definition:</translate>
<source type="xml">
<field name="captcha" type="captcha" validate="captcha"
namespace="contact"
label="COM_CONTACT_CAPTCHA_LABEL"
description="COM_CONTACT_CAPTCHA_DESC" >
</field>
</source>

<noinclude>
<translate>

[[Category:Standard form field types]]
</translate>
</noinclude>

Captcha form field type

2015-11-20T04:38:51Z

Garkell: Change this to show how to use the captcha formfield rather than how to use the plugin type to select a captcha plugin.

<noinclude><languages /></noinclude>
<translate>
Provides the use of a captcha plugin.</translate>

<translate>
* '''type''' (mandatory) must be ''captcha''.</translate>
<translate>
* '''name''' (mandatory) is the unique name of the field.</translate>
<translate>
* '''validate''' (mandatory optional ?) must be ''captcha''.</translate>
<translate>
* '''label''' (mandatory) (translatable) is the descriptive title of the field.</translate>
<translate>
* '''description''' (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the drop-down box.</translate>

<translate>
Example XML Definition:</translate>
<source type="xml">
<field name="captcha" type="captcha" validate="captcha"
label="COM_CONTACT_FIELD_CAPTCHA_LABEL"
description="COM_CONTACT_FIELD_CAPTCHA_DESC" >
</field>
</source>

<noinclude>
<translate>

[[Category:Standard form field types]]
</translate>
</noinclude>

Plugins form field type

2015-11-20T04:34:18Z

Garkell: Add captcha example

<noinclude><languages /></noinclude>
<translate>
Provides a dropdown list of plugin options from the folder.</translate>

<translate>
* '''name''' (mandatory) is the unique name of the parameter.</translate>
<translate>
* '''type''' (mandatory) must be ''plugin''.</translate>
<translate>
* '''folder''' (mandatory) ''editor'' or ''captcha''.</translate>
<translate>
* '''label''' (mandatory) (translatable) is the descriptive title of the field.</translate>
<translate>
* '''description''' description text for the form field.</translate>

<translate>
Example XML Definition:</translate>
<source type="xml">
<field name="editor" type="plugins" folder="editors"
description="COM_USERS_USER_FIELD_EDITOR_DESC"
label="COM_USERS_USER_FIELD_EDITOR_LABEL" >
<option value="">JOPTION_USE_DEFAULT</option>
</field>
<field name="captcha" type="plugins" folder="captcha"
label="COM_CONTACT_FIELD_CAPTCHA_LABEL"
description="COM_CONTACT_FIELD_CAPTCHA_DESC"
default=""
filter="cmd" >
<option value="">JOPTION_USE_DEFAULT</option>
<option value="0">JOPTION_DO_NOT_USE</option>
</field>
</source>

<noinclude>
<translate>

[[Category:Standard form field types]]
</translate>
</noinclude>

Standard form field types

2015-11-20T04:30:27Z

Garkell:

<noinclude><languages /></noinclude>
<translate>
Numerous types of [[S:MyLanguage/form field|form field]] are built into Joomla!. The following table lists these standard types and their availability. Use the [[S:MyLanguage/Standard_form_field_types/Single-page_reference|single-page reference]] if you want to print all existing form field documentation.</translate>

<translate>
{{JVer|1.5}} Please note that many of these fields are available as [[S:MyLanguage/Parameter|parameter types]] in Joomla! 1.5. For a list of parameter types, see [[S:MyLanguage/J1.5:Standard parameter types|J1.5:Standard parameter types]]. For a comparison between form field and parameter types, see [[S:MyLanguage/Standard form field and parameter types|Standard form field and parameter types]].</translate>
{| class="wikitable" style="vertical-align:top; border:1px solid Sienna; background-color:Cornsilk;"
|- style="background-color:Wheat; font-weight:bold; text-align: left;"
!width=15%|<translate>
Type</translate>
!width=65%|<translate>
Description</translate>
!width=20%|<translate>
Availability</translate>
|-
|[[S:MyLanguage/Accesslevel form field type|<translate>
accesslevel</translate>]]
|<translate>
provides a drop down list of viewing access levels.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Cachehandler form field type|<translate>
cachehandler</translate>]]
|<translate>
provides a list of available cache handling options.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Calendar form field type|<translate>
calendar</translate>]]
|<translate>
provides a text box for entry of a date. An icon next to the text box provides a link to a pop-up calendar, which can also be used to enter the date value.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Captcha form field type|<translate>
captcha</translate>]]
|<translate>
provides the use of a captcha plugin.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Category form field type|<translate>
category</translate>]]
|<translate>
provides a drop down list of categories for an extension.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Checkbox form field type|<translate>
checkbox</translate>]]
|<translate>
provides a single checkbox to be checked or unchecked</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Checkboxes form field type|<translate>
checkboxes</translate>]]
|<translate>
provides unlimited checkboxes that can be used for multi-select.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/ChromeStyle form field type|<translate>
Chrome Style</translate>]]
|<translate>
provides a list of template chrome style options grouped by template.</translate>
|{{JVer|3.0}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Color form field type|<translate>
color</translate>]]
|<translate>
provides a color picker when clicking the input box.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/ContentLanguage form field type|<translate>
Content Language</translate>]]
|<translate>
Provides a list of content languages.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Contenttype form field type|<translate>
Content Type</translate>]]
|<translate>
Provides a list of content types.</translate>
|{{JVer|3.1}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Combo form field type|<translate>
combo</translate>]]
|<translate>
provides a combo box field.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Componentlayout form field type|<translate>
componentlayout</translate>]]
|<translate>
provides a grouped list of core and template alternate layouts for a component item.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Contentlanguage form field type|<translate>
contentlanguage</translate>]]
|<translate>
provides a list of installed content languages for use in conjunction with the language switcher plugin.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/DatabaseConnection form field type|<translate>
Database Connection</translate>]]
|<translate>
Provides a list of available database connections, optionally limiting to a given list.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Editor form field type|<translate>
editor</translate>]]
|<translate>
provides an editor area field.</translate>
|{{JVer|1.6}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Editors form field type|<translate>
editors</translate>]]
|<translate>
Provides a drop down list of the available WYSIWYG editors. Since {{JVer|2.5}} use [[S:MyLanguage/Plugins form field type|plugins form field]] instead.</translate>
|{{JVer|1.6}}
|-
|[[S:MyLanguage/Email form field type|<translate>
email</translate>]]
|<translate>
provides an email field.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/File form field type|<translate>
file</translate>]]
|<translate>
Provides an input field for files</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Filelist form field type|<translate>
filelist</translate>]]
|<translate>
provides a drop down list of files from a specified directory.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Folderlist form field type|<translate>
folderlist</translate>]]
|<translate>
provides a drop down list of folders from a specified directory.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Groupedlist form field type|<translate>
groupedlist</translate>]]
|<translate>
provides a drop down list of items organized into groups.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/HeaderTag form field type|<translate>
header tag</translate>]]
|<translate>
provides a drop down list of the header tags (h1-h6)</translate>.
|{{JVer|3.0}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Helpsite form field type|<translate>
helpsite</translate>]]
|<translate>
provides a drop down list of the help sites for your Joomla installation.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Hidden form field type|<translate>
hidden</translate>]]
|<translate>
provides a hidden field for saving a form field whose value cannot be altered directly by a user in the Administrator (it can be altered in code or by editing the ''params.ini'' file).</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Imagelist form field type|<translate>
imagelist</translate>]]
|<translate>
provides a drop down list of image files in a specified directory.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|-
|[[S:MyLanguage/Integer form field type|<translate>
integer</translate>]]
|<translate>
provides a drop down list of integers between a minimum and maximum.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Language form field type|<translate>
language</translate>]]
|<translate>
provides a drop down list of the installed languages for the Front-end or Back-end.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/List form field type|<translate>
list</translate>]]
|<translate>
provides a drop down list of custom-defined entries.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Media form field type|<translate>
media</translate>]]
|<translate>
provides modal access to the media manager for insertion of images with upload for users with appropriate permissions.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Menu form field type|<translate>
menu</translate>]]
|<translate>
provides a drop down list of the available menus from your Joomla site.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Menuitem form field type|<translate>
Menu Item</translate>]]
|<translate>
provides a drop down list of the available menu items from your Joomla site.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[Meter form field type|<translate>
meter</translate>]]
|<translate>
Provides a meter to show value in a range.</translate>
|{{JVer|3.2}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Modulelayout form field type|<translate>
Module Layout</translate>]]
|<translate>
provides a list of alternative layout for a module grouped by core and template.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/ModuleOrder form field type|<translate>
Module Order</translate>]]
|<translate>
Provides a drop down to set the ordering of module in a given position</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/ModulePosition form field type|<translate>
Module Position</translate>]]
|<translate>
provides a text input to set the position of a module.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/ModuleTag form field type|<translate>
Module Tag</translate>]]
|<translate>
provides a list of html5 elements (used to wrap a module in).</translate>
|{{JVer|3.0}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Note form field type|<translate>
note</translate>]]
|<translate>
supports a one line text field.</translate>
|{{JVer|3.1}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Number form field type|<translate>
number</translate>]]
|<translate>
Provides a one line text box with up-down handles to set a number in the field.</translate>
|{{JVer|3.2}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Password form field type|<translate>
password</translate>]]
|<translate>
provides a text box for entry of a password. The password characters will be obscured as they are entered.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Plugins form field type|<translate>
plugins</translate>]]
|<translate>
provides a list of plugins from a given folder.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Predefined List form field type|<translate>
predefinedlist</translate>]]
|<translate>
Form Field to load a list of predefined values.</translate>
|{{JVer|3.2}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Radio form field type|<translate>
radio</translate>]]
|<translate>
provides radio buttons to select different options.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Range form field type|<translate>
range</translate>]]
|<translate>
Provides a horizontal scroll bar to specify a value in a range.</translate>
|{{JVer|3.2}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Repeatable form field type|<translate>
repeatable</translate>]]
|<translate>
Allows form fields which can have as many options as the user desires.</translate>
|{{JVer|3.2}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Rules form field type|<translate>
rules</translate>]]
|<translate>
provides a matrix of group by action options for managing access control. Display depends on context.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Sessionhandler form field type|<translate>
sessionhandler</translate>]]
|<translate>
provides a drop down list of session handler options.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Spacer form field type|<translate>
spacer</translate>]]
|<translate>
provides a visual separator between form fields. It is purely a visual aid and no value is stored.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/SQL form field type|<translate>
sql</translate>]]
|<translate>
provides a drop down list of entries obtained by running a query on the Joomla Database. The first results column returned by the query provides the values for the drop down box.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Tag form field type|<translate>
tag</translate>]]
|<translate>
provides an entry point for tags (either AJAX or Nested).</translate>
|{{JVer|3.1}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Tel form field type|<translate>
tel</translate>]]
|<translate>
provides an input field for a telephone number.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Templatestyle form field type|<translate>
templatestyle</translate>]]
|<translate>
provides a drop down list of template styles.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Text form field type|<translate>
text</translate>]]
|<translate>
provides a text box for data entry.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Textarea form field type|<translate>
textarea</translate>]]
|<translate>
provides a text area for entry of multi-line text.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Timezone form field type|<translate>
timezone</translate>]]
|<translate>
provides a drop down list of time zones.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/URL form field type|<translate>
URL</translate>]]
|<translate>
provides a URL text input field.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/User form field type|<translate>
user</translate>]]
|<translate>
Field to select a user from a modal list. Displays User Name and stores User ID</translate>
|{{JVer|1.6}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/UserActive form field type|<translate>
useractive</translate>]]
|<translate>
Field to show a list of available user active statuses.</translate>
|{{JVer|3.2}} <translate>
and newer</translate>
|
|-
|[[S:MyLanguage/Usergroup form field type|<translate>
usergroup</translate>]]
|<translate>
provides a drop down list of user groups. Since {{JVer|3.2}} use [[S:MyLanguage/User Group List form field type|usergrouplist]] instead.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|
|-
|[[S:MyLanguage/User Group List form field type|<translate>
usergrouplist</translate>]]
|<translate>
Field to load a drop down list of available user groups. Replaces usergroup form field type.</translate>
|{{JVer|3.2}} <translate>
and newer</translate>
|
|-
|[[S:MyLanguage/User State form field type|<translate>
userstate</translate>]]
|<translate>
Field to load a list of available users statuses.</translate>
|{{JVer|3.2}} <translate>
and newer</translate>
|}

<noinclude>
<translate>

[[Category:Form fields]]
[[Category:Development Reference]]
</translate>
</noinclude>

Standard form field types

2015-11-20T04:29:07Z

Garkell: Changed the captcha formfield to be "use a captcha plugin" rather than a dropdown list to choose a captcha plugin.

<noinclude><languages /></noinclude>
<translate>
Numerous types of [[S:MyLanguage/form field|form field]] are built into Joomla!. The following table lists these standard types and their availability. Use the [[S:MyLanguage/Standard_form_field_types/Single-page_reference|single-page reference]] if you want to print all existing form field documentation.</translate>

<translate>
{{JVer|1.5}} Please note that many of these fields are available as [[S:MyLanguage/Parameter|parameter types]] in Joomla! 1.5. For a list of parameter types, see [[S:MyLanguage/J1.5:Standard parameter types|J1.5:Standard parameter types]]. For a comparison between form field and parameter types, see [[S:MyLanguage/Standard form field and parameter types|Standard form field and parameter types]].</translate>
{| class="wikitable" style="vertical-align:top; border:1px solid Sienna; background-color:Cornsilk;"
|- style="background-color:Wheat; font-weight:bold; text-align: left;"
!width=15%|<translate>
Type</translate>
!width=65%|<translate>
Description</translate>
!width=20%|<translate>
Availability</translate>
|-
|[[S:MyLanguage/Accesslevel form field type|<translate>
accesslevel</translate>]]
|<translate>
provides a drop down list of viewing access levels.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Cachehandler form field type|<translate>
cachehandler</translate>]]
|<translate>
provides a list of available cache handling options.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Calendar form field type|<translate>
calendar</translate>]]
|<translate>
provides a text box for entry of a date. An icon next to the text box provides a link to a pop-up calendar, which can also be used to enter the date value.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Captcha form field type|<translate>
captcha</translate>]]
|<translate>
provides a the use of a captcha plugin.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Category form field type|<translate>
category</translate>]]
|<translate>
provides a drop down list of categories for an extension.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Checkbox form field type|<translate>
checkbox</translate>]]
|<translate>
provides a single checkbox to be checked or unchecked</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Checkboxes form field type|<translate>
checkboxes</translate>]]
|<translate>
provides unlimited checkboxes that can be used for multi-select.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/ChromeStyle form field type|<translate>
Chrome Style</translate>]]
|<translate>
provides a list of template chrome style options grouped by template.</translate>
|{{JVer|3.0}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Color form field type|<translate>
color</translate>]]
|<translate>
provides a color picker when clicking the input box.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/ContentLanguage form field type|<translate>
Content Language</translate>]]
|<translate>
Provides a list of content languages.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Contenttype form field type|<translate>
Content Type</translate>]]
|<translate>
Provides a list of content types.</translate>
|{{JVer|3.1}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Combo form field type|<translate>
combo</translate>]]
|<translate>
provides a combo box field.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Componentlayout form field type|<translate>
componentlayout</translate>]]
|<translate>
provides a grouped list of core and template alternate layouts for a component item.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Contentlanguage form field type|<translate>
contentlanguage</translate>]]
|<translate>
provides a list of installed content languages for use in conjunction with the language switcher plugin.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/DatabaseConnection form field type|<translate>
Database Connection</translate>]]
|<translate>
Provides a list of available database connections, optionally limiting to a given list.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Editor form field type|<translate>
editor</translate>]]
|<translate>
provides an editor area field.</translate>
|{{JVer|1.6}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Editors form field type|<translate>
editors</translate>]]
|<translate>
Provides a drop down list of the available WYSIWYG editors. Since {{JVer|2.5}} use [[S:MyLanguage/Plugins form field type|plugins form field]] instead.</translate>
|{{JVer|1.6}}
|-
|[[S:MyLanguage/Email form field type|<translate>
email</translate>]]
|<translate>
provides an email field.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/File form field type|<translate>
file</translate>]]
|<translate>
Provides an input field for files</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Filelist form field type|<translate>
filelist</translate>]]
|<translate>
provides a drop down list of files from a specified directory.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Folderlist form field type|<translate>
folderlist</translate>]]
|<translate>
provides a drop down list of folders from a specified directory.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Groupedlist form field type|<translate>
groupedlist</translate>]]
|<translate>
provides a drop down list of items organized into groups.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/HeaderTag form field type|<translate>
header tag</translate>]]
|<translate>
provides a drop down list of the header tags (h1-h6)</translate>.
|{{JVer|3.0}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Helpsite form field type|<translate>
helpsite</translate>]]
|<translate>
provides a drop down list of the help sites for your Joomla installation.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Hidden form field type|<translate>
hidden</translate>]]
|<translate>
provides a hidden field for saving a form field whose value cannot be altered directly by a user in the Administrator (it can be altered in code or by editing the ''params.ini'' file).</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Imagelist form field type|<translate>
imagelist</translate>]]
|<translate>
provides a drop down list of image files in a specified directory.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|-
|[[S:MyLanguage/Integer form field type|<translate>
integer</translate>]]
|<translate>
provides a drop down list of integers between a minimum and maximum.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Language form field type|<translate>
language</translate>]]
|<translate>
provides a drop down list of the installed languages for the Front-end or Back-end.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/List form field type|<translate>
list</translate>]]
|<translate>
provides a drop down list of custom-defined entries.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Media form field type|<translate>
media</translate>]]
|<translate>
provides modal access to the media manager for insertion of images with upload for users with appropriate permissions.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Menu form field type|<translate>
menu</translate>]]
|<translate>
provides a drop down list of the available menus from your Joomla site.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Menuitem form field type|<translate>
Menu Item</translate>]]
|<translate>
provides a drop down list of the available menu items from your Joomla site.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[Meter form field type|<translate>
meter</translate>]]
|<translate>
Provides a meter to show value in a range.</translate>
|{{JVer|3.2}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Modulelayout form field type|<translate>
Module Layout</translate>]]
|<translate>
provides a list of alternative layout for a module grouped by core and template.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/ModuleOrder form field type|<translate>
Module Order</translate>]]
|<translate>
Provides a drop down to set the ordering of module in a given position</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/ModulePosition form field type|<translate>
Module Position</translate>]]
|<translate>
provides a text input to set the position of a module.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/ModuleTag form field type|<translate>
Module Tag</translate>]]
|<translate>
provides a list of html5 elements (used to wrap a module in).</translate>
|{{JVer|3.0}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Note form field type|<translate>
note</translate>]]
|<translate>
supports a one line text field.</translate>
|{{JVer|3.1}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Number form field type|<translate>
number</translate>]]
|<translate>
Provides a one line text box with up-down handles to set a number in the field.</translate>
|{{JVer|3.2}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Password form field type|<translate>
password</translate>]]
|<translate>
provides a text box for entry of a password. The password characters will be obscured as they are entered.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Plugins form field type|<translate>
plugins</translate>]]
|<translate>
provides a list of plugins from a given folder.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Predefined List form field type|<translate>
predefinedlist</translate>]]
|<translate>
Form Field to load a list of predefined values.</translate>
|{{JVer|3.2}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Radio form field type|<translate>
radio</translate>]]
|<translate>
provides radio buttons to select different options.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Range form field type|<translate>
range</translate>]]
|<translate>
Provides a horizontal scroll bar to specify a value in a range.</translate>
|{{JVer|3.2}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Repeatable form field type|<translate>
repeatable</translate>]]
|<translate>
Allows form fields which can have as many options as the user desires.</translate>
|{{JVer|3.2}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Rules form field type|<translate>
rules</translate>]]
|<translate>
provides a matrix of group by action options for managing access control. Display depends on context.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Sessionhandler form field type|<translate>
sessionhandler</translate>]]
|<translate>
provides a drop down list of session handler options.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Spacer form field type|<translate>
spacer</translate>]]
|<translate>
provides a visual separator between form fields. It is purely a visual aid and no value is stored.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/SQL form field type|<translate>
sql</translate>]]
|<translate>
provides a drop down list of entries obtained by running a query on the Joomla Database. The first results column returned by the query provides the values for the drop down box.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Tag form field type|<translate>
tag</translate>]]
|<translate>
provides an entry point for tags (either AJAX or Nested).</translate>
|{{JVer|3.1}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Tel form field type|<translate>
tel</translate>]]
|<translate>
provides an input field for a telephone number.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Templatestyle form field type|<translate>
templatestyle</translate>]]
|<translate>
provides a drop down list of template styles.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Text form field type|<translate>
text</translate>]]
|<translate>
provides a text box for data entry.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Textarea form field type|<translate>
textarea</translate>]]
|<translate>
provides a text area for entry of multi-line text.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/Timezone form field type|<translate>
timezone</translate>]]
|<translate>
provides a drop down list of time zones.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/URL form field type|<translate>
URL</translate>]]
|<translate>
provides a URL text input field.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/User form field type|<translate>
user</translate>]]
|<translate>
Field to select a user from a modal list. Displays User Name and stores User ID</translate>
|{{JVer|1.6}} <translate>
and newer</translate>
|-
|[[S:MyLanguage/UserActive form field type|<translate>
useractive</translate>]]
|<translate>
Field to show a list of available user active statuses.</translate>
|{{JVer|3.2}} <translate>
and newer</translate>
|
|-
|[[S:MyLanguage/Usergroup form field type|<translate>
usergroup</translate>]]
|<translate>
provides a drop down list of user groups. Since {{JVer|3.2}} use [[S:MyLanguage/User Group List form field type|usergrouplist]] instead.</translate>
|{{JVer|2.5}} <translate>
and newer</translate>
|
|-
|[[S:MyLanguage/User Group List form field type|<translate>
usergrouplist</translate>]]
|<translate>
Field to load a drop down list of available user groups. Replaces usergroup form field type.</translate>
|{{JVer|3.2}} <translate>
and newer</translate>
|
|-
|[[S:MyLanguage/User State form field type|<translate>
userstate</translate>]]
|<translate>
Field to load a list of available users statuses.</translate>
|{{JVer|3.2}} <translate>
and newer</translate>
|}

<noinclude>
<translate>

[[Category:Form fields]]
[[Category:Development Reference]]
</translate>
</noinclude>

Using JLog

2014-10-06T06:20:34Z

Garkell: Added comma in the addLogger array.

{{version|2.5,3.2|platform=11.1}}{{RightTOC}}
Using JLog can be very useful in components when analysing the performance of custom extensions - or analysing where extensions are giving issues. Note this should be used in tandem with php exceptions - not as a replacement. See [[Exceptions and Logging in Joomla 1.7 and Joomla Platform 11.1]] for more information on this

== Calling the class ==

To use JLog you need to call the JLog class. Done through the following code:

jimport('joomla.log.log');

== Basic File Logging ==

Often you may wish to display an error log message and log to an error file. Joomla allows this natively through the [[JLog::add]] function. For example:

JLog::add(JText::_('JTEXT_ERROR_MESSAGE'), JLog::WARNING, 'jerror');

Adding the category of jerror means that this message will also be displayed to users. To only write to file you can easily drop that parameter and simply use

JLog::add(JText::_('JTEXT_ERROR_MESSAGE'), JLog::WARNING);

== Logging a specific extension ==
Sometimes it may be useful to log the errors to a specific file. In this case you can

JLog::addLogger(
array(
// Sets file name
'text_file' => 'com_helloworld.errors.php'
),
// Sets messages of all log levels to be sent to the file
JLog::ALL,
// The log category/categories which should be recorded in this file
// In this case, it's just the one category from our extension, still
// we need to put it inside an array
array('com_helloworld')
);

Now remember to change the category when you add a log message. Such as in the example below.

JLog::add(JText::_('JTEXT_ERROR_MESSAGE'), JLog::WARNING, 'com_helloworld');

'''Note:''' You may wish to combine this with the [[Display error messages and notices]] section to display visable error notifications to users.

== Logging specific priorities ==

You can also add an additional logger to capture only critical and emergency log notifications:

JLog::addLogger(
array(
// Sets file name
'text_file' => 'com_helloworld.critical_emergency.php'
),
// Sets critical and emergency log level messages to be sent to the file
JLog::CRITICAL + JLog::EMERGENCY,
// The log category which should be recorded in this file
array('com_helloworld')
);

You can also exclude a specific category from being included. For example, to log all but DEBUG messages:

JLog::addLogger(
array(
// Sets file name
'text_file' => 'com_helloworld.all_but_debug.php'
),
// Sets all but DEBUG log level messages to be sent to the file
JLog::ALL & ~JLog::DEBUG,
// The log category which should be recorded in this file
array('com_helloworld')
);

Notice how bitwise operations (bitwise AND, &; and bitwise NOT, ~)
are used to calculate the accepted log levels.

== Formatting the logfile ==

The first parameter to addLogger can have a few optional additional settings
in addition to the 'text_file' entry.

There is for example the entry '''text_entry_format''', specifying the format
of each line in your logfile.

The default format is

'{DATETIME} {PRIORITY} {CATEGORY} {MESSAGE}'

Here is an example of a different format which shows how to omit the category:

JLog::addLogger(
array(
// Sets file name
'text_file' => 'com_helloworld.critical_emergency.php',
// Sets the format of each line
'text_entry_format' => '{DATETIME} {PRIORITY} {MESSAGE}'
),
// Sets all but DEBUG log level messages to be sent to the file
JLog::ALL & ~JLog::DEBUG,
// The log category which should be recorded in this file
array('com_helloworld')
);

In addition to the placeholders shown above in the default string, the following
values are available:

{CLIENTIP}
{TIME}
{DATE}

There is an additional optional boolean parameter '''text_file_no_php''', which specifies
whether the log file is prepended with the usual prefix of

#
#<?php die('Forbidden.');?>

'''Note:''' Usually you should not set this setting to false. Log files should not be readable
from the outside, since they can provide valuable information about your system for attackers.
Only dabble with this if you know what you're doing!

Furthermore, if you want to store the log file somewhere else than the logging path configured
in the Joomla! settings, you can there is the '''text_file_path''' setting.

[[Category:Development]]
[[category:Joomla! 1.7]]
[[category:Joomla! 2.5]]
[[category:Joomla! 3.0]]

Editor form field type

2014-06-15T06:01:13Z

Garkell: Add example for buttons and hiding specific ones

The '''Editor''' field type provides a WYSIWYG editor.

* '''type''' (mandatory) must be ''editor''.
* '''name''' (mandatory) is the unique name of the parameter.
* '''label''' (mandatory) (translatable) is the descriptive title of the field.
* '''width''' (optional) defines the width (in pixels) of the wysiwyg editor and defaults to 100%.
* '''height''' (optional) defines the height (in pixels) of the wysiwyg editor and defaults to 250px.
* '''cols''' (optional) defines the width of the editor (in columns).
* '''rows''' (optional) defines the height of the editor (in rows).
* '''buttons''' (optional) can be an array of plugin buttons to be excluded or set to false. The default editors-xtd are: article, image, pagebreak and readmore.
* '''hide''' (optional) array of plugin buttons to be hidden. eg... set buttons="true" hide="readmore,pagebreak"
* '''editor''' specifies the editor to be used and can include two options (editor="desired|alternative")
* '''filter''' (optional) allow the system to save certain html tags or raw data.

Example XML Definition
<source lang="xml"><field name="test1" label ="Test Field" type="editor" width="300" filter="safehtml" /></source>
<noinclude>

=== See also ===
* [[Textarea parameter type]]
* [[Standard form field types|Table of all standard form field types]]
[[Category:Standard form field types]]
</noinclude>

J3.x:Developing an MVC Component/Adding a model to the site part

2014-05-18T01:01:48Z

Garkell: Added "/" at the end of <schemapath> text

{{:J3.1:Developing a MVC Component}}

== Introduction ==
This tutorial is part of the [[J3.2:Developing a MVC Component | Developing a MVC Component for Joomla! 3.2]] tutorial. You are encouraged to read the previous parts of the tutorial before reading this.

== Adding a model ==
In the Joomla framework, models are responsible for managing the data. The first function that has to be written for a model is a ''get'' function. It returns data to the caller. In our case, the caller will be the ''HelloWorldViewHelloWorld'' view. By default, the model named ''HelloWorldModelHelloWorld'' residing in ''site/models/helloworld.php'' is the main model associated to this view.

So let's have a quick look at the naming conventions with an example, since the naming convention are the actual magic, that make everything work:

The class ''HelloWorldView'''HelloWorld''''' resides in ''site/views/'''helloworld'''/view.html.php'' and will make use of the class ''HelloWorldModel'''HelloWorld''''' in the file ''site/models/'''helloworld'''.php''

So let's just assume we want to use an imaginary view ''fluffy'', you would have to have:

The class ''HelloWorldView'''Fluffy''''' which resides in ''site/views/'''fluffy'''/view.html.php''. The view will make use of ''HelloWorldModel'''Fluffy''''' in the file ''site/models/'''fluffy'''.php''. Note: the actual screen of the view: ''site/views/'''fluffy'''/tmpl/default.php'' is required as well to make this example work.

Breaking any of these bold conventions will lead to errors or a blank page.

So back to the actual implementation of the single classes:

With your favorite file manager and editor put a ''site/models/helloworld.php'' file containing:

<span id="site/models/helloworld.php">
''site/models/helloworld.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import Joomla modelitem library
jimport('joomla.application.component.modelitem');

/**
* HelloWorld Model
*/
class HelloWorldModelHelloWorld extends JModelItem
{
/**
* @var string msg
*/
protected $msg;

/**
* Get the message
* @return string The message to be displayed to the user
*/
public function getMsg()
{
if (!isset($this->msg))
{
$this->msg = 'Hello World!';
}
return $this->msg;
}
}
</source>
</span>

The ''HelloWorldViewHelloWorld'' class asks the model for data using the ''get'' method of the ''JViewLegacy'' class:

<span id="site/views/helloworld/view.html.php">
''site/views/helloworld/view.html.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import Joomla view library
jimport('joomla.application.component.view');

/**
* HTML View class for the HelloWorld Component
*/
class HelloWorldViewHelloWorld extends JViewLegacy
{
// Overwriting JView display method
function display($tpl = null)
{
// Assign data to the view
$this->msg = $this->get('Msg');

// Check for errors.
if (count($errors = $this->get('Errors')))
{
JLog::add(implode('<br />', $errors), JLog::WARNING, 'jerror');
return false;
}
// Display the view
parent::display($tpl);
}
}
</source>
</span>

Note: $this->get() is a member of JViewLegacy::get which is a proxy to get* methods of the default model where * is populated with the value of the first parameter passed to get()

Also modify your ''helloworld.xml'' file to indicate use of models and the new version:

<span id="helloworld.xml">
''helloworld.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="3.2.0" method="upgrade">

<name>Hello World!</name>

<creationDate>January 2014</creationDate>
<author>John Doe</author>
<authorEmail>john.doe@example.org</authorEmail>
<authorUrl>http://www.example.org</authorUrl>
<copyright>Copyright Info</copyright>
<license>License Info</license>

<version>0.0.4</version>

<description>Description of the Hello World component ...</description>

<update> 
<schemas>
<schemapath type="mysql">sql/updates/mysql/</schemapath>
</schemas>
</update>



<files folder="site">
<filename>index.html</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>
<folder>views</folder>
<folder>models</folder>
</files>

<administration>

<menu>Hello World!</menu>


<files folder="admin">

<filename>index.html</filename>
<filename>helloworld.php</filename>

<folder>sql</folder>
</files>
</administration>

</extension>
</source>
</span>

== Packaging the component ==

Content of your code directory
* ''[[#helloworld.xml|helloworld.xml]]''
* ''[[J3.2:Developing_a_MVC_Component/Adding_a_view_to_the_site_part#site/helloworld.php|site/helloworld.php]]''
* ''[[J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|site/index.html]]''
* ''[[J3.2:Developing_a_MVC_Component/Adding_a_view_to_the_site_part#site/controller.php|site/controller.php]]''
* ''[[J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|site/views/index.html]]''
* ''[[J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|site/views/helloworld/index.html]]''
* ''[[J3.2:Developing_a_MVC_Component/Adding_a_view_to_the_site_part#site/views/helloworld/view.html.php|site/views/helloworld/view.html.php]]''
* ''[[J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|site/views/helloworld/tmpl/index.html]]''
* ''[[J3.2:Developing_a_MVC_Component/Adding_a_menu_type_to_the_site_part#site/views/helloworld/tmpl/default.xml|site/views/helloworld/tmpl/default.xml]]''
* ''[[J3.2:Developing_a_MVC_Component/Adding_a_view_to_the_site_part#site/views/helloworld/tmpl/default.php|site/views/helloworld/tmpl/default.php]]''
* ''[[J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|site/models/index.html]]''
* ''[[#site/models/helloworld.php|site/models/helloworld.php]]''
* ''[[J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|admin/index.html]]''
* ''[[J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#admin/helloworld.php|admin/helloworld.php]]''
* ''[[J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|admin/sql/index.html]]''
* ''[[J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|admin/sql/updates/index.html]]''
* ''[[J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|admin/sql/updates/mysql/index.html]]''
* ''[[J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#admin/sql/updates/mysql/0.0.1.sql|admin/sql/updates/mysql/0.0.1.sql]]''
Create a compressed file of this directory or directly download the [https://github.com/joomla/Joomla-3.2-Hello-World-Component/archive/step-4-adding-a-site-model.zip archive] and install it using the extension manager of Joomla. You can add a menu item of this component using the menu manager in the backend.

{{notice|Please create a pull request or issue at https://github.com/joomla/Joomla-3.2-Hello-World-Component for any code descprepancies or if editing any of the source code on this page.}}

{{:J3.2:Developing a MVC Component/Navigate
|prev=Adding a menu type to the site part 
|next=Adding a variable request in the menu type }}

== Contributors ==
*[[User:cdemko|Christophe Demko]]
*[[User:oaksu|Ozgur Aksu]]
*[[User:Jossnaz|Lukas Meier]]
*[[User:betweenbrain|Matt Thomas]]

[[Category:Joomla! 3.0]]
[[Category:Joomla! 3.1]]
[[Category:Joomla! 3.2]]
[[Category:Beginner Development]]
[[Category:Component Development]]

J3.x:Developing an MVC Component/Adding a menu type to the site part

2014-05-18T00:57:26Z

Garkell: Added "/" at the end of <schemapath> text

{{:J3.1:Developing a MVC Component}}

== Introduction ==
This tutorial is part of the [[J3.2:Developing a MVC Component|Developing a MVC Component for Joomla!3.2]] tutorial. You are encouraged to read the previous parts of the tutorial before reading this.

== Abstract ==

Generally speaking, this article describes how to get a link on your joomla page to open a specific page of your component. This gets simply done by adding an xml file to your specific page into your view folder.

E.g.

''site/views/helloworld/tmpl/''

Contains your view page ''default.php'' that we want to open.

A file ''default.xml'' is placed next to this file with some xml. This makes joomla able to recognize the view file ''default.php'' as a menu item.

== Adding a menu item type ==
In the Joomla framework, components are executed using menu items. If you go in the menu manager of your Joomla installation a ''HelloWorld'' menu item type does not yet exist. Adding this functionality is easy in Joomla. Simply put a ''site/views/helloworld/tmpl/default.xml'' file containing:

<span id="site/views/helloworld/tmpl/default.xml">
''site/views/helloworld/tmpl/default.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<metadata>
<layout title="COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_TITLE">
<message>
<![CDATA[COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_DESC]]>
</message>
</layout>
</metadata>
</source>
</span>
For the moment the strings won't be translated in the administrator interface. We will see in a later article how translation is performed.

Also modify your ''helloworld.xml'' file to indicate a new version:

<span id="helloworld.xml">
''helloworld.xml''
<source lang="xml">
<extension type="component" version="3.2.0" method="upgrade">

<name>Hello World!</name>

<creationDate>January 2014</creationDate>
<author>John Doe</author>
<authorEmail>john.doe@example.org</authorEmail>
<authorUrl>http://www.example.org</authorUrl>
<copyright>Copyright Info</copyright>
<license>License Info</license>

<version>0.0.3</version>

<description>Description of the Hello World component ...</description>

<update> 
<schemas>
<schemapath type="mysql">sql/updates/mysql/</schemapath>
</schemas>
</update>



<files folder="site">
<filename>index.html</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>
<folder>views</folder>
</files>

<administration>

<menu>Hello World!</menu>


<files folder="admin">

<filename>index.html</filename>
<filename>helloworld.php</filename>

<folder>sql</folder>
</files>
</administration>

</extension>
</source>
</span>

== Packaging the component ==

Content of your code directory
* ''[[#helloworld.xml|helloworld.xml]]''
* ''[[#site/helloworld.php|site/helloworld.php]]''
* ''[[J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|site/index.html]]''
* ''[[#site/controller.php|site/controller.php]]''
* ''[[J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|site/views/index.html]]''
* ''[[J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|site/views/helloworld/index.html]]''
* ''[[#site/views/helloworld/view.html.php|site/views/helloworld/view.html.php]]''
* ''[[J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|site/views/helloworld/tmpl/index.html]]''
* ''[[#site/views/helloworld/tmpl/default.xml|site/views/helloworld/tmpl/default.xml]]''
* ''[[#site/views/helloworld/tmpl/default.php|site/views/helloworld/tmpl/default.php]]''
* ''[[J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|admin/index.html]]''
* ''[[J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#admin/helloworld.php|admin/helloworld.php]]''
* ''[[J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|admin/sql/index.html]]''
* ''[[J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|admin/sql/updates/index.html]]''
* ''[[J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|admin/sql/updates/mysql/index.html]]''
* ''[[J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#admin/sql/updates/mysql/0.0.1.sql|admin/sql/updates/mysql/0.0.1.sql]]''
[[File:Com_helloworld_v3-0.0.3.png|thumb|right|400px|Selecting the Menu Item Type]] Create a compressed file of this directory or directly download the [https://github.com/joomla/Joomla-3.2-Hello-World-Component/archive/step-3-adding-a-site-menu.zip archive] and install it using the extension manager of Joomla. You can add a menu item of this component using the menu manager in the backend. To do so select "Add New Menu Item" from the one of the menus in the "Menus" menu; then you can select COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_TITLE for Menu Item Type. Once selected you can see the Link information is populated with the URL for the view.
<br style="clear: both" />

{{notice|Please create a pull request or issue at https://github.com/joomla/Joomla-3.2-Hello-World-Component for any code descprepancies or if editing any of the source code on this page.}}

{{:J3.2:Developing a MVC Component/Navigate
|prev=Adding a view to the site part 
|next=Adding a model to the site part }}

== Contributors ==
*[[User:cdemko|Christophe Demko]]
*[[User:oaksu|Ozgur Aksu]]
*[[User:Jossnaz|Lukas Meier]]
*[[User:betweenbrain|Matt Thomas]]

[[Category:Joomla! 3.0]]
[[Category:Joomla! 3.1]]
[[Category:Joomla! 3.2]]
[[Category:Beginner Development]]
[[Category:Component Development]]

J3.x:Developing an MVC Component/Adding a view to the site part

2014-05-18T00:56:41Z

Garkell: Added "/" at the end of <schemapath> text

{{version/tutor|3.2}}
{{Chunk:Developing a Model-View-Controller (MVC) Component for Joomla!3.1 - Contents}}

== Introduction ==
This tutorial is part of the [[J3.2:Developing_a_MVC_Component|Developing a Model-View-Controller (MVC) Component for Joomla! 3.x]] tutorial. You are encouraged to read the previous parts of the tutorial before reading this.

In the Joomla!3.x framework, third party component authors divide their code into three main parts:
* ''models'' They manage the data
* ''controllers'' They perform tasks, set and get the states of the models and ask the views to display
* ''views'' They display the content according to the type (''error'', ''feed'', ''html'', ''json'', ''raw'', ''xml'') and the layout chosen by the controllers

== Setting the controller ==
In the core code of Joomla, there is a class able to manage controllers: ''[http://api.joomla.org/cms-3/classes/JControllerLegacy.html JControllerLegacy]''. This class has to be extended to be used in our component. In the file ''yoursite/components/com_helloworld/helloworld.php'' (entry point of our ''Hello World'' component), put these lines:

{{vanchor|site/helloworld.php}}
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import joomla controller library
jimport('joomla.application.component.controller');

// Get an instance of the controller prefixed by HelloWorld
$controller = JControllerLegacy::getInstance('HelloWorld');

// Perform the Request task
$input = JFactory::getApplication()->input;
$controller->execute($input->getCmd('task'));

// Redirect if set by the controller
$controller->redirect();
</source>

The ''[http://api.joomla.org/cms-3/classes/JControllerLegacy.html#method_getInstance getInstance]'' static method of the ''JControllerLegacy'' class will create a controller. In the code above, it will instantiate a controller object of a class named ''HelloWorldController''. Joomla will look for the declaration of that class in an aptly named file called ''yoursite/components/com_helloworld/controller.php'' (it's a default behavior).

Now, ''controller.php'' needs to be created and ''HelloWorldController'' needs to be declared and defined. So with your favorite file manager and editor, create a ''yoursite/components/com_helloworld/controller.php'' file containing

{{vanchor|site/controller.php}}
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import Joomla controller library
jimport('joomla.application.component.controller');

/**
* Hello World Component Controller
*/
class HelloWorldController extends JControllerLegacy
{
}
</source>

When no task is given in the request variables, the default task will be executed. It's the ''display'' task by default. The ''JControllerLegacy'' class has such a task. In our example, it will display a view named ''HelloWorld''.

So with ''task'' simply a public function display() of ''JControllerLegacy'' is refered to.

{{tip|Just a side note for completion, you could call another function aside from ''display()'' by using an URL like this one:

<pre>http://localhost/index.php?option=com_helloworld&task=insert</pre>

This would try to call a function ''insert()'' of our controller (which we would actually have to implement in ''HelloWorldController'' ).}}

== Setting the view ==

When JControllerLegacy wants to display a view, it will look for certain files in the ''yoursite/components/com_[component_name]/views/[name of view]/'' folder.

The name of the folder of the default view is the name of the component itself. In our case the path is ''yoursite/components/com_helloworld/views/helloworld/''.

The file that will contain the code of the view is called ''view.[view_mode].php''. The default view mode, and probably the only view a component might need is the ''html'' mode. So this give us our file name which is ''view.html.php''.

With your favorite file manager and editor, create a file ''yoursite/components/com_helloworld/views/helloworld/view.html.php'' able to display the default view and containing:

<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import Joomla view library
jimport('joomla.application.component.view');

/**
* HTML View class for the HelloWorld Component
*/
class HelloWorldViewHelloWorld extends JViewLegacy
{
// Overwriting JView display method
function display($tpl = null)
{
// Assign data to the view
$this->msg = 'Hello World';

// Display the view
parent::display($tpl);
}
}
</source>

The ''display'' method of the ''[http://api.joomla.org/cms-3/classes/JViewLegacy.html JViewLegacy]'' class is called with the ''display'' task of the JControllerLegacy class. In our case, this method will display data using the ''tmpl/default.php'' file. With your favorite file manager and editor, create a file ''yoursite/components/com_helloworld/views/helloworld/tmpl/default.php'' able to display the default view and containing:

<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');
?>
<h1><?php echo $this->msg; ?></h1>
</source>

This template file will be included by the JViewLegacy class. Therefore, here, $this refers to the HelloWorldViewHelloWorld class.

So to give an example, one could call the view inside the ''yoursite/components/com_[component_name]/views/[name of view]/'' folder by calling <code>index.php?option=com_helloworld</code> (this would default to the ''yoursite/components/com_helloworld/views/helloworld/'' folder) or we could explicitly call the folder by calling: <code>index.php?option=com_helloworld&view=helloworld</code>

if we change <code>&view=helloworld</code> to something else, e.g. <code>&view=fluffy</code> we would have to create a folder <code>components/com_helloworld/views/fluffy/</code>.

Copy the contents of <code>views/helloworld</code> to <code>views/fluffy</code>

The classname of the file <code>view.html.php</code> of the fluffy folder would be ''HelloWorldViewFluffy''. Afterwards you can customize the contents of ''default.php'' of the ''fluffy'' subfolder for custom output and see the output by calling <code>index.php?option=com_helloworld&view=fluffy</code>

== Packaging the component ==

Content of your code directory
* ''[[#helloworld.xml|helloworld.xml]]''
* ''[[#site/helloworld.php|site/helloworld.php]]''
* ''[[J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|site/index.html]]''
* ''[[#site/controller.php|site/controller.php]]''
* ''[[J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|site/views/index.html]]''
* ''[[J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|site/views/helloworld/index.html]]''
* ''[[#site/views/helloworld/view.html.php|site/views/helloworld/view.html.php]]''
* ''[[J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|site/views/helloworld/tmpl/index.html]]''
* ''[[#site/views/helloworld/tmpl/default.php|site/views/helloworld/tmpl/default.php]]''
* ''[[J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|admin/index.html]]''
* ''[[J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#admin/helloworld.php|admin/helloworld.php]]''
* ''[[J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|admin/sql/index.html]]''
* ''[[J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|admin/sql/updates/index.html]]''
* ''[[J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#index.html|admin/sql/updates/mysql/index.html]]''
* ''[[J3.2:Developing_a_MVC_Component/Developing_a_Basic_Component#admin/sql/updates/mysql/0.0.1.sql|admin/sql/updates/mysql/0.0.1.sql]]''

Create a compressed file of this directory or directly download the [http://joomlacode.org/gf/download/frsrelease/11394/58226/com_helloworld-1.6-part02.zip archive] and install it using the extension manager of Joomla. You can test this basic component by putting ''index.php?option=com_helloworld'' in your browser address.

<span id="helloworld.xml">
''helloworld.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="2.5.0" method="upgrade">

<name>Hello World!</name>

<creationDate>November 2009</creationDate>
<author>John Doe</author>
<authorEmail>john.doe@example.org</authorEmail>
<authorUrl>http://www.example.org</authorUrl>
<copyright>Copyright Info</copyright>
<license>License Info</license>

<version>0.0.2</version>

<description>Description of the Hello World component ...</description>

<update> 
<schemas>
<schemapath type="mysql">sql/updates/mysql/</schemapath>
</schemas>
</update>



<files folder="site">
<filename>index.html</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>
<folder>views</folder>
</files>

<administration>

<menu>Hello World!</menu>


<files folder="admin">

<filename>index.html</filename>
<filename>helloworld.php</filename>

<folder>sql</folder>
</files>
</administration>

</extension>
</source>
</span>

'''Result:'''
You will see by default the message contained in the variable ''$this->msg'' in the ''view.html.php'' file.

{{notice|Please create a pull request or issue at https://github.com/joomla/Joomla-3.2-Hello-World-Component for any code descprepancies or if editing any of the source code on this page.}}

{{:J3.2:Developing a MVC Component/Navigate|prev=Developing a Basic Component|next=Adding a menu type to the site part}}

<noinclude>[[Category:Component Development]] [[Category:Joomla! 3.0]] [[Category:Joomla! 3.1]][[Category:Joomla! 3.2]]</noinclude>

== Contributors ==
*[[User:cdemko|Christophe Demko]]
*[[User:oaksu|Ozgur Aksu]]

[[Category:Development]]
[[Category:Joomla! 3.0]]
[[Category:Joomla! 3.1]]
[[Category:Joomla! 3.2]]

J3.x:Developing an MVC Component/Developing a Basic Component

2014-05-18T00:53:52Z

Garkell: Added "/" at the end of <schemapath> text

{{:Developing a Model-View-Controller Component/3.0}}

== The first basic component ==
Let's create a ''Hello World!'' component.
=== Public display ===
With your favorite file manager and editor, create a file ''yoursite/components/com_helloworld/helloworld.php'' containing
<source lang="php">
Hello world
</source>

You can test this basic component by putting ''index.php?option=com_helloworld'' in your browser address (don't forget to prefix this address with your Joomla! 3.x installation path) after installing this component.

=== Administrator management ===
With your favorite file manager and editor, create a file ''yoursite/administrator/components/com_helloworld/helloworld.php'' containing
<source lang="php">
Hello world administration
</source>

You can test this basic component by putting ''administrator/index.php?option=com_helloworld'' in your browser address after installing the component.

=== Packaging an installation zip file ===
If you have used Joomla before reading this tutorial, you have noticed that extensions are installed using a compressed file containing all the things which are needed for installing and uninstalling them.

With your favorite file manager, create a directory (outside your Joomla installation directory) containing
* ''[[#helloworld.xml|helloworld.xml]]''
* ''[[#site/helloworld.php|site/helloworld.php]]''
* ''[[#index.html|site/index.html]]''
* ''[[#index.html|admin/index.html]]''
* ''[[#admin/helloworld.php|admin/helloworld.php]]''
* ''[[#index.html|admin/sql/index.html]]''
* ''[[#index.html|admin/sql/updates/index.html]]''
* ''[[#index.html|admin/sql/updates/mysql/index.html]]''
* ''[[#admin/sql/updates/mysql/0.0.1.sql|admin/sql/updates/mysql/0.0.1.sql]]''

Create a compressed file of this directory or directly download the [http://joomlacode.org/gf/download/frsrelease/11394/58225/com_helloworld-1.6-part01.zip archive] and install it using the extension manager of Joomla. You can test this basic component by putting ''index.php?option=com_helloworld'' or ''administrator/index.php?option=com_helloworld'' in your browser address. You can also notice that the ''Hello World!'' component is visible in the administrator site of your Joomla installation under the ''Components'' menu.

==File Details==
{{vanchor|admin/sql/updates/mysql/0.0.1.sql}}
is an empty file allowing to initialise schema version of the com_helloworld component.
<source lang="sql">
</source>

{{vanchor|helloworld.xml}}
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="3.2" method="upgrade">

<name>Hello World!</name>

<creationDate>December 2013</creationDate>
<author>John Doe</author>
<authorEmail>john.doe@example.org</authorEmail>
<authorUrl>http://www.example.org</authorUrl>
<copyright>Copyright Info</copyright>
<license>License Info</license>

<version>0.0.1</version>

<description>Description of the Hello World component ...</description>

<update> 
<schemas>
<schemapath type="mysql">sql/updates/mysql/</schemapath>
</schemas>
</update>



<files folder="site">
<filename>index.html</filename>
<filename>helloworld.php</filename>
</files>

<administration>

<menu>Hello World!</menu>


<files folder="admin">

<filename>index.html</filename>
<filename>helloworld.php</filename>

<folder>sql</folder>
</files>
</administration>

</extension>
</source>

{{vanchor|site/helloworld.php}}
<source lang="php">
Hello World
</source>

{{vanchor|admin/helloworld.php}}
<source lang="php">
Hello World administration
</source>

{{vanchor|index.html}}
common to all folders
<source lang="html4strict">
<html><body bgcolor="#FFFFFF"></body></html>
</source>

{{notice|Please create a pull request or issue at https://github.com/joomla/Joomla-3.2-Hello-World-Component for any code descprepancies or if editing any of the source code on this page.}}

{{:J3.2:Developing a MVC Component/Navigate
|prev=Introduction
|next=Adding a view to the site part}}

<noinclude>[[Category:Component Development]] [[Category:Joomla! 3.0]] [[Category:Joomla! 3.1]][[Category:Joomla! 3.2]]</noinclude>

Git for Coders

2013-03-17T08:01:21Z

Garkell: /* Overview */

=Overview=
This article shows you how to use Git and Github to code and submit changes to the Joomla CMS. If you are not familiar with Git, you may wish to read the tutorial [[Git_for_Testers_and_Trackers | Git for Testers and Trackers]] first.

''IMPORTANT NOTE: Git is a very powerful system and there is usually more than one way to accomplish the same thing in Git. This tutorial does not try to cover all of the different ways you could do these tasks. Instead, it covers one (hopefully simple) way to do it. As you become more familiar with Git, you may find other ways that work better for you.''

The first step is to set up the remote and local Git repositories. You do this once. Once it is set up, the normal workflow is:
# Update your local and remote repositories with changes others have committed to the main Joomla CMS repository.
# Create a branch for each issue or feature you are working on and commit your changes to the branch in your local repository.
# Update your remote repository on Github with your branches.
# Create a pull request from your Github branch. Alternatively, you can create a patch or diff file from your local branch and post that to the tracker.
# Update the Joomla Issue tracker or Joomla Feature tracker so that others can test your code.

Each of these steps is explained below. Note that you can use Git from the command line, from an IDE such as Eclipse (with the eGit plugin), or from a stand-alone tool, such as TortoiseGit. Here we will use the command line and, where applicable, show the equivalent command in Eclipse eGit.

NOTE: If you want to propose a simple code change, you can do it directly from Github.com, without setting up anything on your local PC. See [[Using_the_Github_UI_to_Make_Pull_Requests|Using the Github UI to Make Pull Requests]].

=Setup=
== Create Your Forked Repository on Github==
Github allows you to create your own copy of any public repository, including the Joomla CMS. This is your personal copy of the repository and is called a "fork". To create a fork of the Joomla CMS:
# If you haven't already, register on Github.com and log in.
# Navigate to [https://github.com/joomla/joomla-cms https://github.com/joomla/joomla-cms]
# Click on the Fork button in the upper right part of the screen.

Note that you can only create one fork of any given repository. However, as we will see, you can create as many branches (versions) of your repository as you like.

== Clone Your Github Repository To Your PC ==
At this point, you have your own repository on Github.com. Now you need to create a local repository that is a copy (called a "clone") of the Github repository. To do this:
===CLI (command line) Commands===
# Change directory to the directory where you want the Joomla files to be stored (for example, <code>C:\xampp\htdocs\joomla\my-project</code> or <code>/opt/lampp/htdocs/joomla/my-project</code>).
# Enter the command: <code>git clone <nowiki>https://github.com/<your Github user name>/joomla-cms.git</nowiki> .</code> For example, if your Github user name is "joomla-coder", the command would be: <code>git clone <nowiki>https://github.com/joomla-coder/joomla-cms.git</nowiki> .</code>

You can get the URL for the command above from your repository at Github.com as shown below. [[File:git-coders-tutorial-20121009-03.png|frame|none]]

Note that the "." dot just tells Git to put the new repository in the current directory. The system will work for a few minutes while it downloads all of the files. When it is finished, you will have a complete set of Joomla files under version control in the current directory.

=== Eclipse Commands ===
# If you like, you can get the URL from Github as shown below. [[File:git-coders-tutorial-20121009-03.png|frame|none]] You will use this later on.
# In Eclipse, open the Git Repositories view and click the button called "Clone a Git Repository and add the clone to this view" as shown below. [[File:git-coders-tutorial-20121009-01.png|frame|none]].
# The window below will show. [[File:git-coders-tutorial-20121009-02.png|frame|none]] Select URI and click Next.
# The window below will show. [[File:git-coders-tutorial-20121009-04.png|frame|none]] Enter the Github URL for your repository (from step (1) above). Enter your Github user name and password and check the box called "Store in Secure Store".
# Click Next and the window below will show. [[File:git-coders-tutorial-20121009-05.png|frame|none]]
# Click Next to select all branches. The window below will show. [[File:git-coders-tutorial-20121009-06.png|frame|none]]
# In Directory, enter the folder where you want the Joomla files to be copied. Keep the default values for Initial branch ("master") and Remote name ("origin") as shown.
# Click Finish. The system will work for a few minutes. When it finishes you will have a clone of the remote repository.

== Create an Upstream Remote==
Now we have our local repository. This has a remote called "origin" that points to our personal fork of Joomla on Github.

In a project like Joomla, many users are submitting bug fixes and features. These changes are committed to the main Joomla CMS repository frequently. It is up to each coder to keep their personal repositories up to date with these changes. Fortunately, as we will see, this is easy to do.

The last step in the setup is to create a second remote called "upstream" that points to the main Joomla CMS repository. We will use this remote to pull changes that others make to the main Joomla repository so we can keep our personal repositories up to date.

===CLI Command ===
To create a remote called "upstream" that points to the main CMS repository, enter this command:

<code>git remote add upstream <nowiki>https://github.com/joomla/joomla-cms.git</nowiki></code>

===Eclipse Command===
''Unknown at this time.''

At this point, you have your personal remote repository (created by "forking" the Joomla CMS project) and your personal local repository (created with CLI or Eclipse). Now you are ready to code patches and features.

=Normal Workflow=
Now that we have done our one-time setup, we are ready to start our normal workflow. This is outlined below.

== Create a New Feature or Bug Fix Change==
Let's say you are ready to start working on a new bug fix or a new feature. Here are the steps you would normally follow.
# Update your master branches. Update the master branch of your local and Github repositories with the latest CMS changes.
# Create a branch for writing the new code
# In the new branch, code the changes and commit them. Depending on the length of time, you can make multiple commits to the branch.
# When you are ready to propose your code for testing (or when you want others to be able to see it), push the branch to your Github repository.
# When you are ready to submit the code, either:
## Create a pull request on Github, or
## Create a patch or diff file and post to the Joomlacode tracker.

Each of these steps is explained in more detail below.

=== Update Your Master Branches ===
You need to keep your repositories up to date with changes made by others in the main CMS repository. It's easy to do, and here are the steps. These are done more easily with the CLI than with Eclipse.

IMPORTANT NOTE: Make sure you never commit your own code changes to the master branch. If you do, you won't be able to keep it synchronized with the master branch on the main CMS repository.

====CLI Commands====
* Make sure you are in your master branch of your local repository (<code>git checkout master</code>). If you aren't sure, you can use the command <code>git status</code> to see what branch you are on.
* Enter the command: <code>git pull upstream master</code>. You should get a message showing the changes, similar to this:
$ git pull upstream master
From <nowiki>https://github.com/joomla/joomla-cms</nowiki>
* branch master -> FETCH_HEAD
Updating 76feee8..294c62c
Fast-forward
installation/CHANGELOG | 3 +++
installation/language/fr-FR/fr-FR.ini | 2 +-
2 files changed, 4 insertions(+), 1 deletion(-)
Mark@MARK2009 /c/xampp/htdocs/joomla-coder/joomla-cms (master)
:If your local repository was already up to date, you will get a message like this:
$ git pull upstream master
From <nowiki>https://github.com/joomla/joomla-cms</nowiki>
* branch master -> FETCH_HEAD
Already up-to-date.

* At this point, your local master branch is up to date with the main CMS repository. Now you need to update the master branch of your Github repository. Enter the command: <code>git push origin master</code>. You should see a message like this:
$ git push origin master
To <nowiki>https://github.com/joomla-coder/joomla-cms.git</nowiki>
76feee8..294c62c master -> master

NOTE: If you haven't stored your user name and password, you will be prompted for them after you enter the push command. See below for how to store your credentials so you don't have to type them each time.

At this point, your master branches on your local and Github repositories are up to date with the main CMS repository. Now, when you create a new branch, it will start at this point and be based on the latest code.

===Create a Branch for the Code===
In Git, the best practice is to use a branch for each bug fix or feature. (In fact, experienced Git users will often create more than one branch for an individual project, perhaps trying different approaches to the problem.) It is super easy to create, delete, and even combine branches. Use a naming convention that allows you to keep track. For example, you could incorporate the tracker issue number into the branch name (for example, "php-notice-12345").

When you create a new branch, it starts from the branch you are currently on. For this reason, you will normally want to make sure you are in your master branch when creating a new one.

====CLI Commands====
<code>git branch xxx</code> where "xxx" is the new branch name. Note: If you already have a branch you are working on, use the command: <code>git checkout xxx</code>.

====Eclipse Commands====
#Left-click on the PHP project and select Team→Switch To→New Branch as shown below. [[File:Git-coders-tutorial-20121009-07.png|frame|none]]. The screen below will show. [[File:Git-coders-tutorial-20121009-08.png|frame|none]]
#Fill in the name of the new branch and click finish.

===Code and Commit to the Branch===
Finally, we are to the fun part! Here we are actually coding and testing our feature or bug fix. The normal workflow is as follows:
# Do some coding.
# Commit your work to your branch.
# Repeat until you are done.

Here are the commands to commit your work to your branch. Make sure you are in the right branch before committing! (Use <code>git status</code> to check.)

====CLI Commands====
* To commit all of the changes since the last commit: <code>git commit -m "My commit message" -a</code>
* To undo any file changes since the last commit: <code>git reset --hard</code>
* To remove any added files and folder since the last commit: <code>git clean -d -f</code>
* To change the last commit: <code>git commit --amend</code>

====Eclipse Commands====
* To commit all changes, right-click on project, select Team→Commit to show this window. [[File:Git-coders-tutorial-20121009-09.png|frame|none]]
* To undo any file changes since the last commit, select Team→Reset and check the Hard Reset Type as shown below. [[File:Git-coders-tutorial-20121009-10.png|frame|none]]
* To change the last commit, select Team→Commit and check the Amend Previous Commit button (as shown in the Commit Changes screenshot above).

===Push Branch to Github===
In the previous workflow, we created the branch and committed changes to our local repository. If we want others to be able to see the branch or to create a pull request, we need to push the branch to our personal repository on Github.

====CLI Command====
To push a branch to your personal Github repository: <code>git push origin xxx</code> (where "xxx" is the name of your branch).

===Submit Pull Request or Patch File===
There are two ways you can submit a proposed code change to the Joomla CMS project. One is to submit a pull request via Github, the other is to create a patch or diff file. In general, pull requests are preferred for very large changes, whereas both work fine for smaller changes.

====Create a Pull Request====
# Navigate to your personal Github repository.
# Select the branch that has the changes for the pull request as shown below. [[File:Git-coders-tutorial-20121009-11.png|frame|none]]
# Click the Pull Request button on the top of the screen. The screen will show as below. [[File:Git-coders-tutorial-20121009-12.png|frame|none]]
# The left side shows the base repository and base branch. This will normally be the master branch of the "joomla/joomla-cms" repository. The right side shows the head repository and branch. This will normally be your repository and the branch that has the desired code changes. If you like you can change the commit message and enter in a comment describing this pull request.
# You can review the pull request using the tabs across the top. Clicking the Commits tab shows the commit history for the branch, as shown below.[[File:Git-coders-tutorial-20121009-13.png|frame|none]]
# Clicking the Files Changed tab shows all of the changes made in this branch, as shown here. [[File:Git-coders-tutorial-20121009-14.png|frame|none]]
# When you are ready to submit the pull request, click the Send Pull Request button at the bottom right of the screen. Github will process the request and then display it as shown below. [[File:Git-coders-tutorial-20121009-15.png|frame|none]]
# At this point, you should update the Joomlacode tracker. For example, if this code is a fix for a Confirmed issue, you should change the issue status to Pending and add a comment with a link to the pull request (for example, <nowiki>https://github.com/joomla/joomla-cms/pull/494</nowiki>). Also, make sure there are good test instructions so people can test the proposed code.

====Create a Patch File====
It is not necessary to create a pull request to submit code changes to Joomla. Another alternative is to create a patch file. This can be done on your local system from the command line as follows:
# In your local system, change to the desired branch.
# Enter the command: <code>git diff master > my-new-patch.patch</code>
This will create a patch file in that same folder. (Note that you may want to have Git automatically ignore all patch files. See the section called Git Tips below.) Upload that file to the Joomlacode tracker and add a comment and change the issue status as needed.
To include changes to binary files in the diff add the <code>--binary</code> option to the command line as follows:
# Enter the command: <code>git diff --binary master > my-new-patch.patch</code>

Note that this method does not require you to push your local branches to Github.

== Keep Your Repositories Up to Date==
As discussed earlier, the main CMS repository on Github is being changed frequently. It is possible that one or more of these changes could conflict with (or otherwise affect) our work. For this reason, it is very important that we keep our repositories up to date. Otherwise, our patch files and pull requests may not work. As discussed earlier, the way we will do this is by keeping our master branch synchronized with the main CMS repository and then using that to update our working branches.

In this tutorial we are using the git merge command. The merge command merges the changes from a different branch into the current branch. Here we use the merge to merge changes from the master branch into our working branch. For example, say we created a branch (my-branch) on day 1. On day 2, someone does 5 commits to the master branch in the main CMS repository. Now, on day 3 we want to update our branch to be current with these 5 commits. The merge command tries to do this automatically. It looks to see what was changed in the master branch since our last merge and applies those same changes to our current branch ("my-branch"). This will work automatically unless we have made changes that conflict with changes made in the same files in the main repository. In that case, we need to resolve these conflicts before we can finish updating our branch.

To update a working branch with changes to the main CMS repository, follow these steps.
# Update your local master branch.
#* Make sure you are on the master branch in your local repository: <code>git checkout master</code>
#* Pull changes from the main CMS repository: <code>git pull upstream master</code>
#* Push those changes to your Github repository: <code>git push origin master</code>
# Now your local master branch is up to date. Next, change to your working branch: <code>git checkout my-branch</code>
# Make sure your remote repository "my-branch" is up to date with your local repository. Use the command: <code>git push origin my-branch</code>. If the remote repository was already up to date, no harm is done. You will just get a message saying it was already up to date.
# Finally, merge the new changes to the master branch with your working branch. The command is as follows: <code>git merge master</code>
# The system will work for a short time and then indicate whether or not the merge was successful. If you don't have any changes that conflict with changes from the main CMS repository, the merge will be successful. If one or more of your changes conflicts with the changes that were made in the main repository, any affected files will be flagged as being in conflict. See the Fixing Conflicts section below for more information about this.

You can also use Eclipse for the merge by changing to the working branch and selecting Team→Merge→. This will show the following screen. [[File:Git-coders-tutorial-20121027-01.png|frame|none]] Select Local->master as shown above and click Merge.

== Fixing Conflicts ==
A conflict occurs during a merge (or rebase) if the same file has been changed in the local branch and in the master branch in a way that conflicts. If this happens, the file is flagged as being in conflict and the merge process is suspended. To complete the process, you need to:
# Manually edit each of the flagged. You will see the changes from your branch and the changes from the main repository highlighted in the file. You need to figure out what should be in the file.
# Once you have edited each flagged file, enter the command <code>git add xxx</code> where "xxx" is the name of the flagged file.

Let's look at a simple example. Here we have added a line of code to a file in our branch and someone has added a different line to the same file in the master branch. When we do the merge command, we get the following message.

$ git merge master
Removing administrator/templates/hathor/html/mod_submenu/default.php
Auto-merging administrator/components/com_admin/script.php
CONFLICT (content): Merge conflict in administrator/components/com_admin/script
php
Automatic merge failed; fix conflicts and then commit the result.

So this tells us we have a conflict in the file <code>administrator/components/com_admin/script.php</code>. If we look at this file in our text editor, we see the following: [[File:Git-coders-tutorial-20121009-17.png|frame|none]] The line under "<<<<<<< HEAD" is from the master branch of the main repository. The line after the "=======" is from our working branch.

At this point, we need to correct the file and remove the "marker" lines. Then we do the command <code>git add administrator/components/com_admin/script.php</code> to tell Git that the conflict is resolved.

Finally, we do the command

<code>git commit -a</code>

to finish the merge. This commits all of the changes that were applied automatically by the merge as well as the changes we have done manually in fixing the conflicts.

If we want to abandon the merge instead of fixing the conflicts, we can use the following commands to reset our branch back to its state before the merge:

<code>git reset --hard</code>

<code>git clean -f -d</code>

===Using Eclipse For Conflicts===
Eclipse is very handy for resolving commits. When you do the command Team→Merge and there is a conflict, you get the following window. [[File:Git-coders-tutorial-20121027-02.png|frame|none]] You will also see a red square annotation in the PHP Explorer window next to each file with a conflict.

To see all of the files in conflict you can use the Merge Tool. Right click on the PHP project and select Team→Merge Tool. You will see the following option. [[File:Git-coders-tutorial-20121009-20.png|frame|none]]

This gives you the option of having Git put in the changes from both sources in the file or letting you compare the changes side by side. If you select Use HEAD version you get a file compare similar to the following. [[File:Git-coders-tutorial-20121009-21.png|frame|none]]

The left shows the change from the master branch, and the right shows the change from your working branch. At this point, you can either edit the file in the left side (for example, by pulling in the change from the right side) or you can just manually edit the file in conflict.

Once the file has been fixed, select the file (either by right-clicking in the PHP Explorer view or in the editor) and select Team→Add to Index as shown below. [[File:Git-coders-tutorial-20121009-22.png|frame|none]]When you do this, the red square annotation will disappear.

Once all the conflicts are resolved, you can finish the merge by right-clicking on the project and selecting Team→Commit. The normal commit screen will show as follows. [[File:Git-coders-tutorial-20121027-03.png|frame|none]] Notice that the files that were in conflict are automatically added to the commit message. Edit the commit message as desired and click the Commit button. At this point, the merge is complete.

== Saving Your User Name and Password ==
When you push changes to Github, it must authenticate you based on your Github user name and password. Normally, the system will simply prompt you for your user name and password each time you do a push.

There are a number of ways you can save your credentials so you don't have to enter them each time. One very simple method is to use the git "store" feature.

''IMPORTANT NOTE: This feature stores your password in plain text on your local computer. If this is not acceptable, do not use this method.''

If it is OK to store your credentials on your PC, at the command line enter the command: <code>git config --global credential.helper store</code> This tells Git to store your credentials in a file called .git-credentials in your home folder ("for example, C:\users\user-name").

The next time you do a push and enter your credentials, they will be stored in that file. After that, you will not need to enter them. Git will use them automatically.

If you want to change your password, simple delete the file and then change your password on Github. The next time you enter your credentials, the new password will be saved.

== Git Tips ==

=== Ignoring Files ===
Some files we don't want Git to track. One way to have Git ignore files is to use the "exclude" file. An advantage of this approach is that this file sits outside of your Git project and doesn't get committed to the repository. This is handy when you want your master branch to be identical to the CMS master branch, even if you want to add some file types to ignore.

To use this feature, follow these steps:
# Create a folder called <code>info</code> under your <code>.git</code> folder. (The .git folder will be at the root of your Joomla project.)
# Create a text file in this folder called <code>exclude</code> and enter in the desired file types to exclude.

Here is an example of a file.
*~
.buildpath
.project
.settings/
tests/system/servers/configdef.php
tests/system/screenshots
configuration.php
logs/error.php
cache/*
administrator/cache/*
*.patch
*.diff
As you can see from the example, we can exclude specific file names or use wild cards.

Once you have this file created, Git will ignore any of these files.
[[Category:Bug Squad]]
[[Category:Development]]

Creating a toolbar for your component

2012-12-18T21:15:25Z

Garkell:

Note: This applies when using the MVC structure.

By default the Joomla Toolbar uses a Delete, Edit, New, Publish, Unpublish and Parameters buttons. To use them in your component you must write the following code in the view.html.php of your view file (below your display function).
<source lang="php">
JToolBarHelper::title( 'your_component_view_page_title', 'generic.png' );
JToolBarHelper::deleteList(); // Will call the task/function "remove" in your controller
JToolBarHelper::editListX(); // Will call the task/function "edit" in your controller
JToolBarHelper::addNewX(); // Will call the task/function "add" in your controller
JToolBarHelper::publishList(); // Will call the task/function "publish" in your controller
JToolBarHelper::unpublishList(); // Will call the task/function "unpublish" in your controller
JToolBarHelper::preferences('your_component_xml_file', 'height');
</source>
So (i.e.) your code would look like this:
<source lang="php">
class HelloViewHellos extends JView
{
function display($tpl = null) {
global $mainframe, $option;
JToolBarHelper::title( 'Hello Component', 'generic.png' );
JToolBarHelper::deleteList();
JToolBarHelper::editListX();
JToolBarHelper::addNewX();
JToolBarHelper::publishList();
JToolBarHelper::unpublishList();
JToolBarHelper::preferences('com_hello', '500');
</source>
An example of creating a custom button in the admin list of records of your component {{JVer|3.0}} could be:

administrator/views/hellos/view.html.php
<source lang="php">
public function display($tpl = null)
{

$this->state = $this->get('State');
$this->items = $this->get('Items');
$this->pagination = $this->get('Pagination');

// Check for errors.
if (count($errors = $this->get('Errors'))) {
JError::raiseError(500, implode("\n", $errors));
return false;
}

$this->addToolbar();

$this->sidebar = JHtmlSidebar::render();
parent::display($tpl);

}

protected function addToolbar()
{
// assuming you have other toolbar buttons ...

JToolBarHelper::custom('hellos.extrahello', 'extrahello.png', 'extrahello_f2.png', 'Extra Hello', true);

}

</source>

administrator/controllers/hellos.php
<source lang="php">
public function extrahello()
{

// Get the input
$input = JFactory::getApplication()->input;
$pks = $input->post->get('cid', array(), 'array');

// Sanitize the input
JArrayHelper::toInteger($pks);

// Get the model
$model = $this->getModel();

$return = $model->extrahello($pks);

// Redirect to the list screen.
$this->setRedirect(JRoute::_('index.php?option=com_hello&view=hellos', false));

}

</source>

administrator/models/hello.php (note: the singular model)
<source lang="php">
public function extrahello($pks)
{

// perform whatever you want on each item checked in the list

return true;

}

</source>

Helpful explanation of JToolBarHelper/custom here - http://docs.joomla.org/JToolBarHelper/custom

[[Category:Component Development]]
[[Category:Tutorials]]

Creating a toolbar for your component

2012-12-18T21:13:34Z

Garkell: Added extra example

Note: This applies when using the MVC structure.

By default the Joomla Toolbar uses a Delete, Edit, New, Publish, Unpublish and Parameters buttons. To use them in your component you must write the following code in the view.html.php of your view file (below your display function).
<source lang="php">
JToolBarHelper::title( 'your_component_view_page_title', 'generic.png' );
JToolBarHelper::deleteList(); // Will call the task/function "remove" in your controller
JToolBarHelper::editListX(); // Will call the task/function "edit" in your controller
JToolBarHelper::addNewX(); // Will call the task/function "add" in your controller
JToolBarHelper::publishList(); // Will call the task/function "publish" in your controller
JToolBarHelper::unpublishList(); // Will call the task/function "unpublish" in your controller
JToolBarHelper::preferences('your_component_xml_file', 'height');
</source>
So (i.e.) your code would look like this:
<source lang="php">
class HelloViewHellos extends JView
{
function display($tpl = null) {
global $mainframe, $option;
JToolBarHelper::title( 'Hello Component', 'generic.png' );
JToolBarHelper::deleteList();
JToolBarHelper::editListX();
JToolBarHelper::addNewX();
JToolBarHelper::publishList();
JToolBarHelper::unpublishList();
JToolBarHelper::preferences('com_hello', '500');
</source>
An example of creating a custom button in the admin list of records of your component {{JVer|3.0}} could be:
WIP

administrator/views/hellos/view.html.php
<source lang="php">
public function display($tpl = null)
{

$this->state = $this->get('State');
$this->items = $this->get('Items');
$this->pagination = $this->get('Pagination');

// Check for errors.
if (count($errors = $this->get('Errors'))) {
JError::raiseError(500, implode("\n", $errors));
return false;
}

$this->addToolbar();

$this->sidebar = JHtmlSidebar::render();
parent::display($tpl);

}

protected function addToolbar()
{
// assuming you have other toolbar buttons ...

JToolBarHelper::custom('hellos.extrahello', 'extrahello.png', 'extrahello_f2.png', 'Extra Hello', true);

}

</source>

administrator/controllers/hellos.php
<source lang="php">
public function extrahello()
{

// Get the input
$input = JFactory::getApplication()->input;
$pks = $input->post->get('cid', array(), 'array');

// Sanitize the input
JArrayHelper::toInteger($pks);

// Get the model
$model = $this->getModel();

$return = $model->extrahello($pks);

// Redirect to the list screen.
$this->setRedirect(JRoute::_('index.php?option=com_hello&view=hellos', false));

}

</source>

administrator/models/hello.php (note: the singular model)
<source lang="php">
public function extrahello($pks)
{

// perform whatever you want on each item checked in the list

return true;

}

</source>

Helpful explanation of JToolBarHelper/custom here - http://docs.joomla.org/JToolBarHelper/custom

[[Category:Component Development]]
[[Category:Tutorials]]

Archived:Developing a MVC Component/Example of menu parameters and stylesheets

2012-05-12T23:10:26Z

Garkell:

This tutorial is for {{JVer|1.6}} {{JVer|1.7}} {{JVer|2.5}}
== Warning - this article needs to be reviewed by someone who knows what they're doing ==

== Articles in this series ==
{{Chunk:Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Contents}}

== Introduction ==
This tutorial is part of the [[Developing a Model-View-Controller (MVC) Component for Joomla!2.5]] tutorial. You are encouraged to read the previous parts of the tutorial before reading this.

== Update the view ==

With your favorite file manager and editor, update the file ''site/views/updhelloworld/view.html.php'' to include setting the state. For the stylesheet, include the import of the html class, and add a new function for including the stylesheet file.

<span id="site/views/updhelloworld/view.html.php">
''site/views/updhelloworld/view.html.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import Joomla view library
jimport('joomla.application.component.view');
// import Joomla html for use with stylesheets
jimport('joomla.html.html');

/**
* HTML View class for the UpdHelloWorld Component
*/
class HelloWorldViewUpdHelloWorld extends JView
{
// Overwriting JView display method
function display($tpl = null)
{
$app = JFactory::getApplication();
$params = $app->getParams();
$dispatcher = JDispatcher::getInstance();

// Get some data from the models
$state = $this->get('State');
$item = $this->get('Item');
$this->form = $this->get('Form');
$this->state = $this->get('State');

// Check for errors.
if (count($errors = $this->get('Errors')))
{
JError::raiseError(500, implode('<br />', $errors));
return false;
}

// get the stylesheet and/or other document values such as title
$this->addDocStyle();

// Display the view
parent::display($tpl);
}

/**
* Add the stylesheet to the document.
*/
protected function addDocStyle()
{
$doc = JFactory::getDocument();
$doc->addStyleSheet('media/com_helloworld/css/site.stylesheet.css');
}

}
</source>
</span>

== Update the layout ==

In Joomla, views display data using a layout. With your favorite file manager and editor, edit your file ''site/views/updhelloworld/tmpl/default.php'' to get the parameter values

<span id="site/views/updhelloworld/tmpl/default.php">
''site/views/updhelloworld/tmpl/default.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

JHtml::_('behavior.keepalive');
JHtml::_('behavior.formvalidation');
JHtml::_('behavior.tooltip');

// get the menu parameters for use
$menuparams = $this->state->get("menuparams");
$headingtxtcolor = $menuparams->get("headingtxtcolor");
$headingbgcolor = $menuparams->get("headingbgcolor");

?>
<h2 style="color:<?php echo $headingtxtcolor; ?>; background-color:<?php echo $headingbgcolor; ?>;">Update the Hello World greeting</h2>

<form class="form-validate" action="<?php echo JRoute::_('index.php'); ?>" method="post" id="updhelloworld" name="updhelloworld">
<fieldset>
<dl>
<dt><?php echo $this->form->getLabel('id'); ?></dt>
<dd><?php echo $this->form->getInput('id'); ?></dd>
<dt></dt><dd></dd>
<dt><?php echo $this->form->getLabel('greeting'); ?></dt>
<dd><?php echo $this->form->getInput('greeting'); ?></dd>
<dt></dt><dd></dd>
<dt></dt>
<dd><input type="hidden" name="option" value="com_helloworld" />
<input type="hidden" name="task" value="updhelloworld.submit" />
</dd>
<dt></dt>
<dd><button type="submit" class="button"><?php echo JText::_('Submit'); ?></button>
<?php echo JHtml::_('form.token'); ?>
</dd>
</dl>
<fieldset>
</form>
<div class="clr"></div>

</source>
</span>

This layout utilises the forms design which resides with the related model. The getLabel and getInput will pickup the xml fields defined and display appropriately. More on the xml file within the models section of this tutorial.

Update the file ''site/views/updhelloworld/tmpl/default.xml'' to include the definitions of the parameter fields.

<span id="site/views/updhelloworld/tmpl/default.xml">
''site/views/updhelloworld/tmpl/default.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<metadata>
<layout title="COM_HELLOWORLD_UPDHELLOWORLD_VIEW_DEFAULT_TITLE">
<message>COM_HELLOWORLD_UPDHELLOWORLD_VIEW_DEFAULT_DESC</message>
</layout>
<fields name="params">
<fieldset name="request">
<field name="headingtxtcolor" type="text" default="#ff0000" size="40"
label="COM_HELLOWORLD_UPDHELLOWORLD_FIELD_HEADINGTXTCOLOR_LABEL"
description="COM_HELLOWORLD_UPDHELLOWORLD_FIELD_HEADINGTXTCOLOR_DESC" />
<field name="headingbgcolor" type="text" default="#0000ff" size="40"
label="COM_HELLOWORLD_UPDHELLOWORLD_FIELD_HEADINGBGCOLOR_LABEL"
description="COM_HELLOWORLD_UPDHELLOWORLD_FIELD_HEADINGBGCOLOR_DESC" />
</fieldset>
</fields>
</metadata>

</source>
</span>

This defines the parameter fields and allows for default values to be set amongst any other JForms elements.

== Update the model ==

The ''UpdHelloWorld'' model sets up the data sent from the related form and allows for saving the data from the form into the database. In the getItem method we will get the values from the parameters.

<span id="site/models/updhelloworld.php">
''site/models/updhelloworld.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// Include dependancy of the main model form
jimport('joomla.application.component.modelform');
// import Joomla modelitem library
jimport('joomla.application.component.modelitem');
// Include dependancy of the dispatcher
jimport('joomla.event.dispatcher');

/**
* UpdHelloWorld Model
*/
class HelloWorldModelUpdHelloWorld extends JModelForm
{
/**
* @var object item
*/
protected $item;

/**
* Get the data for a new qualification
*/
public function getForm($data = array(), $loadData = true)
{

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

// Get the form.
$form = $this->loadForm('com_helloworld.updhelloworld', 'updhelloworld', array('control' => 'jform', 'load_data' => true));
if (empty($form)) {
return false;
}
return $form;

}

/**
* Get the message
* @return object The message to be displayed to the user
*/
function &getItem()
{

if (!isset($this->_item))
{
$cache = JFactory::getCache('com_helloworld', '');
$id = $this->getState('helloworld.id');
$this->_item = $cache->get($id);
if ($this->_item === false) {

// Menu parameters
$menuitemid = JRequest::getInt( 'Itemid' ); // this returns the menu id number so you can reference parameters
$menu = JSite::getMenu();
if ($menuitemid) {
$menuparams = $menu->getParams( $menuitemid );
$headingtxtcolor = $menuparams->get('headingtxtcolor'); // This shows how to get an individual parameter for use
$headingbgcolor = $menuparams->get('headingbgcolor'); // This shows how to get an individual parameter for use
}
$this->setState('menuparams', $menuparams); // this sets the parameter values to the state for later use

}
}
return $this->_item;

}

public function updItem($data)
{
// set the variables from the passed data
$id = $data['id'];
$greeting = $data['greeting'];

// set the data into a query to update the record
$db = $this->getDbo();
$query = $db->getQuery(true);
$query->clear();
$query->update(' #__helloworld ');
$query->set(' greeting = '.$db->Quote($greeting) );
$query->where(' id = ' . (int) $id );

$db->setQuery((string)$query);

if (!$db->query()) {
JError::raiseError(500, $db->getErrorMsg());
return false;
} else {
return true;
}
}
}

</source>
</span>

== Add a stylesheet file ==

Create a new stylesheet file to contain the css code you want to use on your component.

<span id="media/css/site.stylesheet.css">
''media/css/site.stylesheet.css''
<source lang="css">
p {
color: #000000;
}
</source>
</span>

== Adding some language keys ==

Add the last 4 lines to the ''admin/language/en-GB/en-GB.com_helloworld.sys.ini'' file to provide the text link for the parameter type display. And being for the backend, it resides in the admin language folder.

<span id="admin/language/en-GB/en-GB.com_helloworld.sys.ini">
''admin/language/en-GB/en-GB.com_helloworld.sys.ini''
<source lang="ini">
COM_HELLOWORLD="Hello World!"
COM_HELLOWORLD_DESCRIPTION="This is the Hello World description"
COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_DESC="This view displays a selected message"
COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_TITLE="Hello World"
COM_HELLOWORLD_INSTALL_TEXT="HelloWorld Install script"
COM_HELLOWORLD_MENU="Hello World!"
COM_HELLOWORLD_POSTFLIGHT_DISCOVER_INSTALL_TEXT="HelloWorld postlight discover install script"
COM_HELLOWORLD_POSTFLIGHT_INSTALL_TEXT="HelloWorld postflight install script"
COM_HELLOWORLD_POSTFLIGHT_UNINSTALL_TEXT="HelloWorld postflight uninstall script"
COM_HELLOWORLD_POSTFLIGHT_UPDATE_TEXT="HelloWorld postflight update script"
COM_HELLOWORLD_PREFLIGHT_DISCOVER_INSTALL_TEXT="HelloWorld preflight discover install script"
COM_HELLOWORLD_PREFLIGHT_INSTALL_TEXT="HelloWorld preflight install script"
COM_HELLOWORLD_PREFLIGHT_UNINSTALL_TEXT="HelloWorld preflight uninstall script"
COM_HELLOWORLD_PREFLIGHT_UPDATE_TEXT="HelloWorld preflight update script"
COM_HELLOWORLD_UNINSTALL_TEXT="HelloWorld Uninstall script"
COM_HELLOWORLD_UPDATE_TEXT="HelloWorld Update script"
COM_HELLOWORLD_UPDHELLOWORLD_VIEW_DEFAULT_TITLE="Update the Greeting"
COM_HELLOWORLD_UPDHELLOWORLD_VIEW_DEFAULT_DESC="Update greeting here"
COM_HELLOWORLD_UPDHELLOWORLD_FIELD_HEADINGTXTCOLOR_LABEL="Colour of Text"
COM_HELLOWORLD_UPDHELLOWORLD_FIELD_HEADINGTXTCOLOR_DESC="Set the colour of the text on the heading"
COM_HELLOWORLD_UPDHELLOWORLD_FIELD_HEADINGBGCOLOR_LABEL="Colour of Background"
COM_HELLOWORLD_UPDHELLOWORLD_FIELD_HEADINGBGCOLOR_DESC="Set the colour of the background on the heading"</source>
</span>

The ''_populateState'' method is, by default, automatically called when a state is read by the ''getState'' method.

== Packaging the component ==

Content of your code directory-
* ''[[#helloworld.xml|helloworld.xml]]''
* ''[[#script.php|script.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_02#site/helloworld.php|site/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_02#site/controller.php|site/controller.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/updhelloworld.php|site/updhelloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/controllers/updhelloworld.php|site/controllers/updhelloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/controllers/index.html|site/controllers/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/views/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/views/helloworld/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#site/views/helloworld/view.html.php|site/views/helloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/views/updhelloworld/view.html.php|site/views/updhelloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/views/helloworld/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/views/updhelloworld/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_06#site/views/helloworld/tmpl/default.xml|site/views/helloworld/tmpl/default.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#site/views/helloworld/tmpl/default.php|site/views/helloworld/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/views/updhelloworld/tmpl/default.xml|site/views/updhelloworld/tmpl/default.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/views/updhelloworld/tmpl/default.php|site/views/updhelloworld/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/models/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#site/models/helloworld.php|site/models/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/models/updhelloworld.php|site/models/updhelloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/models/forms/updhelloworld.xml|site/models/forms/updhelloworld.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/models/forms/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/language/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/language/en-GB/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_08#site/language/en-GB/en-GB.com_helloworld.ini|site/language/en-GB/en-GB.com_helloworld.ini]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/access.xml|admin/access.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/config.xml|admin/config.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/helloworld.php|admin/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_12#admin/controller.php|admin/controller.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/sql/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/sql/install.mysql.utf8.sql|admin/sql/install.mysql.utf8.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_06#admin/sql/uninstall.mysql.utf8.sql|admin/sql/uninstall.mysql.utf8.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/sql/updates/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/sql/updates/mysql/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#admin/sql/updates/mysql/0.0.1.sql|admin/sql/updates/mysql/0.0.1.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_06#admin/sql/install.mysql.utf8.sql|admin/sql/updates/mysql/0.0.6.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_12#admin/sql/updates/mysql/0.0.12.sql|admin/sql/updates/mysql/0.0.12.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/sql/updates/mysql/0.0.13.sql|admin/sql/updates/mysql/0.0.13.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/models/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/models/fields/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_12#admin/models/fields/helloworld.php|admin/models/fields/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/models/forms/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/models/forms/helloworld.xml|admin/models/forms/helloworld.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/models/forms/helloworld.js|admin/models/forms/helloworld.js]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/models/rules/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/models/rules/greeting.php|admin/models/rules/greeting.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/models/helloworld.php|admin/models/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_09#admin/models/helloworlds.php|admin/models/helloworlds.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/helloworlds/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/views/helloworlds/view.html.php|admin/views/helloworlds/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/helloworlds/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/views/helloworlds/tmpl/default.php|admin/views/helloworlds/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_07#admin/views/helloworlds/tmpl/default_head.php|admin/views/helloworlds/tmpl/default_head.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_07#admin/views/helloworlds/tmpl/default_body.php|admin/views/helloworlds/tmpl/default_body.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_07#admin/views/helloworlds/tmpl/default_foot.php|admin/views/helloworlds/tmpl/default_foot.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/helloworld/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/views/helloworld/view.html.php|admin/views/helloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/views/helloworld/submitbutton.js|admin/views/helloworld/submitbutton.js]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/helloworld/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/views/helloworld/tmpl/edit.php|admin/views/helloworld/tmpl/edit.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/helpers/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/helpers/helloworld.php|admin/helpers/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/tables/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/tables/helloworld.php|admin/tables/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/language/en-GB/en-GB.com_helloworld.ini|admin/language/en-GB/en-GB.com_helloworld.ini]]''
* ''[[#admin/language/en-GB/en-GB.com_helloworld.sys.ini|admin/language/en-GB/en-GB.com_helloworld.sys.ini]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/controllers/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/controllers/helloworld.php|admin/controllers/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/controllers/helloworlds.php|admin/controllers/helloworlds.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_08#language/en-GB/en-GB.ini|language/en-GB/en-GB.ini]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|media/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|media/images/index.html]]''
* ''media/images/tux-16x16.png''
* ''media/images/tux-48x48.png''

Create a compressed file of this directory or directly download the [http://www.glennarkell.com/joomlaorg/com_helloworld_0.0.19.zip] and install it using the extension manager of Joomla. You can add a menu item of this component using the menu manager in the backend.

Be sure to update your manifest to include the stylesheet folder within the media section.

<span id="helloworld.xml">
''helloworld.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="2.5.0" method="upgrade">

<name>COM_HELLOWORLD</name>

<creationDate>November 2009</creationDate>
<author>John Doe</author>
<authorEmail>john.doe@example.org</authorEmail>
<authorUrl>http://www.example.org</authorUrl>
<copyright>Copyright Info</copyright>
<license>License Info</license>

<version>0.0.19</version>

<description>COM_HELLOWORLD_DESCRIPTION</description>


<scriptfile>script.php</scriptfile>

<install> 
<sql>
<file driver="mysql" charset="utf8">sql/install.mysql.utf8.sql</file>
</sql>
</install>
<uninstall> 
<sql>
<file driver="mysql" charset="utf8">sql/uninstall.mysql.utf8.sql</file>
</sql>
</uninstall>
<update> 
<schemas>
<schemapath type="mysql">sql/updates/mysql</schemapath>
</schemas>
</update>



<files folder="site">
<filename>index.html</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>
<filename>updhelloworld.php</filename>
<folder>views</folder>
<folder>models</folder>
<folder>controllers</folder>
<folder>language</folder>
</files>

<media destination="com_helloworld" folder="media">
<filename>index.html</filename>
<folder>css</folder>
<folder>images</folder>
</media>

<administration>

<menu img="../media/com_helloworld/images/tux-16x16.png">COM_HELLOWORLD_MENU</menu>


<files folder="admin">

<filename>index.html</filename>
<filename>config.xml</filename>
<filename>access.xml</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>

<folder>sql</folder>

<folder>tables</folder>

<folder>models</folder>

<folder>views</folder>

<folder>controllers</folder>

<folder>helpers</folder>
</files>

<languages folder="admin">
<language tag="en-GB">language/en-GB/en-GB.com_helloworld.ini</language>
<language tag="en-GB">language/en-GB/en-GB.com_helloworld.sys.ini</language>
</languages>
</administration>


<updateservers>

<server type="extension" priority="1" name="HelloWorld Update Site">http://yourdomain.com/update/helloworld-update.xml</server>
</updateservers>

</extension>

</source>
</span>

Now when you view your '''hello-world''' update function via the front-end menu option, you will see the colours of the text and background being utilised.

== Zips ==
Download the zip file for this Part:
[http://www.glennarkell.com/joomlaorg/com_helloworld_0.0.19.zip]

== Navigate ==

[[Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Part 18|Prev: Example of a Frontend Update Function]]

== Contributors ==
*[[User:garkell|Glenn Arkell]]

[[Category:Development]]
[[category:Joomla! 1.6]]
[[category:Joomla! 1.7]]
[[category:Joomla! 2.5]]
[[category:Manual]]

Archived:Developing a MVC Component/Example of a frontend update function

2012-05-12T23:04:30Z

Garkell:

This tutorial is for {{JVer|1.6}} {{JVer|1.7}} {{JVer|2.5}}
== Warning - this article needs to be reviewed by someone who knows what they're doing ==

== Articles in this series ==
{{Chunk:Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Contents}}

== Introduction ==
This tutorial is part of the [[Developing a Model-View-Controller (MVC) Component for Joomla!2.5]] tutorial. You are encouraged to read the previous parts of the tutorial before reading this.

== Basic frontend form ==
Designing the frontend interface leads us to create a Model-View-Controller triptych similar to the backend in Part 7.

== Create the specific controller ==
The entry point now gets an instance of an ''UpdHelloWorld'' prefixed controller which extends the function of JControllerForm. Let's create a basic controllerform for the site part:

<span id="site/controllers/updhelloworld.php">
''site/controllers/updhelloworld.php''
<source lang="php">
<?php

// No direct access.
defined('_JEXEC') or die;

// Include dependancy of the main controllerform class
jimport('joomla.application.component.controllerform');

class HelloWorldControllerUpdHelloWorld extends JControllerForm
{

public function getModel($name = '', $prefix = '', $config = array('ignore_request' => true))
{
return parent::getModel($name, $prefix, array('ignore_request' => false));
}

public function submit()
{
// Check for request forgeries.
JRequest::checkToken() or jexit(JText::_('JINVALID_TOKEN'));

// Initialise variables.
$app = JFactory::getApplication();
$model = $this->getModel('updhelloworld');

// Get the data from the form POST
$data = JRequest::getVar('jform', array(), 'post', 'array');

// Now update the loaded data to the database via a function in the model
$upditem = $model->updItem($data);

// check if ok and display appropriate message. This can also have a redirect if desired.
if ($upditem) {
echo "<h2>Updated Greeting has been saved</h2>";
} else {
echo "<h2>Updated Greeting failed to be saved</h2>";
}

return true;
}

}
</source>
</span>

This controller will display the appropriate message after the form is submitted.

== Create the view ==

With your favorite file manager and editor, create a file ''site/views/updhelloworld/view.html.php'' containing:

<span id="site/views/updhelloworld/view.html.php">
''site/views/updhelloworld/view.html.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import Joomla view library
jimport('joomla.application.component.view');

/**
* HTML View class for the UpdHelloWorld Component
*/
class HelloWorldViewUpdHelloWorld extends JView
{
// Overwriting JView display method
function display($tpl = null)
{
$app = JFactory::getApplication();
$params = $app->getParams();
$dispatcher = JDispatcher::getInstance();

// Get some data from the models
$state = $this->get('State');
$item = $this->get('Item');
$this->form = $this->get('Form');

// Check for errors.
if (count($errors = $this->get('Errors')))
{
JError::raiseError(500, implode('<br />', $errors));
return false;
}
// Display the view
parent::display($tpl);
}
}
</source>
</span>

In Joomla, views display data using a layout. With your favorite file manager and editor, put a file ''site/views/updhelloworld/tmpl/default.php'' containing

<span id="site/views/updhelloworld/tmpl/default.php">
''site/views/updhelloworld/tmpl/default.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

JHtml::_('behavior.keepalive');
JHtml::_('behavior.formvalidation');
JHtml::_('behavior.tooltip');

?>
<h2>Update the Hello World greeting</h2>

<form class="form-validate" action="<?php echo JRoute::_('index.php'); ?>" method="post" id="updhelloworld" name="updhelloworld">
<fieldset>
<dl>
<dt><?php echo $this->form->getLabel('id'); ?></dt>
<dd><?php echo $this->form->getInput('id'); ?></dd>
<dt></dt><dd></dd>
<dt><?php echo $this->form->getLabel('greeting'); ?></dt>
<dd><?php echo $this->form->getInput('greeting'); ?></dd>
<dt></dt><dd></dd>
<dt></dt>
<dd><input type="hidden" name="option" value="com_helloworld" />
<input type="hidden" name="task" value="updhelloworld.submit" />
</dd>
<dt></dt>
<dd><button type="submit" class="button"><?php echo JText::_('Submit'); ?></button>
<?php echo JHtml::_('form.token'); ?>
</dd>
</dl>
<fieldset>
</form>
<div class="clr"></div>

</source>
</span>

This layout utilises the forms design which resides with the related model. The getLabel and getInput will pickup the xml fields defined and display appropriately. More on the xml file within the models section of this tutorial.

Create a file ''site/views/updhelloworld/tmpl/default.xml'' containing

<span id="site/views/updhelloworld/tmpl/default.xml">
''site/views/updhelloworld/tmpl/default.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<metadata>
<layout title="COM_HELLOWORLD_UPDHELLOWORLD_VIEW_DEFAULT_TITLE">
<message>COM_HELLOWORLD_UPDHELLOWORLD_VIEW_DEFAULT_DESC</message>
</layout>
</metadata>

</source>
</span>

This enables a menu option to be allocated to the frontend form.

== Create the model ==
The ''UpdHelloWorld'' model sets up the data through from the related form and allows the mechanism to save the subsequent data loaded into the form into the database.

<span id="site/models/updhelloworld.php">
''site/models/updhelloworld.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// Include dependancy of the main model form
jimport('joomla.application.component.modelform');
// import Joomla modelitem library
jimport('joomla.application.component.modelitem');
// Include dependancy of the dispatcher
jimport('joomla.event.dispatcher');

/**
* UpdHelloWorld Model
*/
class HelloWorldModelUpdHelloWorld extends JModelForm
{
/**
* @var object item
*/
protected $item;

/**
* Get the data for a new qualification
*/
public function getForm($data = array(), $loadData = true)
{

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

// Get the form.
$form = $this->loadForm('com_helloworld.updhelloworld', 'updhelloworld', array('control' => 'jform', 'load_data' => true));
if (empty($form)) {
return false;
}
return $form;

}

/**
* Get the message
* @return object The message to be displayed to the user
*/
function &getItem()
{

if (!isset($this->_item))
{
$cache = JFactory::getCache('com_helloworld', '');
$id = $this->getState('helloworld.id');
$this->_item = $cache->get($id);
if ($this->_item === false) {

}
}
return $this->_item;

}

public function updItem($data)
{
// set the variables from the passed data
$id = $data['id'];
$greeting = $data['greeting'];

// set the data into a query to update the record
$db = $this->getDbo();
$query = $db->getQuery(true);
$query->clear();
$query->update(' #__helloworld ');
$query->set(' greeting = '.$db->Quote($greeting) );
$query->where(' id = ' . (int) $id );

$db->setQuery((string)$query);

if (!$db->query()) {
JError::raiseError(500, $db->getErrorMsg());
return false;
} else {
return true;
}
}
}

</source>
</span>

The following file ''updhelloworld.xml'' should be created using your favourite editor and saved in the forms folder under the models directory. The first of the fields being referenced id using the sql type so that I returns the results from the query into a dropdown list form to be selected.
<span id="site/models/forms/updhelloworld.xml">
''site/models/forms/updhelloworld.xml''
<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<form name="updhelloworld">
<fieldset name="updhelloworld">

<field
name="id"
type="sql"
multiple="false"
size="1"
label="COM_HELLOWORLD_FORM_LBL_UPDHELLOWORLD_ID"
description="COM_HELLOWORLD_FORM_DESC_UPDHELLOWORLD_ID"
query="select id, greeting from #__helloworld"
key_field="id"
value_field="greeting"
default="0"
required="true"
>
<option value="">JOPTION_SELECT_ID</option>
</field>

<field
name="greeting"
type="text"
description="COM_HELLOWORLD_FORM_DESC_UPDHELLOWORLD_GREETING"
label="COM_HELLOWORLD_FORM_LBL_UPDHELLOWORLD_GREETING"
required="true"
size="50" />

</fieldset>
</form>

</source>
</span>

== Adding some language keys ==

This file provides the text link between the label in the model form definition to be displayed in the view. And being for the frontend, it resides in the site folder.

<span id="site/language/en-GB/en-GB.com_helloworld.ini">
''site/language/en-GB/en-GB.com_helloworld.ini''
<source lang="ini">
COM_HELLOWORLD_FORM_LBL_UPDHELLOWORLD_ID="Greeting ID"
COM_HELLOWORLD_FORM_DESC_UPDHELLOWORLD_ID="This is the ID of the Greeting record"
COM_HELLOWORLD_FORM_LBL_UPDHELLOWORLD_GREETING="Greeting"
COM_HELLOWORLD_FORM_DESC_UPDHELLOWORLD_GREETING="Greeting description"
JOPTION_SELECT_ID=" -- Select Greeting to Update -- "
</source>
</span>

Add the last 2 lines to the ''admin/language/en-GB/en-GB.com_helloworld.sys.ini'' file to provide the text link for the menu type display. And being for the backend, it resides in the admin language folder.

<span id="admin/language/en-GB/en-GB.com_helloworld.sys.ini">
''admin/language/en-GB/en-GB.com_helloworld.sys.ini''
<source lang="ini">
COM_HELLOWORLD="Hello World!"
COM_HELLOWORLD_DESCRIPTION="This is the Hello World description"
COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_DESC="This view displays a selected message"
COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_TITLE="Hello World"
COM_HELLOWORLD_INSTALL_TEXT="HelloWorld Install script"
COM_HELLOWORLD_MENU="Hello World!"
COM_HELLOWORLD_POSTFLIGHT_DISCOVER_INSTALL_TEXT="HelloWorld postlight discover install script"
COM_HELLOWORLD_POSTFLIGHT_INSTALL_TEXT="HelloWorld postflight install script"
COM_HELLOWORLD_POSTFLIGHT_UNINSTALL_TEXT="HelloWorld postflight uninstall script"
COM_HELLOWORLD_POSTFLIGHT_UPDATE_TEXT="HelloWorld postflight update script"
COM_HELLOWORLD_PREFLIGHT_DISCOVER_INSTALL_TEXT="HelloWorld preflight discover install script"
COM_HELLOWORLD_PREFLIGHT_INSTALL_TEXT="HelloWorld preflight install script"
COM_HELLOWORLD_PREFLIGHT_UNINSTALL_TEXT="HelloWorld preflight uninstall script"
COM_HELLOWORLD_PREFLIGHT_UPDATE_TEXT="HelloWorld preflight update script"
COM_HELLOWORLD_UNINSTALL_TEXT="HelloWorld Uninstall script"
COM_HELLOWORLD_UPDATE_TEXT="HelloWorld Update script"
COM_HELLOWORLD_UPDHELLOWORLD_VIEW_DEFAULT_TITLE="Update the Greeting"
COM_HELLOWORLD_UPDHELLOWORLD_VIEW_DEFAULT_DESC="Update greeting here"
</source>
</span>

The ''_populateState'' method is, by default, automatically called when a state is read by the ''getState'' method.

== Packaging the component ==

Content of your code directory-
* ''[[#helloworld.xml|helloworld.xml]]''
* ''[[#script.php|script.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_02#site/helloworld.php|site/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_02#site/controller.php|site/controller.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/updhelloworld.php|site/updhelloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/controllers/updhelloworld.php|site/controllers/updhelloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/controllers/index.html|site/controllers/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/views/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/views/helloworld/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#site/views/helloworld/view.html.php|site/views/helloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/views/updhelloworld/view.html.php|site/views/updhelloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/views/helloworld/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/views/updhelloworld/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_06#site/views/helloworld/tmpl/default.xml|site/views/helloworld/tmpl/default.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#site/views/helloworld/tmpl/default.php|site/views/helloworld/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/views/updhelloworld/tmpl/default.xml|site/views/updhelloworld/tmpl/default.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/views/updhelloworld/tmpl/default.php|site/views/updhelloworld/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/models/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#site/models/helloworld.php|site/models/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/models/updhelloworld.php|site/models/updhelloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/models/forms/updhelloworld.xml|site/models/forms/updhelloworld.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/models/forms/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/language/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/language/en-GB/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_08#site/language/en-GB/en-GB.com_helloworld.ini|site/language/en-GB/en-GB.com_helloworld.ini]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/access.xml|admin/access.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/config.xml|admin/config.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/helloworld.php|admin/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_12#admin/controller.php|admin/controller.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/sql/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/sql/install.mysql.utf8.sql|admin/sql/install.mysql.utf8.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_06#admin/sql/uninstall.mysql.utf8.sql|admin/sql/uninstall.mysql.utf8.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/sql/updates/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/sql/updates/mysql/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#admin/sql/updates/mysql/0.0.1.sql|admin/sql/updates/mysql/0.0.1.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_06#admin/sql/install.mysql.utf8.sql|admin/sql/updates/mysql/0.0.6.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_12#admin/sql/updates/mysql/0.0.12.sql|admin/sql/updates/mysql/0.0.12.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/sql/updates/mysql/0.0.13.sql|admin/sql/updates/mysql/0.0.13.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/models/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/models/fields/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_12#admin/models/fields/helloworld.php|admin/models/fields/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/models/forms/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/models/forms/helloworld.xml|admin/models/forms/helloworld.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/models/forms/helloworld.js|admin/models/forms/helloworld.js]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/models/rules/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/models/rules/greeting.php|admin/models/rules/greeting.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/models/helloworld.php|admin/models/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_09#admin/models/helloworlds.php|admin/models/helloworlds.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/helloworlds/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/views/helloworlds/view.html.php|admin/views/helloworlds/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/helloworlds/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/views/helloworlds/tmpl/default.php|admin/views/helloworlds/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_07#admin/views/helloworlds/tmpl/default_head.php|admin/views/helloworlds/tmpl/default_head.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_07#admin/views/helloworlds/tmpl/default_body.php|admin/views/helloworlds/tmpl/default_body.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_07#admin/views/helloworlds/tmpl/default_foot.php|admin/views/helloworlds/tmpl/default_foot.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/helloworld/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/views/helloworld/view.html.php|admin/views/helloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/views/helloworld/submitbutton.js|admin/views/helloworld/submitbutton.js]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/helloworld/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/views/helloworld/tmpl/edit.php|admin/views/helloworld/tmpl/edit.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/helpers/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/helpers/helloworld.php|admin/helpers/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/tables/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/tables/helloworld.php|admin/tables/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/language/en-GB/en-GB.com_helloworld.ini|admin/language/en-GB/en-GB.com_helloworld.ini]]''
* ''[[#admin/language/en-GB/en-GB.com_helloworld.sys.ini|admin/language/en-GB/en-GB.com_helloworld.sys.ini]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/controllers/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/controllers/helloworld.php|admin/controllers/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/controllers/helloworlds.php|admin/controllers/helloworlds.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_08#language/en-GB/en-GB.ini|language/en-GB/en-GB.ini]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|media/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|media/images/index.html]]''
* ''media/images/tux-16x16.png''
* ''media/images/tux-48x48.png''

Create a compressed file of this directory or directly download the [http://joomlacode.org/gf/download/frsrelease/11394/58397/com_helloworld-1.6-part07.zip archive] and install it using the extension manager of Joomla. You can add a menu item of this component using the menu manager in the backend.

<span id="helloworld.xml">
''helloworld.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="2.5.0" method="upgrade">

<name>COM_HELLOWORLD</name>

<creationDate>November 2009</creationDate>
<author>John Doe</author>
<authorEmail>john.doe@example.org</authorEmail>
<authorUrl>http://www.example.org</authorUrl>
<copyright>Copyright Info</copyright>
<license>License Info</license>

<version>0.0.18</version>

<description>COM_HELLOWORLD_DESCRIPTION</description>


<scriptfile>script.php</scriptfile>

<install> 
<sql>
<file driver="mysql" charset="utf8">sql/install.mysql.utf8.sql</file>
</sql>
</install>
<uninstall> 
<sql>
<file driver="mysql" charset="utf8">sql/uninstall.mysql.utf8.sql</file>
</sql>
</uninstall>
<update> 
<schemas>
<schemapath type="mysql">sql/updates/mysql</schemapath>
</schemas>
</update>



<files folder="site">
<filename>index.html</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>
<filename>updhelloworld.php</filename>
<folder>views</folder>
<folder>models</folder>
<folder>controllers</folder>
<folder>language</folder>
</files>

<media destination="com_helloworld" folder="media">
<filename>index.html</filename>
<folder>images</folder>
</media>

<administration>

<menu img="../media/com_helloworld/images/tux-16x16.png">COM_HELLOWORLD_MENU</menu>


<files folder="admin">

<filename>index.html</filename>
<filename>config.xml</filename>
<filename>access.xml</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>

<folder>sql</folder>

<folder>tables</folder>

<folder>models</folder>

<folder>views</folder>

<folder>controllers</folder>

<folder>helpers</folder>
</files>

<languages folder="admin">
<language tag="en-GB">language/en-GB/en-GB.com_helloworld.ini</language>
<language tag="en-GB">language/en-GB/en-GB.com_helloworld.sys.ini</language>
</languages>
</administration>


<updateservers>

<server type="extension" priority="1" name="HelloWorld Update Site">http://yourdomain.com/update/helloworld-update.xml</server>
</updateservers>

</extension>

</source>
</span>

Now you can see in your component '''hello-world''' an array with two colums, two rows and checkboxes. You can click the checkboxes in order to select the different options you want.

== Zips ==
Download the zip file for this Part:
[http://www.glennarkell.com/joomlaorg/com_helloworld_0.0.18.zip]

== Navigate ==

[[Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Part 17|Prev: Adding an update server]]
[[Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Part 19|Next: Example of Menu Parameters & Stylesheets]]

== Contributors ==
*[[User:garkell|Glenn Arkell]]

[[Category:Development]]
[[category:Joomla! 1.6]]
[[category:Joomla! 1.7]]
[[category:Joomla! 2.5]]
[[category:Manual]]

Archived:Developing a MVC Component/Example of menu parameters and stylesheets

2012-05-12T23:01:22Z

Garkell:

This tutorial is for {{JVer|1.6}} {{JVer|1.7}} {{JVer|2.5}}
== Warning - this article needs to be reviewed by someone who knows what they're doing ==

== Articles in this series ==
{{Chunk:Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Contents}}

== Introduction ==
This tutorial is part of the [[Developing a Model-View-Controller (MVC) Component for Joomla!2.5]] tutorial. You are encouraged to read the previous parts of the tutorial before reading this.

== Update the view ==

With your favorite file manager and editor, update the file ''site/views/updhelloworld/view.html.php'' to include setting the state. For the stylesheet, include the import of the html class, and add a new function for including the stylesheet file.

<span id="site/views/updhelloworld/view.html.php">
''site/views/updhelloworld/view.html.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import Joomla view library
jimport('joomla.application.component.view');
// import Joomla html for use with stylesheets
jimport('joomla.html.html');

/**
* HTML View class for the UpdHelloWorld Component
*/
class HelloWorldViewUpdHelloWorld extends JView
{
// Overwriting JView display method
function display($tpl = null)
{
$app = JFactory::getApplication();
$params = $app->getParams();
$dispatcher = JDispatcher::getInstance();

// Get some data from the models
$state = $this->get('State');
$item = $this->get('Item');
$this->form = $this->get('Form');
$this->state = $this->get('State');

// Check for errors.
if (count($errors = $this->get('Errors')))
{
JError::raiseError(500, implode('<br />', $errors));
return false;
}

// get the stylesheet and/or other document values such as title
$this->addDocStyle();

// Display the view
parent::display($tpl);
}

/**
* Add the stylesheet to the document.
*/
protected function addDocStyle()
{
$doc = JFactory::getDocument();
$doc->addStyleSheet('media/com_helloworld/css/site.stylesheet.css');
}

}
</source>
</span>

== Update the layout ==

In Joomla, views display data using a layout. With your favorite file manager and editor, edit your file ''site/views/updhelloworld/tmpl/default.php'' to get the parameter values

<span id="site/views/updhelloworld/tmpl/default.php">
''site/views/updhelloworld/tmpl/default.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

JHtml::_('behavior.keepalive');
JHtml::_('behavior.formvalidation');
JHtml::_('behavior.tooltip');

// get the menu parameters for use
$menuparams = $this->state->get("menuparams");
$headingtxtcolor = $menuparams->get("headingtxtcolor");
$headingbgcolor = $menuparams->get("headingbgcolor");

?>
<h2 style="color:<?php echo $headingtxtcolor; ?>; background-color:<?php echo $headingbgcolor; ?>;">Update the Hello World greeting</h2>

<form class="form-validate" action="<?php echo JRoute::_('index.php'); ?>" method="post" id="updhelloworld" name="updhelloworld">
<fieldset>
<dl>
<dt><?php echo $this->form->getLabel('id'); ?></dt>
<dd><?php echo $this->form->getInput('id'); ?></dd>
<dt></dt><dd></dd>
<dt><?php echo $this->form->getLabel('greeting'); ?></dt>
<dd><?php echo $this->form->getInput('greeting'); ?></dd>
<dt></dt><dd></dd>
<dt></dt>
<dd><input type="hidden" name="option" value="com_helloworld" />
<input type="hidden" name="task" value="updhelloworld.submit" />
</dd>
<dt></dt>
<dd><button type="submit" class="button"><?php echo JText::_('Submit'); ?></button>
<?php echo JHtml::_('form.token'); ?>
</dd>
</dl>
<fieldset>
</form>
<div class="clr"></div>

</source>
</span>

This layout utilises the forms design which resides with the related model. The getLabel and getInput will pickup the xml fields defined and display appropriately. More on the xml file within the models section of this tutorial.

Update the file ''site/views/updhelloworld/tmpl/default.xml'' containing

<span id="site/views/updhelloworld/tmpl/default.xml">
''site/views/updhelloworld/tmpl/default.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<metadata>
<layout title="COM_HELLOWORLD_UPDHELLOWORLD_VIEW_DEFAULT_TITLE">
<message>COM_HELLOWORLD_UPDHELLOWORLD_VIEW_DEFAULT_DESC</message>
</layout>
<fields name="params">
<fieldset name="request">
<field name="headingtxtcolor" type="text" default="#ff0000" size="40"
label="COM_HELLOWORLD_UPDHELLOWORLD_FIELD_HEADINGTXTCOLOR_LABEL"
description="COM_HELLOWORLD_UPDHELLOWORLD_FIELD_HEADINGTXTCOLOR_DESC" />
<field name="headingbgcolor" type="text" default="#0000ff" size="40"
label="COM_HELLOWORLD_UPDHELLOWORLD_FIELD_HEADINGBGCOLOR_LABEL"
description="COM_HELLOWORLD_UPDHELLOWORLD_FIELD_HEADINGBGCOLOR_DESC" />
</fieldset>
</fields>
</metadata>

</source>
</span>

This defines the parameter fields and allows for default values to be set.

== Update the model ==

The ''UpdHelloWorld'' model sets up the data sent from the related form and allows for saving the data from the form into the database. In the getItem method we will get the values from the parameters.

<span id="site/models/updhelloworld.php">
''site/models/updhelloworld.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// Include dependancy of the main model form
jimport('joomla.application.component.modelform');
// import Joomla modelitem library
jimport('joomla.application.component.modelitem');
// Include dependancy of the dispatcher
jimport('joomla.event.dispatcher');

/**
* UpdHelloWorld Model
*/
class HelloWorldModelUpdHelloWorld extends JModelForm
{
/**
* @var object item
*/
protected $item;

/**
* Get the data for a new qualification
*/
public function getForm($data = array(), $loadData = true)
{

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

// Get the form.
$form = $this->loadForm('com_helloworld.updhelloworld', 'updhelloworld', array('control' => 'jform', 'load_data' => true));
if (empty($form)) {
return false;
}
return $form;

}

/**
* Get the message
* @return object The message to be displayed to the user
*/
function &getItem()
{

if (!isset($this->_item))
{
$cache = JFactory::getCache('com_helloworld', '');
$id = $this->getState('helloworld.id');
$this->_item = $cache->get($id);
if ($this->_item === false) {

// Menu parameters
$menuitemid = JRequest::getInt( 'Itemid' ); // this returns the menu id number so you can reference parameters
$menu = JSite::getMenu();
if ($menuitemid) {
$menuparams = $menu->getParams( $menuitemid );
$headingtxtcolor = $menuparams->get('headingtxtcolor'); // This shows how to get an individual parameter for use
$headingbgcolor = $menuparams->get('headingbgcolor'); // This shows how to get an individual parameter for use
}
$this->setState('menuparams', $menuparams); // this sets the parameter values to the state for later use

}
}
return $this->_item;

}

public function updItem($data)
{
// set the variables from the passed data
$id = $data['id'];
$greeting = $data['greeting'];

// set the data into a query to update the record
$db = $this->getDbo();
$query = $db->getQuery(true);
$query->clear();
$query->update(' #__helloworld ');
$query->set(' greeting = '.$db->Quote($greeting) );
$query->where(' id = ' . (int) $id );

$db->setQuery((string)$query);

if (!$db->query()) {
JError::raiseError(500, $db->getErrorMsg());
return false;
} else {
return true;
}
}
}

</source>
</span>

== Add a stylesheet file ==

Create a new stylesheet file to contain the css code you want to use on your component.

<span id="media/css/site.stylesheet.css">
''media/css/site.stylesheet.css''
<source lang="css">
p {
color: #000000;
}
</source>
</span>

== Adding some language keys ==

Add the last 4 lines to the ''admin/language/en-GB/en-GB.com_helloworld.sys.ini'' file to provide the text link for the parameter type display. And being for the backend, it resides in the admin language folder.

<span id="admin/language/en-GB/en-GB.com_helloworld.sys.ini">
''admin/language/en-GB/en-GB.com_helloworld.sys.ini''
<source lang="ini">
COM_HELLOWORLD="Hello World!"
COM_HELLOWORLD_DESCRIPTION="This is the Hello World description"
COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_DESC="This view displays a selected message"
COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_TITLE="Hello World"
COM_HELLOWORLD_INSTALL_TEXT="HelloWorld Install script"
COM_HELLOWORLD_MENU="Hello World!"
COM_HELLOWORLD_POSTFLIGHT_DISCOVER_INSTALL_TEXT="HelloWorld postlight discover install script"
COM_HELLOWORLD_POSTFLIGHT_INSTALL_TEXT="HelloWorld postflight install script"
COM_HELLOWORLD_POSTFLIGHT_UNINSTALL_TEXT="HelloWorld postflight uninstall script"
COM_HELLOWORLD_POSTFLIGHT_UPDATE_TEXT="HelloWorld postflight update script"
COM_HELLOWORLD_PREFLIGHT_DISCOVER_INSTALL_TEXT="HelloWorld preflight discover install script"
COM_HELLOWORLD_PREFLIGHT_INSTALL_TEXT="HelloWorld preflight install script"
COM_HELLOWORLD_PREFLIGHT_UNINSTALL_TEXT="HelloWorld preflight uninstall script"
COM_HELLOWORLD_PREFLIGHT_UPDATE_TEXT="HelloWorld preflight update script"
COM_HELLOWORLD_UNINSTALL_TEXT="HelloWorld Uninstall script"
COM_HELLOWORLD_UPDATE_TEXT="HelloWorld Update script"
COM_HELLOWORLD_UPDHELLOWORLD_VIEW_DEFAULT_TITLE="Update the Greeting"
COM_HELLOWORLD_UPDHELLOWORLD_VIEW_DEFAULT_DESC="Update greeting here"
COM_HELLOWORLD_UPDHELLOWORLD_FIELD_HEADINGTXTCOLOR_LABEL="Colour of Text"
COM_HELLOWORLD_UPDHELLOWORLD_FIELD_HEADINGTXTCOLOR_DESC="Set the colour of the text on the heading"
COM_HELLOWORLD_UPDHELLOWORLD_FIELD_HEADINGBGCOLOR_LABEL="Colour of Background"
COM_HELLOWORLD_UPDHELLOWORLD_FIELD_HEADINGBGCOLOR_DESC="Set the colour of the background on the heading"</source>
</span>

The ''_populateState'' method is, by default, automatically called when a state is read by the ''getState'' method.

== Packaging the component ==

Content of your code directory-
* ''[[#helloworld.xml|helloworld.xml]]''
* ''[[#script.php|script.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_02#site/helloworld.php|site/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_02#site/controller.php|site/controller.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/updhelloworld.php|site/updhelloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/controllers/updhelloworld.php|site/controllers/updhelloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/controllers/index.html|site/controllers/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/views/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/views/helloworld/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#site/views/helloworld/view.html.php|site/views/helloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/views/updhelloworld/view.html.php|site/views/updhelloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/views/helloworld/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/views/updhelloworld/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_06#site/views/helloworld/tmpl/default.xml|site/views/helloworld/tmpl/default.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#site/views/helloworld/tmpl/default.php|site/views/helloworld/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/views/updhelloworld/tmpl/default.xml|site/views/updhelloworld/tmpl/default.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/views/updhelloworld/tmpl/default.php|site/views/updhelloworld/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/models/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#site/models/helloworld.php|site/models/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/models/updhelloworld.php|site/models/updhelloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/models/forms/updhelloworld.xml|site/models/forms/updhelloworld.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/models/forms/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/language/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/language/en-GB/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_08#site/language/en-GB/en-GB.com_helloworld.ini|site/language/en-GB/en-GB.com_helloworld.ini]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/access.xml|admin/access.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/config.xml|admin/config.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/helloworld.php|admin/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_12#admin/controller.php|admin/controller.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/sql/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/sql/install.mysql.utf8.sql|admin/sql/install.mysql.utf8.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_06#admin/sql/uninstall.mysql.utf8.sql|admin/sql/uninstall.mysql.utf8.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/sql/updates/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/sql/updates/mysql/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#admin/sql/updates/mysql/0.0.1.sql|admin/sql/updates/mysql/0.0.1.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_06#admin/sql/install.mysql.utf8.sql|admin/sql/updates/mysql/0.0.6.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_12#admin/sql/updates/mysql/0.0.12.sql|admin/sql/updates/mysql/0.0.12.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/sql/updates/mysql/0.0.13.sql|admin/sql/updates/mysql/0.0.13.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/models/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/models/fields/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_12#admin/models/fields/helloworld.php|admin/models/fields/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/models/forms/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/models/forms/helloworld.xml|admin/models/forms/helloworld.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/models/forms/helloworld.js|admin/models/forms/helloworld.js]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/models/rules/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/models/rules/greeting.php|admin/models/rules/greeting.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/models/helloworld.php|admin/models/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_09#admin/models/helloworlds.php|admin/models/helloworlds.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/helloworlds/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/views/helloworlds/view.html.php|admin/views/helloworlds/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/helloworlds/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/views/helloworlds/tmpl/default.php|admin/views/helloworlds/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_07#admin/views/helloworlds/tmpl/default_head.php|admin/views/helloworlds/tmpl/default_head.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_07#admin/views/helloworlds/tmpl/default_body.php|admin/views/helloworlds/tmpl/default_body.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_07#admin/views/helloworlds/tmpl/default_foot.php|admin/views/helloworlds/tmpl/default_foot.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/helloworld/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/views/helloworld/view.html.php|admin/views/helloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/views/helloworld/submitbutton.js|admin/views/helloworld/submitbutton.js]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/helloworld/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/views/helloworld/tmpl/edit.php|admin/views/helloworld/tmpl/edit.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/helpers/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/helpers/helloworld.php|admin/helpers/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/tables/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/tables/helloworld.php|admin/tables/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/language/en-GB/en-GB.com_helloworld.ini|admin/language/en-GB/en-GB.com_helloworld.ini]]''
* ''[[#admin/language/en-GB/en-GB.com_helloworld.sys.ini|admin/language/en-GB/en-GB.com_helloworld.sys.ini]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/controllers/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/controllers/helloworld.php|admin/controllers/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/controllers/helloworlds.php|admin/controllers/helloworlds.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_08#language/en-GB/en-GB.ini|language/en-GB/en-GB.ini]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|media/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|media/images/index.html]]''
* ''media/images/tux-16x16.png''
* ''media/images/tux-48x48.png''

Create a compressed file of this directory or directly download the [http://www.glennarkell.com/joomlaorg/com_helloworld_0.0.19.zip] and install it using the extension manager of Joomla. You can add a menu item of this component using the menu manager in the backend.

Be sure to update your manifest to include the stylesheet folder within the media section.

<span id="helloworld.xml">
''helloworld.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="2.5.0" method="upgrade">

<name>COM_HELLOWORLD</name>

<creationDate>November 2009</creationDate>
<author>John Doe</author>
<authorEmail>john.doe@example.org</authorEmail>
<authorUrl>http://www.example.org</authorUrl>
<copyright>Copyright Info</copyright>
<license>License Info</license>

<version>0.0.19</version>

<description>COM_HELLOWORLD_DESCRIPTION</description>


<scriptfile>script.php</scriptfile>

<install> 
<sql>
<file driver="mysql" charset="utf8">sql/install.mysql.utf8.sql</file>
</sql>
</install>
<uninstall> 
<sql>
<file driver="mysql" charset="utf8">sql/uninstall.mysql.utf8.sql</file>
</sql>
</uninstall>
<update> 
<schemas>
<schemapath type="mysql">sql/updates/mysql</schemapath>
</schemas>
</update>



<files folder="site">
<filename>index.html</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>
<filename>updhelloworld.php</filename>
<folder>views</folder>
<folder>models</folder>
<folder>controllers</folder>
<folder>language</folder>
</files>

<media destination="com_helloworld" folder="media">
<filename>index.html</filename>
<folder>css</folder>
<folder>images</folder>
</media>

<administration>

<menu img="../media/com_helloworld/images/tux-16x16.png">COM_HELLOWORLD_MENU</menu>


<files folder="admin">

<filename>index.html</filename>
<filename>config.xml</filename>
<filename>access.xml</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>

<folder>sql</folder>

<folder>tables</folder>

<folder>models</folder>

<folder>views</folder>

<folder>controllers</folder>

<folder>helpers</folder>
</files>

<languages folder="admin">
<language tag="en-GB">language/en-GB/en-GB.com_helloworld.ini</language>
<language tag="en-GB">language/en-GB/en-GB.com_helloworld.sys.ini</language>
</languages>
</administration>


<updateservers>

<server type="extension" priority="1" name="HelloWorld Update Site">http://yourdomain.com/update/helloworld-update.xml</server>
</updateservers>

</extension>

</source>
</span>

Now when you view your '''hello-world''' update function via the front-end menu option, you will see the colours of the text and background being utilised.

== Zips ==
Download the zip file for this Part:
[http://www.glennarkell.com/joomlaorg/com_helloworld_0.0.19.zip]

== Navigate ==

[[Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Part 18|Prev: Example of a Frontend Update Function]]

== Contributors ==
*[[User:garkell|Glenn Arkell]]

[[Category:Development]]
[[category:Joomla! 1.6]]
[[category:Joomla! 1.7]]
[[category:Joomla! 2.5]]
[[category:Manual]]

Archived:Developing a MVC Component/Example of menu parameters and stylesheets

2012-05-12T22:59:59Z

Garkell: /* Add a stylesheet file */

This tutorial is for {{JVer|1.6}} {{JVer|1.7}} {{JVer|2.5}}
== Warning - this article needs to be reviewed by someone who knows what they're doing ==

== Articles in this series ==
{{Chunk:Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Contents}}

== Introduction ==
This tutorial is part of the [[Developing a Model-View-Controller (MVC) Component for Joomla!2.5]] tutorial. You are encouraged to read the previous parts of the tutorial before reading this.

== Update the view ==

With your favorite file manager and editor, update the file ''site/views/updhelloworld/view.html.php'' to include setting the state. For the stylesheet, include the import of the html class, and add a new function for including the stylesheet file.

<span id="site/views/updhelloworld/view.html.php">
''site/views/updhelloworld/view.html.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import Joomla view library
jimport('joomla.application.component.view');
// import Joomla html for use with stylesheets
jimport('joomla.html.html');

/**
* HTML View class for the UpdHelloWorld Component
*/
class HelloWorldViewUpdHelloWorld extends JView
{
// Overwriting JView display method
function display($tpl = null)
{
$app = JFactory::getApplication();
$params = $app->getParams();
$dispatcher = JDispatcher::getInstance();

// Get some data from the models
$state = $this->get('State');
$item = $this->get('Item');
$this->form = $this->get('Form');
$this->state = $this->get('State');

// Check for errors.
if (count($errors = $this->get('Errors')))
{
JError::raiseError(500, implode('<br />', $errors));
return false;
}

// get the stylesheet and/or other document values such as title
$this->addDocStyle();

// Display the view
parent::display($tpl);
}

/**
* Add the stylesheet to the document.
*/
protected function addDocStyle()
{
$doc = JFactory::getDocument();
$doc->addStyleSheet('media/com_helloworld/css/site.stylesheet.css');
}

}
</source>
</span>

== Update the layout ==

In Joomla, views display data using a layout. With your favorite file manager and editor, edit your file ''site/views/updhelloworld/tmpl/default.php'' to get the parameter values

<span id="site/views/updhelloworld/tmpl/default.php">
''site/views/updhelloworld/tmpl/default.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

JHtml::_('behavior.keepalive');
JHtml::_('behavior.formvalidation');
JHtml::_('behavior.tooltip');

// get the menu parameters for use
$menuparams = $this->state->get("menuparams");
$headingtxtcolor = $menuparams->get("headingtxtcolor");
$headingbgcolor = $menuparams->get("headingbgcolor");

?>
<h2 style="color:<?php echo $headingtxtcolor; ?>; background-color:<?php echo $headingbgcolor; ?>;">Update the Hello World greeting</h2>

<form class="form-validate" action="<?php echo JRoute::_('index.php'); ?>" method="post" id="updhelloworld" name="updhelloworld">
<fieldset>
<dl>
<dt><?php echo $this->form->getLabel('id'); ?></dt>
<dd><?php echo $this->form->getInput('id'); ?></dd>
<dt></dt><dd></dd>
<dt><?php echo $this->form->getLabel('greeting'); ?></dt>
<dd><?php echo $this->form->getInput('greeting'); ?></dd>
<dt></dt><dd></dd>
<dt></dt>
<dd><input type="hidden" name="option" value="com_helloworld" />
<input type="hidden" name="task" value="updhelloworld.submit" />
</dd>
<dt></dt>
<dd><button type="submit" class="button"><?php echo JText::_('Submit'); ?></button>
<?php echo JHtml::_('form.token'); ?>
</dd>
</dl>
<fieldset>
</form>
<div class="clr"></div>

</source>
</span>

This layout utilises the forms design which resides with the related model. The getLabel and getInput will pickup the xml fields defined and display appropriately. More on the xml file within the models section of this tutorial.

Update the file ''site/views/updhelloworld/tmpl/default.xml'' containing

<span id="site/views/updhelloworld/tmpl/default.xml">
''site/views/updhelloworld/tmpl/default.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<metadata>
<layout title="COM_HELLOWORLD_UPDHELLOWORLD_VIEW_DEFAULT_TITLE">
<message>COM_HELLOWORLD_UPDHELLOWORLD_VIEW_DEFAULT_DESC</message>
</layout>
<fields name="params">
<fieldset name="request">
<field name="headingtxtcolor" type="text" default="#ff0000" size="40"
label="COM_HELLOWORLD_UPDHELLOWORLD_FIELD_HEADINGTXTCOLOR_LABEL"
description="COM_HELLOWORLD_UPDHELLOWORLD_FIELD_HEADINGTXTCOLOR_DESC" />
<field name="headingbgcolor" type="text" default="#0000ff" size="40"
label="COM_HELLOWORLD_UPDHELLOWORLD_FIELD_HEADINGBGCOLOR_LABEL"
description="COM_HELLOWORLD_UPDHELLOWORLD_FIELD_HEADINGBGCOLOR_DESC" />
</fieldset>
</fields>
</metadata>

</source>
</span>

This defines the parameter fields and allows for default values to be set.

== Update the model ==

The ''UpdHelloWorld'' model sets up the data sent from the related form and allows for saving the data from the form into the database. In the getItem method we will get the values from the parameters.

<span id="site/models/updhelloworld.php">
''site/models/updhelloworld.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// Include dependancy of the main model form
jimport('joomla.application.component.modelform');
// import Joomla modelitem library
jimport('joomla.application.component.modelitem');
// Include dependancy of the dispatcher
jimport('joomla.event.dispatcher');

/**
* UpdHelloWorld Model
*/
class HelloWorldModelUpdHelloWorld extends JModelForm
{
/**
* @var object item
*/
protected $item;

/**
* Get the data for a new qualification
*/
public function getForm($data = array(), $loadData = true)
{

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

// Get the form.
$form = $this->loadForm('com_helloworld.updhelloworld', 'updhelloworld', array('control' => 'jform', 'load_data' => true));
if (empty($form)) {
return false;
}
return $form;

}

/**
* Get the message
* @return object The message to be displayed to the user
*/
function &getItem()
{

if (!isset($this->_item))
{
$cache = JFactory::getCache('com_helloworld', '');
$id = $this->getState('helloworld.id');
$this->_item = $cache->get($id);
if ($this->_item === false) {

// Menu parameters
$menuitemid = JRequest::getInt( 'Itemid' ); // this returns the menu id number so you can reference parameters
$menu = JSite::getMenu();
if ($menuitemid) {
$menuparams = $menu->getParams( $menuitemid );
$headingtxtcolor = $menuparams->get('headingtxtcolor'); // This shows how to get an individual parameter for use
$headingbgcolor = $menuparams->get('headingbgcolor'); // This shows how to get an individual parameter for use
}
$this->setState('menuparams', $menuparams); // this sets the parameter values to the state for later use

}
}
return $this->_item;

}

public function updItem($data)
{
// set the variables from the passed data
$id = $data['id'];
$greeting = $data['greeting'];

// set the data into a query to update the record
$db = $this->getDbo();
$query = $db->getQuery(true);
$query->clear();
$query->update(' #__helloworld ');
$query->set(' greeting = '.$db->Quote($greeting) );
$query->where(' id = ' . (int) $id );

$db->setQuery((string)$query);

if (!$db->query()) {
JError::raiseError(500, $db->getErrorMsg());
return false;
} else {
return true;
}
}
}

</source>
</span>

== Add a stylesheet file ==

Create a new stylesheet file to contain the css code you want to use on your component.

<span id="media/css/site.stylesheet.css">
''media/css/site.stylesheet.css''
<source lang="css">
p {
color: #000000;
}
</span>

== Adding some language keys ==

Add the last 4 lines to the ''admin/language/en-GB/en-GB.com_helloworld.sys.ini'' file to provide the text link for the parameter type display. And being for the backend, it resides in the admin language folder.

<span id="admin/language/en-GB/en-GB.com_helloworld.sys.ini">
''admin/language/en-GB/en-GB.com_helloworld.sys.ini''
<source lang="ini">
COM_HELLOWORLD="Hello World!"
COM_HELLOWORLD_DESCRIPTION="This is the Hello World description"
COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_DESC="This view displays a selected message"
COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_TITLE="Hello World"
COM_HELLOWORLD_INSTALL_TEXT="HelloWorld Install script"
COM_HELLOWORLD_MENU="Hello World!"
COM_HELLOWORLD_POSTFLIGHT_DISCOVER_INSTALL_TEXT="HelloWorld postlight discover install script"
COM_HELLOWORLD_POSTFLIGHT_INSTALL_TEXT="HelloWorld postflight install script"
COM_HELLOWORLD_POSTFLIGHT_UNINSTALL_TEXT="HelloWorld postflight uninstall script"
COM_HELLOWORLD_POSTFLIGHT_UPDATE_TEXT="HelloWorld postflight update script"
COM_HELLOWORLD_PREFLIGHT_DISCOVER_INSTALL_TEXT="HelloWorld preflight discover install script"
COM_HELLOWORLD_PREFLIGHT_INSTALL_TEXT="HelloWorld preflight install script"
COM_HELLOWORLD_PREFLIGHT_UNINSTALL_TEXT="HelloWorld preflight uninstall script"
COM_HELLOWORLD_PREFLIGHT_UPDATE_TEXT="HelloWorld preflight update script"
COM_HELLOWORLD_UNINSTALL_TEXT="HelloWorld Uninstall script"
COM_HELLOWORLD_UPDATE_TEXT="HelloWorld Update script"
COM_HELLOWORLD_UPDHELLOWORLD_VIEW_DEFAULT_TITLE="Update the Greeting"
COM_HELLOWORLD_UPDHELLOWORLD_VIEW_DEFAULT_DESC="Update greeting here"
COM_HELLOWORLD_UPDHELLOWORLD_FIELD_HEADINGTXTCOLOR_LABEL="Colour of Text"
COM_HELLOWORLD_UPDHELLOWORLD_FIELD_HEADINGTXTCOLOR_DESC="Set the colour of the text on the heading"
COM_HELLOWORLD_UPDHELLOWORLD_FIELD_HEADINGBGCOLOR_LABEL="Colour of Background"
COM_HELLOWORLD_UPDHELLOWORLD_FIELD_HEADINGBGCOLOR_DESC="Set the colour of the background on the heading"</source>
</span>

The ''_populateState'' method is, by default, automatically called when a state is read by the ''getState'' method.

== Packaging the component ==

Content of your code directory-
* ''[[#helloworld.xml|helloworld.xml]]''
* ''[[#script.php|script.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_02#site/helloworld.php|site/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_02#site/controller.php|site/controller.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/updhelloworld.php|site/updhelloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/controllers/updhelloworld.php|site/controllers/updhelloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/controllers/index.html|site/controllers/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/views/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/views/helloworld/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#site/views/helloworld/view.html.php|site/views/helloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/views/updhelloworld/view.html.php|site/views/updhelloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/views/helloworld/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/views/updhelloworld/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_06#site/views/helloworld/tmpl/default.xml|site/views/helloworld/tmpl/default.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#site/views/helloworld/tmpl/default.php|site/views/helloworld/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/views/updhelloworld/tmpl/default.xml|site/views/updhelloworld/tmpl/default.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/views/updhelloworld/tmpl/default.php|site/views/updhelloworld/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/models/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#site/models/helloworld.php|site/models/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/models/updhelloworld.php|site/models/updhelloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/models/forms/updhelloworld.xml|site/models/forms/updhelloworld.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/models/forms/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/language/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/language/en-GB/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_08#site/language/en-GB/en-GB.com_helloworld.ini|site/language/en-GB/en-GB.com_helloworld.ini]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/access.xml|admin/access.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/config.xml|admin/config.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/helloworld.php|admin/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_12#admin/controller.php|admin/controller.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/sql/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/sql/install.mysql.utf8.sql|admin/sql/install.mysql.utf8.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_06#admin/sql/uninstall.mysql.utf8.sql|admin/sql/uninstall.mysql.utf8.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/sql/updates/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/sql/updates/mysql/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#admin/sql/updates/mysql/0.0.1.sql|admin/sql/updates/mysql/0.0.1.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_06#admin/sql/install.mysql.utf8.sql|admin/sql/updates/mysql/0.0.6.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_12#admin/sql/updates/mysql/0.0.12.sql|admin/sql/updates/mysql/0.0.12.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/sql/updates/mysql/0.0.13.sql|admin/sql/updates/mysql/0.0.13.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/models/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/models/fields/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_12#admin/models/fields/helloworld.php|admin/models/fields/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/models/forms/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/models/forms/helloworld.xml|admin/models/forms/helloworld.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/models/forms/helloworld.js|admin/models/forms/helloworld.js]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/models/rules/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/models/rules/greeting.php|admin/models/rules/greeting.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/models/helloworld.php|admin/models/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_09#admin/models/helloworlds.php|admin/models/helloworlds.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/helloworlds/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/views/helloworlds/view.html.php|admin/views/helloworlds/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/helloworlds/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/views/helloworlds/tmpl/default.php|admin/views/helloworlds/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_07#admin/views/helloworlds/tmpl/default_head.php|admin/views/helloworlds/tmpl/default_head.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_07#admin/views/helloworlds/tmpl/default_body.php|admin/views/helloworlds/tmpl/default_body.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_07#admin/views/helloworlds/tmpl/default_foot.php|admin/views/helloworlds/tmpl/default_foot.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/helloworld/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/views/helloworld/view.html.php|admin/views/helloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/views/helloworld/submitbutton.js|admin/views/helloworld/submitbutton.js]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/helloworld/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/views/helloworld/tmpl/edit.php|admin/views/helloworld/tmpl/edit.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/helpers/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/helpers/helloworld.php|admin/helpers/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/tables/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/tables/helloworld.php|admin/tables/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/language/en-GB/en-GB.com_helloworld.ini|admin/language/en-GB/en-GB.com_helloworld.ini]]''
* ''[[#admin/language/en-GB/en-GB.com_helloworld.sys.ini|admin/language/en-GB/en-GB.com_helloworld.sys.ini]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/controllers/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/controllers/helloworld.php|admin/controllers/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/controllers/helloworlds.php|admin/controllers/helloworlds.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_08#language/en-GB/en-GB.ini|language/en-GB/en-GB.ini]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|media/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|media/images/index.html]]''
* ''media/images/tux-16x16.png''
* ''media/images/tux-48x48.png''

Create a compressed file of this directory or directly download the [http://www.glennarkell.com/joomlaorg/com_helloworld_0.0.19.zip] and install it using the extension manager of Joomla. You can add a menu item of this component using the menu manager in the backend.

Be sure to update your manifest to include the stylesheet folder within the media section.

<span id="helloworld.xml">
''helloworld.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="2.5.0" method="upgrade">

<name>COM_HELLOWORLD</name>

<creationDate>November 2009</creationDate>
<author>John Doe</author>
<authorEmail>john.doe@example.org</authorEmail>
<authorUrl>http://www.example.org</authorUrl>
<copyright>Copyright Info</copyright>
<license>License Info</license>

<version>0.0.19</version>

<description>COM_HELLOWORLD_DESCRIPTION</description>


<scriptfile>script.php</scriptfile>

<install> 
<sql>
<file driver="mysql" charset="utf8">sql/install.mysql.utf8.sql</file>
</sql>
</install>
<uninstall> 
<sql>
<file driver="mysql" charset="utf8">sql/uninstall.mysql.utf8.sql</file>
</sql>
</uninstall>
<update> 
<schemas>
<schemapath type="mysql">sql/updates/mysql</schemapath>
</schemas>
</update>



<files folder="site">
<filename>index.html</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>
<filename>updhelloworld.php</filename>
<folder>views</folder>
<folder>models</folder>
<folder>controllers</folder>
<folder>language</folder>
</files>

<media destination="com_helloworld" folder="media">
<filename>index.html</filename>
<folder>css</folder>
<folder>images</folder>
</media>

<administration>

<menu img="../media/com_helloworld/images/tux-16x16.png">COM_HELLOWORLD_MENU</menu>


<files folder="admin">

<filename>index.html</filename>
<filename>config.xml</filename>
<filename>access.xml</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>

<folder>sql</folder>

<folder>tables</folder>

<folder>models</folder>

<folder>views</folder>

<folder>controllers</folder>

<folder>helpers</folder>
</files>

<languages folder="admin">
<language tag="en-GB">language/en-GB/en-GB.com_helloworld.ini</language>
<language tag="en-GB">language/en-GB/en-GB.com_helloworld.sys.ini</language>
</languages>
</administration>


<updateservers>

<server type="extension" priority="1" name="HelloWorld Update Site">http://yourdomain.com/update/helloworld-update.xml</server>
</updateservers>

</extension>

</source>
</span>

Now when you view your '''hello-world''' update function via the front-end menu option, you will see the colours of the text and background being utilised.

== Zips ==
Download the zip file for this Part:
[http://www.glennarkell.com/joomlaorg/com_helloworld_0.0.19.zip]

== Navigate ==

[[Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Part 18|Prev: Example of a Frontend Update Function]]

== Contributors ==
*[[User:garkell|Glenn Arkell]]

[[Category:Development]]
[[category:Joomla! 1.6]]
[[category:Joomla! 1.7]]
[[category:Joomla! 2.5]]
[[category:Manual]]

Archived:Developing a MVC Component/Example of menu parameters and stylesheets

2012-05-12T22:57:29Z

Garkell: Add new example of menu parameters & stylesheets - extending on the Update Function (Part 18) example.

This tutorial is for {{JVer|1.6}} {{JVer|1.7}} {{JVer|2.5}}
== Warning - this article needs to be reviewed by someone who knows what they're doing ==

== Articles in this series ==
{{Chunk:Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Contents}}

== Introduction ==
This tutorial is part of the [[Developing a Model-View-Controller (MVC) Component for Joomla!2.5]] tutorial. You are encouraged to read the previous parts of the tutorial before reading this.

== Update the view ==

With your favorite file manager and editor, update the file ''site/views/updhelloworld/view.html.php'' to include setting the state. For the stylesheet, include the import of the html class, and add a new function for including the stylesheet file.

<span id="site/views/updhelloworld/view.html.php">
''site/views/updhelloworld/view.html.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import Joomla view library
jimport('joomla.application.component.view');
// import Joomla html for use with stylesheets
jimport('joomla.html.html');

/**
* HTML View class for the UpdHelloWorld Component
*/
class HelloWorldViewUpdHelloWorld extends JView
{
// Overwriting JView display method
function display($tpl = null)
{
$app = JFactory::getApplication();
$params = $app->getParams();
$dispatcher = JDispatcher::getInstance();

// Get some data from the models
$state = $this->get('State');
$item = $this->get('Item');
$this->form = $this->get('Form');
$this->state = $this->get('State');

// Check for errors.
if (count($errors = $this->get('Errors')))
{
JError::raiseError(500, implode('<br />', $errors));
return false;
}

// get the stylesheet and/or other document values such as title
$this->addDocStyle();

// Display the view
parent::display($tpl);
}

/**
* Add the stylesheet to the document.
*/
protected function addDocStyle()
{
$doc = JFactory::getDocument();
$doc->addStyleSheet('media/com_helloworld/css/site.stylesheet.css');
}

}
</source>
</span>

== Update the layout ==

In Joomla, views display data using a layout. With your favorite file manager and editor, edit your file ''site/views/updhelloworld/tmpl/default.php'' to get the parameter values

<span id="site/views/updhelloworld/tmpl/default.php">
''site/views/updhelloworld/tmpl/default.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

JHtml::_('behavior.keepalive');
JHtml::_('behavior.formvalidation');
JHtml::_('behavior.tooltip');

// get the menu parameters for use
$menuparams = $this->state->get("menuparams");
$headingtxtcolor = $menuparams->get("headingtxtcolor");
$headingbgcolor = $menuparams->get("headingbgcolor");

?>
<h2 style="color:<?php echo $headingtxtcolor; ?>; background-color:<?php echo $headingbgcolor; ?>;">Update the Hello World greeting</h2>

<form class="form-validate" action="<?php echo JRoute::_('index.php'); ?>" method="post" id="updhelloworld" name="updhelloworld">
<fieldset>
<dl>
<dt><?php echo $this->form->getLabel('id'); ?></dt>
<dd><?php echo $this->form->getInput('id'); ?></dd>
<dt></dt><dd></dd>
<dt><?php echo $this->form->getLabel('greeting'); ?></dt>
<dd><?php echo $this->form->getInput('greeting'); ?></dd>
<dt></dt><dd></dd>
<dt></dt>
<dd><input type="hidden" name="option" value="com_helloworld" />
<input type="hidden" name="task" value="updhelloworld.submit" />
</dd>
<dt></dt>
<dd><button type="submit" class="button"><?php echo JText::_('Submit'); ?></button>
<?php echo JHtml::_('form.token'); ?>
</dd>
</dl>
<fieldset>
</form>
<div class="clr"></div>

</source>
</span>

This layout utilises the forms design which resides with the related model. The getLabel and getInput will pickup the xml fields defined and display appropriately. More on the xml file within the models section of this tutorial.

Update the file ''site/views/updhelloworld/tmpl/default.xml'' containing

<span id="site/views/updhelloworld/tmpl/default.xml">
''site/views/updhelloworld/tmpl/default.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<metadata>
<layout title="COM_HELLOWORLD_UPDHELLOWORLD_VIEW_DEFAULT_TITLE">
<message>COM_HELLOWORLD_UPDHELLOWORLD_VIEW_DEFAULT_DESC</message>
</layout>
<fields name="params">
<fieldset name="request">
<field name="headingtxtcolor" type="text" default="#ff0000" size="40"
label="COM_HELLOWORLD_UPDHELLOWORLD_FIELD_HEADINGTXTCOLOR_LABEL"
description="COM_HELLOWORLD_UPDHELLOWORLD_FIELD_HEADINGTXTCOLOR_DESC" />
<field name="headingbgcolor" type="text" default="#0000ff" size="40"
label="COM_HELLOWORLD_UPDHELLOWORLD_FIELD_HEADINGBGCOLOR_LABEL"
description="COM_HELLOWORLD_UPDHELLOWORLD_FIELD_HEADINGBGCOLOR_DESC" />
</fieldset>
</fields>
</metadata>

</source>
</span>

This defines the parameter fields and allows for default values to be set.

== Update the model ==

The ''UpdHelloWorld'' model sets up the data sent from the related form and allows for saving the data from the form into the database. In the getItem method we will get the values from the parameters.

<span id="site/models/updhelloworld.php">
''site/models/updhelloworld.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// Include dependancy of the main model form
jimport('joomla.application.component.modelform');
// import Joomla modelitem library
jimport('joomla.application.component.modelitem');
// Include dependancy of the dispatcher
jimport('joomla.event.dispatcher');

/**
* UpdHelloWorld Model
*/
class HelloWorldModelUpdHelloWorld extends JModelForm
{
/**
* @var object item
*/
protected $item;

/**
* Get the data for a new qualification
*/
public function getForm($data = array(), $loadData = true)
{

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

// Get the form.
$form = $this->loadForm('com_helloworld.updhelloworld', 'updhelloworld', array('control' => 'jform', 'load_data' => true));
if (empty($form)) {
return false;
}
return $form;

}

/**
* Get the message
* @return object The message to be displayed to the user
*/
function &getItem()
{

if (!isset($this->_item))
{
$cache = JFactory::getCache('com_helloworld', '');
$id = $this->getState('helloworld.id');
$this->_item = $cache->get($id);
if ($this->_item === false) {

// Menu parameters
$menuitemid = JRequest::getInt( 'Itemid' ); // this returns the menu id number so you can reference parameters
$menu = JSite::getMenu();
if ($menuitemid) {
$menuparams = $menu->getParams( $menuitemid );
$headingtxtcolor = $menuparams->get('headingtxtcolor'); // This shows how to get an individual parameter for use
$headingbgcolor = $menuparams->get('headingbgcolor'); // This shows how to get an individual parameter for use
}
$this->setState('menuparams', $menuparams); // this sets the parameter values to the state for later use

}
}
return $this->_item;

}

public function updItem($data)
{
// set the variables from the passed data
$id = $data['id'];
$greeting = $data['greeting'];

// set the data into a query to update the record
$db = $this->getDbo();
$query = $db->getQuery(true);
$query->clear();
$query->update(' #__helloworld ');
$query->set(' greeting = '.$db->Quote($greeting) );
$query->where(' id = ' . (int) $id );

$db->setQuery((string)$query);

if (!$db->query()) {
JError::raiseError(500, $db->getErrorMsg());
return false;
} else {
return true;
}
}
}

</source>
</span>

== Add a stylesheet file ==

Create a new stylesheet file to contain the css code you want to use on your component.

<span id="media/css/site.stylesheet.css">
''media/css/site.stylesheet.css''
<source lang="css">
p {
color: #000000;
}

== Adding some language keys ==

Add the last 4 lines to the ''admin/language/en-GB/en-GB.com_helloworld.sys.ini'' file to provide the text link for the parameter type display. And being for the backend, it resides in the admin language folder.

<span id="admin/language/en-GB/en-GB.com_helloworld.sys.ini">
''admin/language/en-GB/en-GB.com_helloworld.sys.ini''
<source lang="ini">
COM_HELLOWORLD="Hello World!"
COM_HELLOWORLD_DESCRIPTION="This is the Hello World description"
COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_DESC="This view displays a selected message"
COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_TITLE="Hello World"
COM_HELLOWORLD_INSTALL_TEXT="HelloWorld Install script"
COM_HELLOWORLD_MENU="Hello World!"
COM_HELLOWORLD_POSTFLIGHT_DISCOVER_INSTALL_TEXT="HelloWorld postlight discover install script"
COM_HELLOWORLD_POSTFLIGHT_INSTALL_TEXT="HelloWorld postflight install script"
COM_HELLOWORLD_POSTFLIGHT_UNINSTALL_TEXT="HelloWorld postflight uninstall script"
COM_HELLOWORLD_POSTFLIGHT_UPDATE_TEXT="HelloWorld postflight update script"
COM_HELLOWORLD_PREFLIGHT_DISCOVER_INSTALL_TEXT="HelloWorld preflight discover install script"
COM_HELLOWORLD_PREFLIGHT_INSTALL_TEXT="HelloWorld preflight install script"
COM_HELLOWORLD_PREFLIGHT_UNINSTALL_TEXT="HelloWorld preflight uninstall script"
COM_HELLOWORLD_PREFLIGHT_UPDATE_TEXT="HelloWorld preflight update script"
COM_HELLOWORLD_UNINSTALL_TEXT="HelloWorld Uninstall script"
COM_HELLOWORLD_UPDATE_TEXT="HelloWorld Update script"
COM_HELLOWORLD_UPDHELLOWORLD_VIEW_DEFAULT_TITLE="Update the Greeting"
COM_HELLOWORLD_UPDHELLOWORLD_VIEW_DEFAULT_DESC="Update greeting here"
COM_HELLOWORLD_UPDHELLOWORLD_FIELD_HEADINGTXTCOLOR_LABEL="Colour of Text"
COM_HELLOWORLD_UPDHELLOWORLD_FIELD_HEADINGTXTCOLOR_DESC="Set the colour of the text on the heading"
COM_HELLOWORLD_UPDHELLOWORLD_FIELD_HEADINGBGCOLOR_LABEL="Colour of Background"
COM_HELLOWORLD_UPDHELLOWORLD_FIELD_HEADINGBGCOLOR_DESC="Set the colour of the background on the heading"</source>
</span>

The ''_populateState'' method is, by default, automatically called when a state is read by the ''getState'' method.

== Packaging the component ==

Content of your code directory-
* ''[[#helloworld.xml|helloworld.xml]]''
* ''[[#script.php|script.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_02#site/helloworld.php|site/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_02#site/controller.php|site/controller.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/updhelloworld.php|site/updhelloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/controllers/updhelloworld.php|site/controllers/updhelloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/controllers/index.html|site/controllers/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/views/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/views/helloworld/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#site/views/helloworld/view.html.php|site/views/helloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/views/updhelloworld/view.html.php|site/views/updhelloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/views/helloworld/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/views/updhelloworld/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_06#site/views/helloworld/tmpl/default.xml|site/views/helloworld/tmpl/default.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#site/views/helloworld/tmpl/default.php|site/views/helloworld/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/views/updhelloworld/tmpl/default.xml|site/views/updhelloworld/tmpl/default.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/views/updhelloworld/tmpl/default.php|site/views/updhelloworld/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/models/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#site/models/helloworld.php|site/models/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/models/updhelloworld.php|site/models/updhelloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/models/forms/updhelloworld.xml|site/models/forms/updhelloworld.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/models/forms/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/language/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/language/en-GB/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_08#site/language/en-GB/en-GB.com_helloworld.ini|site/language/en-GB/en-GB.com_helloworld.ini]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/access.xml|admin/access.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/config.xml|admin/config.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/helloworld.php|admin/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_12#admin/controller.php|admin/controller.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/sql/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/sql/install.mysql.utf8.sql|admin/sql/install.mysql.utf8.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_06#admin/sql/uninstall.mysql.utf8.sql|admin/sql/uninstall.mysql.utf8.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/sql/updates/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/sql/updates/mysql/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#admin/sql/updates/mysql/0.0.1.sql|admin/sql/updates/mysql/0.0.1.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_06#admin/sql/install.mysql.utf8.sql|admin/sql/updates/mysql/0.0.6.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_12#admin/sql/updates/mysql/0.0.12.sql|admin/sql/updates/mysql/0.0.12.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/sql/updates/mysql/0.0.13.sql|admin/sql/updates/mysql/0.0.13.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/models/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/models/fields/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_12#admin/models/fields/helloworld.php|admin/models/fields/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/models/forms/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/models/forms/helloworld.xml|admin/models/forms/helloworld.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/models/forms/helloworld.js|admin/models/forms/helloworld.js]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/models/rules/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/models/rules/greeting.php|admin/models/rules/greeting.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/models/helloworld.php|admin/models/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_09#admin/models/helloworlds.php|admin/models/helloworlds.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/helloworlds/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/views/helloworlds/view.html.php|admin/views/helloworlds/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/helloworlds/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/views/helloworlds/tmpl/default.php|admin/views/helloworlds/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_07#admin/views/helloworlds/tmpl/default_head.php|admin/views/helloworlds/tmpl/default_head.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_07#admin/views/helloworlds/tmpl/default_body.php|admin/views/helloworlds/tmpl/default_body.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_07#admin/views/helloworlds/tmpl/default_foot.php|admin/views/helloworlds/tmpl/default_foot.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/helloworld/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/views/helloworld/view.html.php|admin/views/helloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/views/helloworld/submitbutton.js|admin/views/helloworld/submitbutton.js]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/helloworld/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/views/helloworld/tmpl/edit.php|admin/views/helloworld/tmpl/edit.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/helpers/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/helpers/helloworld.php|admin/helpers/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/tables/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/tables/helloworld.php|admin/tables/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/language/en-GB/en-GB.com_helloworld.ini|admin/language/en-GB/en-GB.com_helloworld.ini]]''
* ''[[#admin/language/en-GB/en-GB.com_helloworld.sys.ini|admin/language/en-GB/en-GB.com_helloworld.sys.ini]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/controllers/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/controllers/helloworld.php|admin/controllers/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/controllers/helloworlds.php|admin/controllers/helloworlds.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_08#language/en-GB/en-GB.ini|language/en-GB/en-GB.ini]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|media/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|media/images/index.html]]''
* ''media/images/tux-16x16.png''
* ''media/images/tux-48x48.png''

Create a compressed file of this directory or directly download the [http://www.glennarkell.com/joomlaorg/com_helloworld_0.0.19.zip] and install it using the extension manager of Joomla. You can add a menu item of this component using the menu manager in the backend.

Be sure to update your manifest to include the stylesheet folder within the media section.

<span id="helloworld.xml">
''helloworld.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="2.5.0" method="upgrade">

<name>COM_HELLOWORLD</name>

<creationDate>November 2009</creationDate>
<author>John Doe</author>
<authorEmail>john.doe@example.org</authorEmail>
<authorUrl>http://www.example.org</authorUrl>
<copyright>Copyright Info</copyright>
<license>License Info</license>

<version>0.0.19</version>

<description>COM_HELLOWORLD_DESCRIPTION</description>


<scriptfile>script.php</scriptfile>

<install> 
<sql>
<file driver="mysql" charset="utf8">sql/install.mysql.utf8.sql</file>
</sql>
</install>
<uninstall> 
<sql>
<file driver="mysql" charset="utf8">sql/uninstall.mysql.utf8.sql</file>
</sql>
</uninstall>
<update> 
<schemas>
<schemapath type="mysql">sql/updates/mysql</schemapath>
</schemas>
</update>



<files folder="site">
<filename>index.html</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>
<filename>updhelloworld.php</filename>
<folder>views</folder>
<folder>models</folder>
<folder>controllers</folder>
<folder>language</folder>
</files>

<media destination="com_helloworld" folder="media">
<filename>index.html</filename>
<folder>css</folder>
<folder>images</folder>
</media>

<administration>

<menu img="../media/com_helloworld/images/tux-16x16.png">COM_HELLOWORLD_MENU</menu>


<files folder="admin">

<filename>index.html</filename>
<filename>config.xml</filename>
<filename>access.xml</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>

<folder>sql</folder>

<folder>tables</folder>

<folder>models</folder>

<folder>views</folder>

<folder>controllers</folder>

<folder>helpers</folder>
</files>

<languages folder="admin">
<language tag="en-GB">language/en-GB/en-GB.com_helloworld.ini</language>
<language tag="en-GB">language/en-GB/en-GB.com_helloworld.sys.ini</language>
</languages>
</administration>


<updateservers>

<server type="extension" priority="1" name="HelloWorld Update Site">http://yourdomain.com/update/helloworld-update.xml</server>
</updateservers>

</extension>

</source>
</span>

Now when you view your '''hello-world''' update function via the front-end menu option, you will see the colours of the text and background being utilised.

== Zips ==
Download the zip file for this Part:
[http://www.glennarkell.com/joomlaorg/com_helloworld_0.0.19.zip]

== Navigate ==

[[Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Part 18|Prev: Example of a Frontend Update Function]]

== Contributors ==
*[[User:garkell|Glenn Arkell]]

[[Category:Development]]
[[category:Joomla! 1.6]]
[[category:Joomla! 1.7]]
[[category:Joomla! 2.5]]
[[category:Manual]]

Chunk:Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Contents

2012-05-12T22:36:45Z

Garkell: Add new example of menu parameters & stylesheets - extending on the Update Function (Part 18) example.

* [[Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Part 01|Developing a Basic Component]]
* [[Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Part 02|Adding a view to the site part]]
* [[Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Part 03|Adding a menu type to the site part]]
* [[Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Part 04|Adding a model to the site part]]
* [[Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Part 05|Adding a variable request in the menu type]]
* [[Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Part 06|Using the database]]
* [[Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Part 07|Basic backend]]
* [[Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Part 08|Adding language management]]
* [[Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Part 09|Adding backend actions]]
* [[Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Part 10|Adding decorations to the backend]]
* [[Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Part 11|Adding verifications]]
* [[Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Part 12|Adding categories]]
* [[Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Part 13|Adding configuration]]
* [[Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Part 14|Adding ACL]]
* [[Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Part 15|Adding an install/uninstall/update script file]]
* [[Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Part 16|Using the language filter facility]]
* [[Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Part 17|Adding an update server]]
* [[Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Part 18|Example of a Frontend Update Function]]
* [[Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Part 19|Example of Menu Parameters & Stylesheets]]

Archived:Developing a MVC Component/Example of a frontend update function

2012-05-11T10:12:35Z

Garkell: Tidied up the form xml for presentation

This tutorial is for {{JVer|1.6}} {{JVer|1.7}} {{JVer|2.5}}
== Warning - this article needs to be reviewed by someone who knows what they're doing ==

== Articles in this series ==
{{Chunk:Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Contents}}

== Introduction ==
This tutorial is part of the [[Developing a Model-View-Controller (MVC) Component for Joomla!2.5]] tutorial. You are encouraged to read the previous parts of the tutorial before reading this.

== Basic frontend form ==
Designing the frontend interface leads us to create a Model-View-Controller triptych similar to the backend in Part 7.

== Create the specific controller ==
The entry point now gets an instance of an ''UpdHelloWorld'' prefixed controller which extends the function of JControllerForm. Let's create a basic controllerform for the site part:

<span id="site/controllers/updhelloworld.php">
''site/controllers/updhelloworld.php''
<source lang="php">
<?php

// No direct access.
defined('_JEXEC') or die;

// Include dependancy of the main controllerform class
jimport('joomla.application.component.controllerform');

class HelloWorldControllerUpdHelloWorld extends JControllerForm
{

public function getModel($name = '', $prefix = '', $config = array('ignore_request' => true))
{
return parent::getModel($name, $prefix, array('ignore_request' => false));
}

public function submit()
{
// Check for request forgeries.
JRequest::checkToken() or jexit(JText::_('JINVALID_TOKEN'));

// Initialise variables.
$app = JFactory::getApplication();
$model = $this->getModel('updhelloworld');

// Get the data from the form POST
$data = JRequest::getVar('jform', array(), 'post', 'array');

// Now update the loaded data to the database via a function in the model
$upditem = $model->updItem($data);

// check if ok and display appropriate message. This can also have a redirect if desired.
if ($upditem) {
echo "<h2>Updated Greeting has been saved</h2>";
} else {
echo "<h2>Updated Greeting failed to be saved</h2>";
}

return true;
}

}
</source>
</span>

This controller will display the appropriate message after the form is submitted.

== Create the view ==

With your favorite file manager and editor, create a file ''site/views/updhelloworld/view.html.php'' containing:

<span id="site/views/updhelloworld/view.html.php">
''site/views/updhelloworld/view.html.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import Joomla view library
jimport('joomla.application.component.view');

/**
* HTML View class for the UpdHelloWorld Component
*/
class HelloWorldViewUpdHelloWorld extends JView
{
// Overwriting JView display method
function display($tpl = null)
{
$app = JFactory::getApplication();
$params = $app->getParams();
$dispatcher = JDispatcher::getInstance();

// Get some data from the models
$state = $this->get('State');
$item = $this->get('Item');
$this->form = $this->get('Form');

// Check for errors.
if (count($errors = $this->get('Errors')))
{
JError::raiseError(500, implode('<br />', $errors));
return false;
}
// Display the view
parent::display($tpl);
}
}
</source>
</span>

In Joomla, views display data using a layout. With your favorite file manager and editor, put a file ''site/views/updhelloworld/tmpl/default.php'' containing

<span id="site/views/updhelloworld/tmpl/default.php">
''site/views/updhelloworld/tmpl/default.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

JHtml::_('behavior.keepalive');
JHtml::_('behavior.formvalidation');
JHtml::_('behavior.tooltip');

?>
<h2>Update the Hello World greeting</h2>

<form class="form-validate" action="<?php echo JRoute::_('index.php'); ?>" method="post" id="updhelloworld" name="updhelloworld">
<fieldset>
<dl>
<dt><?php echo $this->form->getLabel('id'); ?></dt>
<dd><?php echo $this->form->getInput('id'); ?></dd>
<dt></dt><dd></dd>
<dt><?php echo $this->form->getLabel('greeting'); ?></dt>
<dd><?php echo $this->form->getInput('greeting'); ?></dd>
<dt></dt><dd></dd>
<dt></dt>
<dd><input type="hidden" name="option" value="com_helloworld" />
<input type="hidden" name="task" value="updhelloworld.submit" />
</dd>
<dt></dt>
<dd><button type="submit" class="button"><?php echo JText::_('Submit'); ?></button>
<?php echo JHtml::_('form.token'); ?>
</dd>
</dl>
<fieldset>
</form>
<div class="clr"></div>

</source>
</span>

This layout utilises the forms design which resides with the related model. The getLabel and getInput will pickup the xml fields defined and display appropriately. More on the xml file within the models section of this tutorial.

Create a file ''site/views/updhelloworld/tmpl/default.xml'' containing

<span id="site/views/updhelloworld/tmpl/default.xml">
''site/views/updhelloworld/tmpl/default.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<metadata>
<layout title="COM_HELLOWORLD_UPDHELLOWORLD_VIEW_DEFAULT_TITLE">
<message>COM_HELLOWORLD_UPDHELLOWORLD_VIEW_DEFAULT_DESC</message>
</layout>
</metadata>

</source>
</span>

This enables a menu option to be allocated to the frontend form.

== Create the model ==
The ''UpdHelloWorld'' model sets up the data through from the related form and allows the mechanism to save the subsequent data loaded into the form into the database.

<span id="site/models/updhelloworld.php">
''site/models/updhelloworld.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// Include dependancy of the main model form
jimport('joomla.application.component.modelform');
// import Joomla modelitem library
jimport('joomla.application.component.modelitem');
// Include dependancy of the dispatcher
jimport('joomla.event.dispatcher');

/**
* UpdHelloWorld Model
*/
class HelloWorldModelUpdHelloWorld extends JModelForm
{
/**
* @var object item
*/
protected $item;

/**
* Get the data for a new qualification
*/
public function getForm($data = array(), $loadData = true)
{

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

// Get the form.
$form = $this->loadForm('com_helloworld.updhelloworld', 'updhelloworld', array('control' => 'jform', 'load_data' => true));
if (empty($form)) {
return false;
}
return $form;

}

/**
* Get the message
* @return object The message to be displayed to the user
*/
function &getItem()
{

if (!isset($this->_item))
{
$cache = JFactory::getCache('com_helloworld', '');
$id = $this->getState('helloworld.id');
$this->_item = $cache->get($id);
if ($this->_item === false) {

}
}
return $this->_item;

}

public function updItem($data)
{
// set the variables from the passed data
$id = $data['id'];
$greeting = $data['greeting'];

// set the data into a query to update the record
$db = $this->getDbo();
$query = $db->getQuery(true);
$query->clear();
$query->update(' #__helloworld ');
$query->set(' greeting = '.$db->Quote($greeting) );
$query->where(' id = ' . (int) $id );

$db->setQuery((string)$query);

if (!$db->query()) {
JError::raiseError(500, $db->getErrorMsg());
return false;
} else {
return true;
}
}
}

</source>
</span>

The following file ''updhelloworld.xml'' should be created using your favourite editor and saved in the forms folder under the models directory. The first of the fields being referenced id using the sql type so that I returns the results from the query into a dropdown list form to be selected.
<span id="site/models/forms/updhelloworld.xml">
''site/models/forms/updhelloworld.xml''
<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<form name="updhelloworld">
<fieldset name="updhelloworld">

<field
name="id"
type="sql"
multiple="false"
size="1"
label="COM_HELLOWORLD_FORM_LBL_UPDHELLOWORLD_ID"
description="COM_HELLOWORLD_FORM_DESC_UPDHELLOWORLD_ID"
query="select id, greeting from #__helloworld"
key_field="id"
value_field="greeting"
default="0"
required="true"
>
<option value="">JOPTION_SELECT_ID</option>
</field>

<field
name="greeting"
type="text"
description="COM_HELLOWORLD_FORM_DESC_UPDHELLOWORLD_GREETING"
label="COM_HELLOWORLD_FORM_LBL_UPDHELLOWORLD_GREETING"
required="true"
size="50" />

</fieldset>
</form>

</source>
</span>

== Adding some language keys ==

This file provides the text link between the label in the model form definition to be displayed in the view. And being for the frontend, it resides in the site folder.

<span id="site/language/en-GB/en-GB.com_helloworld.ini">
''site/language/en-GB/en-GB.com_helloworld.ini''
<source lang="ini">
COM_HELLOWORLD_FORM_LBL_UPDHELLOWORLD_ID="Greeting ID"
COM_HELLOWORLD_FORM_DESC_UPDHELLOWORLD_ID="This is the ID of the Greeting record"
COM_HELLOWORLD_FORM_LBL_UPDHELLOWORLD_GREETING="Greeting"
COM_HELLOWORLD_FORM_DESC_UPDHELLOWORLD_GREETING="Greeting description"
JOPTION_SELECT_ID=" -- Select Greeting to Update -- "
</source>
</span>

Add the last 2 lines to the ''admin/language/en-GB/en-GB.com_helloworld.sys.ini'' file to provide the text link for the menu type display. And being for the backend, it resides in the admin language folder.

<span id="admin/language/en-GB/en-GB.com_helloworld.sys.ini">
''admin/language/en-GB/en-GB.com_helloworld.sys.ini''
<source lang="ini">
COM_HELLOWORLD="Hello World!"
COM_HELLOWORLD_DESCRIPTION="This is the Hello World description"
COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_DESC="This view displays a selected message"
COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_TITLE="Hello World"
COM_HELLOWORLD_INSTALL_TEXT="HelloWorld Install script"
COM_HELLOWORLD_MENU="Hello World!"
COM_HELLOWORLD_POSTFLIGHT_DISCOVER_INSTALL_TEXT="HelloWorld postlight discover install script"
COM_HELLOWORLD_POSTFLIGHT_INSTALL_TEXT="HelloWorld postflight install script"
COM_HELLOWORLD_POSTFLIGHT_UNINSTALL_TEXT="HelloWorld postflight uninstall script"
COM_HELLOWORLD_POSTFLIGHT_UPDATE_TEXT="HelloWorld postflight update script"
COM_HELLOWORLD_PREFLIGHT_DISCOVER_INSTALL_TEXT="HelloWorld preflight discover install script"
COM_HELLOWORLD_PREFLIGHT_INSTALL_TEXT="HelloWorld preflight install script"
COM_HELLOWORLD_PREFLIGHT_UNINSTALL_TEXT="HelloWorld preflight uninstall script"
COM_HELLOWORLD_PREFLIGHT_UPDATE_TEXT="HelloWorld preflight update script"
COM_HELLOWORLD_UNINSTALL_TEXT="HelloWorld Uninstall script"
COM_HELLOWORLD_UPDATE_TEXT="HelloWorld Update script"
COM_HELLOWORLD_UPDHELLOWORLD_VIEW_DEFAULT_TITLE="Update the Greeting"
COM_HELLOWORLD_UPDHELLOWORLD_VIEW_DEFAULT_DESC="Update greeting here"
</source>
</span>

The ''_populateState'' method is, by default, automatically called when a state is read by the ''getState'' method.

== Packaging the component ==

Content of your code directory-
* ''[[#helloworld.xml|helloworld.xml]]''
* ''[[#script.php|script.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_02#site/helloworld.php|site/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_02#site/controller.php|site/controller.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/updhelloworld.php|site/updhelloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/controllers/updhelloworld.php|site/controllers/updhelloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/controllers/index.html|site/controllers/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/views/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/views/helloworld/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#site/views/helloworld/view.html.php|site/views/helloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/views/updhelloworld/view.html.php|site/views/updhelloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/views/helloworld/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/views/updhelloworld/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_06#site/views/helloworld/tmpl/default.xml|site/views/helloworld/tmpl/default.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#site/views/helloworld/tmpl/default.php|site/views/helloworld/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/views/updhelloworld/tmpl/default.xml|site/views/updhelloworld/tmpl/default.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/views/updhelloworld/tmpl/default.php|site/views/updhelloworld/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/models/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#site/models/helloworld.php|site/models/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/models/updhelloworld.php|site/models/updhelloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/models/forms/updhelloworld.xml|site/models/forms/updhelloworld.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/models/forms/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/language/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/language/en-GB/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_08#site/language/en-GB/en-GB.com_helloworld.ini|site/language/en-GB/en-GB.com_helloworld.ini]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/access.xml|admin/access.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/config.xml|admin/config.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/helloworld.php|admin/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_12#admin/controller.php|admin/controller.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/sql/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/sql/install.mysql.utf8.sql|admin/sql/install.mysql.utf8.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_06#admin/sql/uninstall.mysql.utf8.sql|admin/sql/uninstall.mysql.utf8.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/sql/updates/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/sql/updates/mysql/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#admin/sql/updates/mysql/0.0.1.sql|admin/sql/updates/mysql/0.0.1.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_06#admin/sql/install.mysql.utf8.sql|admin/sql/updates/mysql/0.0.6.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_12#admin/sql/updates/mysql/0.0.12.sql|admin/sql/updates/mysql/0.0.12.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/sql/updates/mysql/0.0.13.sql|admin/sql/updates/mysql/0.0.13.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/models/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/models/fields/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_12#admin/models/fields/helloworld.php|admin/models/fields/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/models/forms/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/models/forms/helloworld.xml|admin/models/forms/helloworld.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/models/forms/helloworld.js|admin/models/forms/helloworld.js]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/models/rules/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/models/rules/greeting.php|admin/models/rules/greeting.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/models/helloworld.php|admin/models/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_09#admin/models/helloworlds.php|admin/models/helloworlds.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/helloworlds/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/views/helloworlds/view.html.php|admin/views/helloworlds/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/helloworlds/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/views/helloworlds/tmpl/default.php|admin/views/helloworlds/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_07#admin/views/helloworlds/tmpl/default_head.php|admin/views/helloworlds/tmpl/default_head.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_07#admin/views/helloworlds/tmpl/default_body.php|admin/views/helloworlds/tmpl/default_body.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_07#admin/views/helloworlds/tmpl/default_foot.php|admin/views/helloworlds/tmpl/default_foot.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/helloworld/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/views/helloworld/view.html.php|admin/views/helloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/views/helloworld/submitbutton.js|admin/views/helloworld/submitbutton.js]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/helloworld/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/views/helloworld/tmpl/edit.php|admin/views/helloworld/tmpl/edit.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/helpers/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/helpers/helloworld.php|admin/helpers/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/tables/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/tables/helloworld.php|admin/tables/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/language/en-GB/en-GB.com_helloworld.ini|admin/language/en-GB/en-GB.com_helloworld.ini]]''
* ''[[#admin/language/en-GB/en-GB.com_helloworld.sys.ini|admin/language/en-GB/en-GB.com_helloworld.sys.ini]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/controllers/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/controllers/helloworld.php|admin/controllers/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/controllers/helloworlds.php|admin/controllers/helloworlds.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_08#language/en-GB/en-GB.ini|language/en-GB/en-GB.ini]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|media/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|media/images/index.html]]''
* ''media/images/tux-16x16.png''
* ''media/images/tux-48x48.png''

Create a compressed file of this directory or directly download the [http://joomlacode.org/gf/download/frsrelease/11394/58397/com_helloworld-1.6-part07.zip archive] and install it using the extension manager of Joomla. You can add a menu item of this component using the menu manager in the backend.

<span id="helloworld.xml">
''helloworld.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="2.5.0" method="upgrade">

<name>COM_HELLOWORLD</name>

<creationDate>November 2009</creationDate>
<author>John Doe</author>
<authorEmail>john.doe@example.org</authorEmail>
<authorUrl>http://www.example.org</authorUrl>
<copyright>Copyright Info</copyright>
<license>License Info</license>

<version>0.0.18</version>

<description>COM_HELLOWORLD_DESCRIPTION</description>


<scriptfile>script.php</scriptfile>

<install> 
<sql>
<file driver="mysql" charset="utf8">sql/install.mysql.utf8.sql</file>
</sql>
</install>
<uninstall> 
<sql>
<file driver="mysql" charset="utf8">sql/uninstall.mysql.utf8.sql</file>
</sql>
</uninstall>
<update> 
<schemas>
<schemapath type="mysql">sql/updates/mysql</schemapath>
</schemas>
</update>



<files folder="site">
<filename>index.html</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>
<filename>updhelloworld.php</filename>
<folder>views</folder>
<folder>models</folder>
<folder>controllers</folder>
<folder>language</folder>
</files>

<media destination="com_helloworld" folder="media">
<filename>index.html</filename>
<folder>images</folder>
</media>

<administration>

<menu img="../media/com_helloworld/images/tux-16x16.png">COM_HELLOWORLD_MENU</menu>


<files folder="admin">

<filename>index.html</filename>
<filename>config.xml</filename>
<filename>access.xml</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>

<folder>sql</folder>

<folder>tables</folder>

<folder>models</folder>

<folder>views</folder>

<folder>controllers</folder>

<folder>helpers</folder>
</files>

<languages folder="admin">
<language tag="en-GB">language/en-GB/en-GB.com_helloworld.ini</language>
<language tag="en-GB">language/en-GB/en-GB.com_helloworld.sys.ini</language>
</languages>
</administration>


<updateservers>

<server type="extension" priority="1" name="HelloWorld Update Site">http://yourdomain.com/update/helloworld-update.xml</server>
</updateservers>

</extension>

</source>
</span>

Now you can see in your component '''hello-world''' an array with two colums, two rows and checkboxes. You can click the checkboxes in order to select the different options you want.

== Zips ==
Download the zip file for this Part:
[http://www.glennarkell.com/joomlaorg/com_helloworld_0.0.18.zip]

== Navigate ==

[[Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Part 17|Prev: Adding an update server]]

== Contributors ==
*[[User:garkell|Glenn Arkell]]

[[Category:Development]]
[[category:Joomla! 1.6]]
[[category:Joomla! 1.7]]
[[category:Joomla! 2.5]]
[[category:Manual]]

Archived:Developing a MVC Component/Example of a frontend update function

2012-02-22T20:44:50Z

Garkell: /* Basic frontend form */

This tutorial is for {{JVer|1.6}} {{JVer|1.7}} {{JVer|2.5}}
== Warning - this article needs to be reviewed by someone who knows what they're doing ==

== Articles in this series ==
{{Chunk:Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Contents}}

== Introduction ==
This tutorial is part of the [[Developing a Model-View-Controller (MVC) Component for Joomla!2.5]] tutorial. You are encouraged to read the previous parts of the tutorial before reading this.

== Basic frontend form ==
Designing the frontend interface leads us to create a Model-View-Controller triptych similar to the backend in Part 7.

== Create the specific controller ==
The entry point now gets an instance of an ''UpdHelloWorld'' prefixed controller which extends the function of JControllerForm. Let's create a basic controllerform for the site part:

<span id="site/controllers/updhelloworld.php">
''site/controllers/updhelloworld.php''
<source lang="php">
<?php

// No direct access.
defined('_JEXEC') or die;

// Include dependancy of the main controllerform class
jimport('joomla.application.component.controllerform');

class HelloWorldControllerUpdHelloWorld extends JControllerForm
{

public function getModel($name = '', $prefix = '', $config = array('ignore_request' => true))
{
return parent::getModel($name, $prefix, array('ignore_request' => false));
}

public function submit()
{
// Check for request forgeries.
JRequest::checkToken() or jexit(JText::_('JINVALID_TOKEN'));

// Initialise variables.
$app = JFactory::getApplication();
$model = $this->getModel('updhelloworld');

// Get the data from the form POST
$data = JRequest::getVar('jform', array(), 'post', 'array');

// Now update the loaded data to the database via a function in the model
$upditem = $model->updItem($data);

// check if ok and display appropriate message. This can also have a redirect if desired.
if ($upditem) {
echo "<h2>Updated Greeting has been saved</h2>";
} else {
echo "<h2>Updated Greeting failed to be saved</h2>";
}

return true;
}

}
</source>
</span>

This controller will display the appropriate message after the form is submitted.

== Create the view ==

With your favorite file manager and editor, create a file ''site/views/updhelloworld/view.html.php'' containing:

<span id="site/views/updhelloworld/view.html.php">
''site/views/updhelloworld/view.html.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import Joomla view library
jimport('joomla.application.component.view');

/**
* HTML View class for the UpdHelloWorld Component
*/
class HelloWorldViewUpdHelloWorld extends JView
{
// Overwriting JView display method
function display($tpl = null)
{
$app = JFactory::getApplication();
$params = $app->getParams();
$dispatcher = JDispatcher::getInstance();

// Get some data from the models
$state = $this->get('State');
$item = $this->get('Item');
$this->form = $this->get('Form');

// Check for errors.
if (count($errors = $this->get('Errors')))
{
JError::raiseError(500, implode('<br />', $errors));
return false;
}
// Display the view
parent::display($tpl);
}
}
</source>
</span>

In Joomla, views display data using a layout. With your favorite file manager and editor, put a file ''site/views/updhelloworld/tmpl/default.php'' containing

<span id="site/views/updhelloworld/tmpl/default.php">
''site/views/updhelloworld/tmpl/default.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

JHtml::_('behavior.keepalive');
JHtml::_('behavior.formvalidation');
JHtml::_('behavior.tooltip');

?>
<h2>Update the Hello World greeting</h2>

<form class="form-validate" action="<?php echo JRoute::_('index.php'); ?>" method="post" id="updhelloworld" name="updhelloworld">
<fieldset>
<dl>
<dt><?php echo $this->form->getLabel('id'); ?></dt>
<dd><?php echo $this->form->getInput('id'); ?></dd>
<dt></dt><dd></dd>
<dt><?php echo $this->form->getLabel('greeting'); ?></dt>
<dd><?php echo $this->form->getInput('greeting'); ?></dd>
<dt></dt><dd></dd>
<dt></dt>
<dd><input type="hidden" name="option" value="com_helloworld" />
<input type="hidden" name="task" value="updhelloworld.submit" />
</dd>
<dt></dt>
<dd><button type="submit" class="button"><?php echo JText::_('Submit'); ?></button>
<?php echo JHtml::_('form.token'); ?>
</dd>
</dl>
<fieldset>
</form>
<div class="clr"></div>

</source>
</span>

This layout utilises the forms design which resides with the related model. The getLabel and getInput will pickup the xml fields defined and display appropriately. More on the xml file within the models section of this tutorial.

Create a file ''site/views/updhelloworld/tmpl/default.xml'' containing

<span id="site/views/updhelloworld/tmpl/default.xml">
''site/views/updhelloworld/tmpl/default.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<metadata>
<layout title="COM_HELLOWORLD_UPDHELLOWORLD_VIEW_DEFAULT_TITLE">
<message>COM_HELLOWORLD_UPDHELLOWORLD_VIEW_DEFAULT_DESC</message>
</layout>
</metadata>

</source>
</span>

This enables a menu option to be allocated to the frontend form.

== Create the model ==
The ''UpdHelloWorld'' model sets up the data through from the related form and allows the mechanism to save the subsequent data loaded into the form into the database.

<span id="site/models/updhelloworld.php">
''site/models/updhelloworld.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// Include dependancy of the main model form
jimport('joomla.application.component.modelform');
// import Joomla modelitem library
jimport('joomla.application.component.modelitem');
// Include dependancy of the dispatcher
jimport('joomla.event.dispatcher');

/**
* UpdHelloWorld Model
*/
class HelloWorldModelUpdHelloWorld extends JModelForm
{
/**
* @var object item
*/
protected $item;

/**
* Get the data for a new qualification
*/
public function getForm($data = array(), $loadData = true)
{

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

// Get the form.
$form = $this->loadForm('com_helloworld.updhelloworld', 'updhelloworld', array('control' => 'jform', 'load_data' => true));
if (empty($form)) {
return false;
}
return $form;

}

/**
* Get the message
* @return object The message to be displayed to the user
*/
function &getItem()
{

if (!isset($this->_item))
{
$cache = JFactory::getCache('com_helloworld', '');
$id = $this->getState('helloworld.id');
$this->_item = $cache->get($id);
if ($this->_item === false) {

}
}
return $this->_item;

}

public function updItem($data)
{
// set the variables from the passed data
$id = $data['id'];
$greeting = $data['greeting'];

// set the data into a query to update the record
$db = $this->getDbo();
$query = $db->getQuery(true);
$query->clear();
$query->update(' #__helloworld ');
$query->set(' greeting = '.$db->Quote($greeting) );
$query->where(' id = ' . (int) $id );

$db->setQuery((string)$query);

if (!$db->query()) {
JError::raiseError(500, $db->getErrorMsg());
return false;
} else {
return true;
}
}
}

</source>
</span>

The following file ''updhelloworld.xml'' should be created using your favourite editor and saved in the forms folder under the models directory. The first of the fields being referenced id using the sql type so that I returns the results from the query into a dropdown list form to be selected.
<span id="site/models/forms/updhelloworld.xml">
''site/models/forms/updhelloworld.xml''
<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<form name="updhelloworld">
<fieldset name="updhelloworld">

<field
name="id"
type="sql"
multiple="false"
size="1"
label="COM_HELLOWORLD_FORM_LBL_UPDHELLOWORLD_ID"
description="COM_HELLOWORLD_FORM_DESC_UPDHELLOWORLD_ID"
query="select id, greeting from #__helloworld"
key_field="id"
value_field="greeting"
default="0"
required="true"
>
<option value="">JOPTION_SELECT_ID</option>
</field>

<field
name="greeting"
type="text"
description="COM_HELLOWORLD_FORM_DESC_UPDHELLOWORLD_GREETING"
label="COM_HELLOWORLD_FORM_LBL_UPDHELLOWORLD_GREETING"
required="true"
size="50"
/>

</fieldset>
</form>

</source>
</span>

== Adding some language keys ==

This file provides the text link between the label in the model form definition to be displayed in the view. And being for the frontend, it resides in the site folder.

<span id="site/language/en-GB/en-GB.com_helloworld.ini">
''site/language/en-GB/en-GB.com_helloworld.ini''
<source lang="ini">
COM_HELLOWORLD_FORM_LBL_UPDHELLOWORLD_ID="Greeting ID"
COM_HELLOWORLD_FORM_DESC_UPDHELLOWORLD_ID="This is the ID of the Greeting record"
COM_HELLOWORLD_FORM_LBL_UPDHELLOWORLD_GREETING="Greeting"
COM_HELLOWORLD_FORM_DESC_UPDHELLOWORLD_GREETING="Greeting description"
JOPTION_SELECT_ID=" -- Select Greeting to Update -- "
</source>
</span>

Add the last 2 lines to the ''admin/language/en-GB/en-GB.com_helloworld.sys.ini'' file to provide the text link for the menu type display. And being for the backend, it resides in the admin language folder.

<span id="admin/language/en-GB/en-GB.com_helloworld.sys.ini">
''admin/language/en-GB/en-GB.com_helloworld.sys.ini''
<source lang="ini">
COM_HELLOWORLD="Hello World!"
COM_HELLOWORLD_DESCRIPTION="This is the Hello World description"
COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_DESC="This view displays a selected message"
COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_TITLE="Hello World"
COM_HELLOWORLD_INSTALL_TEXT="HelloWorld Install script"
COM_HELLOWORLD_MENU="Hello World!"
COM_HELLOWORLD_POSTFLIGHT_DISCOVER_INSTALL_TEXT="HelloWorld postlight discover install script"
COM_HELLOWORLD_POSTFLIGHT_INSTALL_TEXT="HelloWorld postflight install script"
COM_HELLOWORLD_POSTFLIGHT_UNINSTALL_TEXT="HelloWorld postflight uninstall script"
COM_HELLOWORLD_POSTFLIGHT_UPDATE_TEXT="HelloWorld postflight update script"
COM_HELLOWORLD_PREFLIGHT_DISCOVER_INSTALL_TEXT="HelloWorld preflight discover install script"
COM_HELLOWORLD_PREFLIGHT_INSTALL_TEXT="HelloWorld preflight install script"
COM_HELLOWORLD_PREFLIGHT_UNINSTALL_TEXT="HelloWorld preflight uninstall script"
COM_HELLOWORLD_PREFLIGHT_UPDATE_TEXT="HelloWorld preflight update script"
COM_HELLOWORLD_UNINSTALL_TEXT="HelloWorld Uninstall script"
COM_HELLOWORLD_UPDATE_TEXT="HelloWorld Update script"
COM_HELLOWORLD_UPDHELLOWORLD_VIEW_DEFAULT_TITLE="Update the Greeting"
COM_HELLOWORLD_UPDHELLOWORLD_VIEW_DEFAULT_DESC="Update greeting here"
</source>
</span>

The ''_populateState'' method is, by default, automatically called when a state is read by the ''getState'' method.

== Packaging the component ==

Content of your code directory-
* ''[[#helloworld.xml|helloworld.xml]]''
* ''[[#script.php|script.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_02#site/helloworld.php|site/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_02#site/controller.php|site/controller.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/updhelloworld.php|site/updhelloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/controllers/updhelloworld.php|site/controllers/updhelloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/controllers/index.html|site/controllers/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/views/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/views/helloworld/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#site/views/helloworld/view.html.php|site/views/helloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/views/updhelloworld/view.html.php|site/views/updhelloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/views/helloworld/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/views/updhelloworld/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_06#site/views/helloworld/tmpl/default.xml|site/views/helloworld/tmpl/default.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#site/views/helloworld/tmpl/default.php|site/views/helloworld/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/views/updhelloworld/tmpl/default.xml|site/views/updhelloworld/tmpl/default.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/views/updhelloworld/tmpl/default.php|site/views/updhelloworld/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/models/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#site/models/helloworld.php|site/models/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/models/updhelloworld.php|site/models/updhelloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/models/forms/updhelloworld.xml|site/models/forms/updhelloworld.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/models/forms/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/language/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/language/en-GB/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_08#site/language/en-GB/en-GB.com_helloworld.ini|site/language/en-GB/en-GB.com_helloworld.ini]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/access.xml|admin/access.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/config.xml|admin/config.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/helloworld.php|admin/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_12#admin/controller.php|admin/controller.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/sql/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/sql/install.mysql.utf8.sql|admin/sql/install.mysql.utf8.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_06#admin/sql/uninstall.mysql.utf8.sql|admin/sql/uninstall.mysql.utf8.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/sql/updates/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/sql/updates/mysql/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#admin/sql/updates/mysql/0.0.1.sql|admin/sql/updates/mysql/0.0.1.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_06#admin/sql/install.mysql.utf8.sql|admin/sql/updates/mysql/0.0.6.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_12#admin/sql/updates/mysql/0.0.12.sql|admin/sql/updates/mysql/0.0.12.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/sql/updates/mysql/0.0.13.sql|admin/sql/updates/mysql/0.0.13.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/models/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/models/fields/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_12#admin/models/fields/helloworld.php|admin/models/fields/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/models/forms/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/models/forms/helloworld.xml|admin/models/forms/helloworld.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/models/forms/helloworld.js|admin/models/forms/helloworld.js]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/models/rules/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/models/rules/greeting.php|admin/models/rules/greeting.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/models/helloworld.php|admin/models/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_09#admin/models/helloworlds.php|admin/models/helloworlds.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/helloworlds/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/views/helloworlds/view.html.php|admin/views/helloworlds/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/helloworlds/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/views/helloworlds/tmpl/default.php|admin/views/helloworlds/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_07#admin/views/helloworlds/tmpl/default_head.php|admin/views/helloworlds/tmpl/default_head.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_07#admin/views/helloworlds/tmpl/default_body.php|admin/views/helloworlds/tmpl/default_body.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_07#admin/views/helloworlds/tmpl/default_foot.php|admin/views/helloworlds/tmpl/default_foot.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/helloworld/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/views/helloworld/view.html.php|admin/views/helloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/views/helloworld/submitbutton.js|admin/views/helloworld/submitbutton.js]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/helloworld/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/views/helloworld/tmpl/edit.php|admin/views/helloworld/tmpl/edit.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/helpers/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/helpers/helloworld.php|admin/helpers/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/tables/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/tables/helloworld.php|admin/tables/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/language/en-GB/en-GB.com_helloworld.ini|admin/language/en-GB/en-GB.com_helloworld.ini]]''
* ''[[#admin/language/en-GB/en-GB.com_helloworld.sys.ini|admin/language/en-GB/en-GB.com_helloworld.sys.ini]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/controllers/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/controllers/helloworld.php|admin/controllers/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/controllers/helloworlds.php|admin/controllers/helloworlds.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_08#language/en-GB/en-GB.ini|language/en-GB/en-GB.ini]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|media/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|media/images/index.html]]''
* ''media/images/tux-16x16.png''
* ''media/images/tux-48x48.png''

Create a compressed file of this directory or directly download the [http://joomlacode.org/gf/download/frsrelease/11394/58397/com_helloworld-1.6-part07.zip archive] and install it using the extension manager of Joomla. You can add a menu item of this component using the menu manager in the backend.

<span id="helloworld.xml">
''helloworld.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="2.5.0" method="upgrade">

<name>COM_HELLOWORLD</name>

<creationDate>November 2009</creationDate>
<author>John Doe</author>
<authorEmail>john.doe@example.org</authorEmail>
<authorUrl>http://www.example.org</authorUrl>
<copyright>Copyright Info</copyright>
<license>License Info</license>

<version>0.0.18</version>

<description>COM_HELLOWORLD_DESCRIPTION</description>


<scriptfile>script.php</scriptfile>

<install> 
<sql>
<file driver="mysql" charset="utf8">sql/install.mysql.utf8.sql</file>
</sql>
</install>
<uninstall> 
<sql>
<file driver="mysql" charset="utf8">sql/uninstall.mysql.utf8.sql</file>
</sql>
</uninstall>
<update> 
<schemas>
<schemapath type="mysql">sql/updates/mysql</schemapath>
</schemas>
</update>



<files folder="site">
<filename>index.html</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>
<filename>updhelloworld.php</filename>
<folder>views</folder>
<folder>models</folder>
<folder>controllers</folder>
<folder>language</folder>
</files>

<media destination="com_helloworld" folder="media">
<filename>index.html</filename>
<folder>images</folder>
</media>

<administration>

<menu img="../media/com_helloworld/images/tux-16x16.png">COM_HELLOWORLD_MENU</menu>


<files folder="admin">

<filename>index.html</filename>
<filename>config.xml</filename>
<filename>access.xml</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>

<folder>sql</folder>

<folder>tables</folder>

<folder>models</folder>

<folder>views</folder>

<folder>controllers</folder>

<folder>helpers</folder>
</files>

<languages folder="admin">
<language tag="en-GB">language/en-GB/en-GB.com_helloworld.ini</language>
<language tag="en-GB">language/en-GB/en-GB.com_helloworld.sys.ini</language>
</languages>
</administration>


<updateservers>

<server type="extension" priority="1" name="HelloWorld Update Site">http://yourdomain.com/update/helloworld-update.xml</server>
</updateservers>

</extension>

</source>
</span>

Now you can see in your component '''hello-world''' an array with two colums, two rows and checkboxes. You can click the checkboxes in order to select the different options you want.

== Zips ==
Download the zip file for this Part:
[http://www.glennarkell.com/joomlaorg/com_helloworld_0.0.18.zip]

== Navigate ==

[[Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Part 17|Prev: Adding an update server]]

== Contributors ==
*[[User:garkell|Glenn Arkell]]

[[Category:Development]]
[[category:Joomla! 1.6]]
[[category:Joomla! 1.7]]
[[category:Joomla! 2.5]]
[[category:Manual]]

Archived talk:Developing a MVC Component/Example of a frontend update function

2012-02-22T20:42:04Z

Garkell:

This section of the tutorial seems to say that to add an "update" view to the helloworld component a new entry point file must be created with the same name as the view ("updhelloworld.php" in that example). I think this is wrong because:
1) I can delete this file and the example component still works
2) None of the other components have this structure (eg com_users just
has a switch in the main controller's display to select different
displays based on view name)
3) A "die()" in that file never gets executed.

Note that "helloworld.php" (without the "upd" prefix) was created as the entry point back in part 2.

:-Dave

:: I can't see why there is dispatcher in the model and another import of it in the controller. [[User:Oc666|oc666]] 00:49, 14 February 2012 (CST)

Hi Dave,
You are correct. Since your comment I created my second small component and followed your suggestion and all is working as expected so I agree and will update. Cheers.

Glenn

Archived:Developing a MVC Component/Example of a frontend update function

2011-12-15T04:19:19Z

Garkell: An example of frontend form - my first go so be nice but change whatever is wrong

This tutorial is for {{JVer|1.7}}
== Warning - this article needs to be reviewed by someone who knows what they're doing ==

== Articles in this series ==
{{Chunk:Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Contents}}

== Introduction ==
This tutorial is part of the [[Developing a Model-View-Controller (MVC) Component for Joomla!1.6]] tutorial. You are encouraged to read the previous parts of the tutorial before reading this.

== Basic frontend form ==
Designing the frontend interface leads us to create a Model-View-Controller triptych similar to the backend in Part 7. We have to create an entry point of our component, the ''site/updhelloworld.php'' file.

<span id="site/updhelloworld.php">
''site/updhelloworld.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import joomla controller library
jimport('joomla.application.component.controller');

// Get an instance of the controller prefixed by UpdHelloWorld
$controller = JController::getInstance('UpdHelloWorld');

// Perform the Request task
$controller->execute(JRequest::getCmd('task'));

// Redirect if set by the controller
$controller->redirect();
</source>
</span>

== Create the specific controller ==
The entry point now gets an instance of an ''UpdHelloWorld'' prefixed controller which extends the function of JControllerForm. Let's create a basic controllerform for the site part:

<span id="site/controllers/updhelloworld.php">
''site/controllers/updhelloworld.php''
<source lang="php">
<?php

// No direct access.
defined('_JEXEC') or die;

// Include dependancy of the main controllerform class
jimport('joomla.application.component.controllerform');

class HelloWorldControllerUpdHelloWorld extends JControllerForm
{

public function getModel($name = '', $prefix = '', $config = array('ignore_request' => true))
{
return parent::getModel($name, $prefix, array('ignore_request' => false));
}

public function submit()
{
// Check for request forgeries.
JRequest::checkToken() or jexit(JText::_('JINVALID_TOKEN'));

// Initialise variables.
$app = JFactory::getApplication();
$model = $this->getModel('updhelloworld');

// Get the data from the form POST
$data = JRequest::getVar('jform', array(), 'post', 'array');

// Now update the loaded data to the database via a function in the model
$upditem = $model->updItem($data);

// check if ok and display appropriate message. This can also have a redirect if desired.
if ($upditem) {
echo "<h2>Updated Greeting has been saved</h2>";
} else {
echo "<h2>Updated Greeting failed to be saved</h2>";
}

return true;
}

}
</source>
</span>

This controller will display the appropriate message after the form is submitted.

== Create the view ==

With your favorite file manager and editor, create a file ''site/views/updhelloworld/view.html.php'' containing:

<span id="site/views/updhelloworld/view.html.php">
''site/views/updhelloworld/view.html.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import Joomla view library
jimport('joomla.application.component.view');

/**
* HTML View class for the UpdHelloWorld Component
*/
class HelloWorldViewUpdHelloWorld extends JView
{
// Overwriting JView display method
function display($tpl = null)
{
$app = JFactory::getApplication();
$params = $app->getParams();
$dispatcher = JDispatcher::getInstance();

// Get some data from the models
$state = $this->get('State');
$item = $this->get('Item');
$this->form = $this->get('Form');

// Check for errors.
if (count($errors = $this->get('Errors')))
{
JError::raiseError(500, implode('<br />', $errors));
return false;
}
// Display the view
parent::display($tpl);
}
}
</source>
</span>

In Joomla, views display data using a layout. With your favorite file manager and editor, put a file ''site/views/updhelloworld/tmpl/default.php'' containing

<span id="site/views/updhelloworld/tmpl/default.php">
''site/views/updhelloworld/tmpl/default.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

JHtml::_('behavior.keepalive');
JHtml::_('behavior.formvalidation');
JHtml::_('behavior.tooltip');

?>
<h2>Update the Hello World greeting</h2>

<form class="form-validate" action="<?php echo JRoute::_('index.php'); ?>" method="post" id="updhelloworld" name="updhelloworld">
<fieldset>
<dl>
<dt><?php echo $this->form->getLabel('id'); ?></dt>
<dd><?php echo $this->form->getInput('id'); ?></dd>
<dt></dt><dd></dd>
<dt><?php echo $this->form->getLabel('greeting'); ?></dt>
<dd><?php echo $this->form->getInput('greeting'); ?></dd>
<dt></dt><dd></dd>
<dt></dt>
<dd><input type="hidden" name="option" value="com_helloworld" />
<input type="hidden" name="task" value="updhelloworld.submit" />
</dd>
<dt></dt>
<dd><button type="submit" class="button"><?php echo JText::_('Submit'); ?></button>
<?php echo JHtml::_('form.token'); ?>
</dd>
</dl>
<fieldset>
</form>
<div class="clr"></div>

</source>
</span>

This layout utilises the forms design which resides with the related model. The getLabel and getInput will pickup the xml fields defined and display appropriately. More on the xml file within the models section of this tutorial.

Create a file ''site/views/updhelloworld/tmpl/default.xml'' containing

<span id="site/views/updhelloworld/tmpl/default.xml">
''site/views/updhelloworld/tmpl/default.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<metadata>
<layout title="COM_HELLOWORLD_UPDHELLOWORLD_VIEW_DEFAULT_TITLE">
<message>COM_HELLOWORLD_UPDHELLOWORLD_VIEW_DEFAULT_DESC</message>
</layout>
</metadata>

</source>
</span>

This enables a menu option to be allocated to the frontend form.

== Create the model ==
The ''UpdHelloWorld'' model sets up the data through from the related form and allows the mechanism to save the subsequent data loaded into the form into the database.

<span id="site/models/updhelloworld.php">
''site/models/updhelloworld.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// Include dependancy of the main model form
jimport('joomla.application.component.modelform');
// import Joomla modelitem library
jimport('joomla.application.component.modelitem');
// Include dependancy of the dispatcher
jimport('joomla.event.dispatcher');

/**
* UpdHelloWorld Model
*/
class HelloWorldModelUpdHelloWorld extends JModelForm
{
/**
* @var object item
*/
protected $item;

/**
* Get the data for a new qualification
*/
public function getForm($data = array(), $loadData = true)
{

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

// Get the form.
$form = $this->loadForm('com_helloworld.updhelloworld', 'updhelloworld', array('control' => 'jform', 'load_data' => true));
if (empty($form)) {
return false;
}
return $form;

}

/**
* Get the message
* @return object The message to be displayed to the user
*/
function &getItem()
{

if (!isset($this->_item))
{
$cache = JFactory::getCache('com_helloworld', '');
$id = $this->getState('helloworld.id');
$this->_item = $cache->get($id);
if ($this->_item === false) {

}
}
return $this->_item;

}

public function updItem($data)
{
// set the variables from the passed data
$id = $data['id'];
$greeting = $data['greeting'];

// set the data into a query to update the record
$db = $this->getDbo();
$query = $db->getQuery(true);
$query->clear();
$query->update(' #__helloworld ');
$query->set(' greeting = '.$db->Quote($greeting) );
$query->where(' id = ' . (int) $id );

$db->setQuery((string)$query);

if (!$db->query()) {
JError::raiseError(500, $db->getErrorMsg());
return false;
} else {
return true;
}
}
}

</source>
</span>

The following file ''updhelloworld.xml'' should be created using your favourite editor and saved in the forms folder under the models directory. The first of the fields being referenced id using the sql type so that I returns the results from the query into a dropdown list form to be selected.
<span id="site/models/forms/updhelloworld.xml">
''site/models/forms/updhelloworld.xml''
<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<form name="updhelloworld">
<fieldset name="updhelloworld">

<field
name="id"
type="sql"
multiple="false"
size="1"
label="COM_HELLOWORLD_FORM_LBL_UPDHELLOWORLD_ID"
description="COM_HELLOWORLD_FORM_DESC_UPDHELLOWORLD_ID"
query="select id, greeting from #__helloworld"
key_field="id"
value_field="greeting"
default="0"
required="true"
>
<option value="">JOPTION_SELECT_ID</option>
</field>

<field
name="greeting"
type="text"
description="COM_HELLOWORLD_FORM_DESC_UPDHELLOWORLD_GREETING"
label="COM_HELLOWORLD_FORM_LBL_UPDHELLOWORLD_GREETING"
required="true"
size="50"
/>

</fieldset>
</form>

</source>
</span>

== Adding some language keys ==

This file provides the text link between the label in the model form definition to be displayed in the view. And being for the frontend, it resides in the site folder.

<span id="site/language/en-GB/en-GB.com_helloworld.ini">
''site/language/en-GB/en-GB.com_helloworld.ini''
<source lang="ini">
COM_HELLOWORLD_FORM_LBL_UPDHELLOWORLD_ID="Greeting ID"
COM_HELLOWORLD_FORM_DESC_UPDHELLOWORLD_ID="This is the ID of the Greeting record"
COM_HELLOWORLD_FORM_LBL_UPDHELLOWORLD_GREETING="Greeting"
COM_HELLOWORLD_FORM_DESC_UPDHELLOWORLD_GREETING="Greeting description"
JOPTION_SELECT_ID=" -- Select Greeting to Update -- "
</source>
</span>

Add the last 2 lines to the ''admin/language/en-GB/en-GB.com_helloworld.sys.ini'' file to provide the text link for the menu type display. And being for the backend, it resides in the admin language folder.

<span id="admin/language/en-GB/en-GB.com_helloworld.sys.ini">
''admin/language/en-GB/en-GB.com_helloworld.sys.ini''
<source lang="ini">
COM_HELLOWORLD="Hello World!"
COM_HELLOWORLD_DESCRIPTION="This is the Hello World description"
COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_DESC="This view displays a selected message"
COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_TITLE="Hello World"
COM_HELLOWORLD_INSTALL_TEXT="HelloWorld Install script"
COM_HELLOWORLD_MENU="Hello World!"
COM_HELLOWORLD_POSTFLIGHT_DISCOVER_INSTALL_TEXT="HelloWorld postlight discover install script"
COM_HELLOWORLD_POSTFLIGHT_INSTALL_TEXT="HelloWorld postflight install script"
COM_HELLOWORLD_POSTFLIGHT_UNINSTALL_TEXT="HelloWorld postflight uninstall script"
COM_HELLOWORLD_POSTFLIGHT_UPDATE_TEXT="HelloWorld postflight update script"
COM_HELLOWORLD_PREFLIGHT_DISCOVER_INSTALL_TEXT="HelloWorld preflight discover install script"
COM_HELLOWORLD_PREFLIGHT_INSTALL_TEXT="HelloWorld preflight install script"
COM_HELLOWORLD_PREFLIGHT_UNINSTALL_TEXT="HelloWorld preflight uninstall script"
COM_HELLOWORLD_PREFLIGHT_UPDATE_TEXT="HelloWorld preflight update script"
COM_HELLOWORLD_UNINSTALL_TEXT="HelloWorld Uninstall script"
COM_HELLOWORLD_UPDATE_TEXT="HelloWorld Update script"
COM_HELLOWORLD_UPDHELLOWORLD_VIEW_DEFAULT_TITLE="Update the Greeting"
COM_HELLOWORLD_UPDHELLOWORLD_VIEW_DEFAULT_DESC="Update greeting here"
</source>
</span>

The ''_populateState'' method is, by default, automatically called when a state is read by the ''getState'' method.

== Packaging the component ==

Content of your code directory
* ''[[#helloworld.xml|helloworld.xml]]''
* ''[[#script.php|script.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_02#site/helloworld.php|site/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_02#site/controller.php|site/controller.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_18#site/updhelloworld.php|site/updhelloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_18#site/controllers/updhelloworld.php|site/controllers/updhelloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_18#site/controllers/index.html|site/controllers/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/views/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/views/helloworld/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_13#site/views/helloworld/view.html.php|site/views/helloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_18#site/views/updhelloworld/view.html.php|site/views/updhelloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/views/helloworld/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/views/updhelloworld/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_06#site/views/helloworld/tmpl/default.xml|site/views/helloworld/tmpl/default.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_13#site/views/helloworld/tmpl/default.php|site/views/helloworld/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_18#site/views/updhelloworld/tmpl/default.xml|site/views/updhelloworld/tmpl/default.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_18#site/views/updhelloworld/tmpl/default.php|site/views/updhelloworld/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/models/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_13#site/models/helloworld.php|site/models/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_18#site/models/updhelloworld.php|site/models/updhelloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_18#site/models/forms/updhelloworld.xml|site/models/forms/updhelloworld.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/models/forms/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/language/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|site/language/en-GB/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_08#site/language/en-GB/en-GB.com_helloworld.ini|site/language/en-GB/en-GB.com_helloworld.ini]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_14#admin/access.xml|admin/access.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_14#admin/config.xml|admin/config.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_14#admin/helloworld.php|admin/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_12#admin/controller.php|admin/controller.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/sql/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_13#admin/sql/install.mysql.utf8.sql|admin/sql/install.mysql.utf8.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_06#admin/sql/uninstall.mysql.utf8.sql|admin/sql/uninstall.mysql.utf8.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/sql/updates/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/sql/updates/mysql/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#admin/sql/updates/mysql/0.0.1.sql|admin/sql/updates/mysql/0.0.1.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_06#admin/sql/install.mysql.utf8.sql|admin/sql/updates/mysql/0.0.6.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_12#admin/sql/updates/mysql/0.0.12.sql|admin/sql/updates/mysql/0.0.12.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_13#admin/sql/updates/mysql/0.0.13.sql|admin/sql/updates/mysql/0.0.13.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/models/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/models/fields/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_12#admin/models/fields/helloworld.php|admin/models/fields/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/models/forms/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_13#admin/models/forms/helloworld.xml|admin/models/forms/helloworld.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_11#admin/models/forms/helloworld.js|admin/models/forms/helloworld.js]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/models/rules/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_11#admin/models/rules/greeting.php|admin/models/rules/greeting.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_14#admin/models/helloworld.php|admin/models/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_09#admin/models/helloworlds.php|admin/models/helloworlds.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/views/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/views/helloworlds/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_14#admin/views/helloworlds/view.html.php|admin/views/helloworlds/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/views/helloworlds/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_11#admin/views/helloworlds/tmpl/default.php|admin/views/helloworlds/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_07#admin/views/helloworlds/tmpl/default_head.php|admin/views/helloworlds/tmpl/default_head.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_07#admin/views/helloworlds/tmpl/default_body.php|admin/views/helloworlds/tmpl/default_body.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_07#admin/views/helloworlds/tmpl/default_foot.php|admin/views/helloworlds/tmpl/default_foot.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/views/helloworld/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_14#admin/views/helloworld/view.html.php|admin/views/helloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_11#admin/views/helloworld/submitbutton.js|admin/views/helloworld/submitbutton.js]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/views/helloworld/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_13#admin/views/helloworld/tmpl/edit.php|admin/views/helloworld/tmpl/edit.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/helpers/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_14#admin/helpers/helloworld.php|admin/helpers/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/tables/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_14#admin/tables/helloworld.php|admin/tables/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_13#admin/language/en-GB/en-GB.com_helloworld.ini|admin/language/en-GB/en-GB.com_helloworld.ini]]''
* ''[[#admin/language/en-GB/en-GB.com_helloworld.sys.ini|admin/language/en-GB/en-GB.com_helloworld.sys.ini]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|admin/controllers/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_11#admin/controllers/helloworld.php|admin/controllers/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_11#admin/controllers/helloworlds.php|admin/controllers/helloworlds.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_08#language/en-GB/en-GB.ini|language/en-GB/en-GB.ini]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|media/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!1.6_-_Part_01#index.html|media/images/index.html]]''
* ''media/images/tux-16x16.png''
* ''media/images/tux-48x48.png''

Create a compressed file of this directory or directly download the [http://joomlacode.org/gf/download/frsrelease/11394/58397/com_helloworld-1.6-part07.zip archive] and install it using the extension manager of Joomla!1.6. You can add a menu item of this component using the menu manager in the backend.

<span id="helloworld.xml">
''helloworld.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="1.6.0" method="upgrade">

<name>COM_HELLOWORLD</name>

<creationDate>November 2009</creationDate>
<author>John Doe</author>
<authorEmail>john.doe@example.org</authorEmail>
<authorUrl>http://www.example.org</authorUrl>
<copyright>Copyright Info</copyright>
<license>License Info</license>

<version>0.0.18</version>

<description>COM_HELLOWORLD_DESCRIPTION</description>


<scriptfile>script.php</scriptfile>

<install> 
<sql>
<file driver="mysql" charset="utf8">sql/install.mysql.utf8.sql</file>
</sql>
</install>
<uninstall> 
<sql>
<file driver="mysql" charset="utf8">sql/uninstall.mysql.utf8.sql</file>
</sql>
</uninstall>
<update> 
<schemas>
<schemapath type="mysql">sql/updates/mysql</schemapath>
</schemas>
</update>



<files folder="site">
<filename>index.html</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>
<filename>updhelloworld.php</filename>
<folder>views</folder>
<folder>models</folder>
<folder>controllers</folder>
<folder>language</folder>
</files>

<media destination="com_helloworld" folder="media">
<filename>index.html</filename>
<folder>images</folder>
</media>

<administration>

<menu img="../media/com_helloworld/images/tux-16x16.png">COM_HELLOWORLD_MENU</menu>


<files folder="admin">

<filename>index.html</filename>
<filename>config.xml</filename>
<filename>access.xml</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>

<folder>sql</folder>

<folder>tables</folder>

<folder>models</folder>

<folder>views</folder>

<folder>controllers</folder>

<folder>helpers</folder>
</files>

<languages folder="admin">
<language tag="en-GB">language/en-GB/en-GB.com_helloworld.ini</language>
<language tag="en-GB">language/en-GB/en-GB.com_helloworld.sys.ini</language>
</languages>
</administration>


<updateservers>

<server type="extension" priority="1" name="HelloWorld Update Site">http://yourdomain.com/update/helloworld-update.xml</server>
</updateservers>

</extension>

</source>
</span>

Now you can see in your component '''hello-world''' an array with two colums, two rows and checkboxes. You can click the checkboxes in order to select the different options you want.

== Zips ==
Download the zip file for this Part:
[http://www.glennarkell.com/joomlaorg/com_helloworld_0.0.18.zip]

== Navigate ==

[[Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Part 17|Prev: Adding an update server]]

== Contributors ==
*[[User:garkell|Glenn Arkell]]

[[Category:Development]]
[[category:Joomla! 1.7]]
[[category:Manual]]

Chunk:Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Contents

2011-12-15T04:15:11Z

Garkell: Added Part 18 - example of front end form

* [[Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Part 01|Developing a Basic Component]]
* [[Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Part 02|Adding a view to the site part]]
* [[Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Part 03|Adding a menu type to the site part]]
* [[Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Part 04|Adding a model to the site part]]
* [[Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Part 05|Adding a variable request in the menu type]]
* [[Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Part 06|Using the database]]
* [[Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Part 07|Basic backend]]
* [[Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Part 08|Adding language management]]
* [[Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Part 09|Adding backend actions]]
* [[Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Part 10|Adding decorations to the backend]]
* [[Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Part 11|Adding verifications]]
* [[Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Part 12|Adding categories]]
* [[Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Part 13|Adding configuration]]
* [[Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Part 14|Adding ACL]]
* [[Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Part 15|Adding an install/uninstall/update script file]]
* [[Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Part 16|Using the language filter facility]]
* [[Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Part 17|Adding an update server]]
* [[Developing a Model-View-Controller (MVC) Component for Joomla!1.6 - Part 18|Example of a Frontend Update Function]]

J1.5:Using the JTable class

2011-12-10T23:18:47Z

Garkell: Added comment about version of Joomla this is related to.

This tutorial is for {{JVer|1.5}} In Joomla! 1.5.

[[Category:Development]]
== Writing an extension of JTable ==

The [[JTable]] class is an implementation of the [http://en.wikipedia.org/wiki/Active_record_pattern Active Record] design pattern. It is used throughout Joomla! for [http://en.wikipedia.org/wiki/Create,_read,_update_and_delete creating, reading, updating, and deleting] records in the database table.

To use JTable, create an extension of the class. In this example, we have a database table containing recipes.

<pre>
<?php

defined('_JEXEC') or die();

class TableRecipes extends JTable
{
var $id = null;
var $ingredients = null;
var $instructions = null;
var $serves = null;
var $difficulty = null;
var $prep_time = null;
var $cook_time = null;
var $published = 0;

function __construct(&$db)
{
parent::__construct( '#__recipes', 'id', $db );
}
}
</pre>

When naming your class extension, the convention is to prefix it with 'Table', then follow with a [http://en.wikipedia.org/wiki/CamelCase CamelCased] version of the table's name. All of the member variables of your class should match the column names in the database. The default values should be valid according to the table schema For instance, if you have columns that are NOT NULL, you must use a value other than 'null' as the default.

Finally, create a constructor for the class that accepts a reference to the current database instance. This will call the parent constructor which needs the name of the table, the name of the primary key column, and the database instance. The name of the table uses #__ instead of jos_, as the administrator can pick any table prefix desired during Joomla! installation.

If you were using this class as a part of a component called 'Recipes', you would place this code in the file /administrator/components/com_recipes/tables/recipes.php.

== Using a JTable class extension ==

Once the table class is in place, you can use it in any Joomla! extension. To include the file, place this line in your extension's source code (use com_nameofyourcomponent in place of com_recipes):

<pre>
JTable::addIncludePath(JPATH_ADMINISTRATOR.DS.'components'.DS.'com_recipes'.DS.'tables');
</pre>

To get an instance of the object, use this code:

<pre>
$row =& JTable::getInstance('recipes', 'Table');
</pre>

Notice that the lowercase version of the suffix of your class name is used as the first parameter, with the prefix 'Table' as the second. Also, the getInstance() member function of JTable returns the object by reference instead of value; use =& to enforce this.

In a model class (extends JModel) you can also use:

<pre>
$row =& $this->getTable('recipes');
</pre>

Notice that if you have not used the standard naming convention, you can supply the class prefix as the optional second parameter.

=== Checkout/Checkin ===
Common scenario is when multiple users are editing identical item (e.g article, category, user and etc) simultaneously, which in turn, may results in arbitrary data when saved by the users (depends on who last saved the item). Joomla! solves such cases of unknown modification ownership using Checkouts and Checkins in order to provide access only to one user at a time. For example, if one user began editing an article, then it is said that the article was '''checked out''' by the user, when finished working with the article (usually by closing it using a button), the article is '''checked in''' by the user. At the time the user was editing the article, no other user could edit the same article, unless manually specified by a user with the right permissions. You can find further explanation [http://help.joomla.org/content/view/202/153/ here].
The following examples demonstrate how Checkout/Checkin may be implemented.

'''Checkout'''
<pre>
// retrieve item identifier from request
$itemId = JRequest::getInt('itemId');
// the user to test checkout with, could be any other user you want
$user = JFactory::getUser();

// load the item's data so we'll know with what item were dealing with
if (!$row->load($itemId)) {
return JError::raiseWarning( 500, $row->getError() );
}

// check out the item
if ($row->checkout($user->id)) {
echo 'Item was checked out by the user.';
} else {
return JError::raiseWarning( 500, $row->getError() );
}
</pre>
'''checkout()''' will signal the item was checked out by the user whom ID we provided as an argument to the method.

'''Checkin'''
<pre>
// retrieve item identifier from request
$itemId = JRequest::getInt('itemId');
// the user to test checkout with, could be any other user you want
$user = JFactory::getUser();

// load the item's data so we'll know with what item were dealing with
if (!$row->load($itemId)) {
return JError::raiseWarning( 500, $row->getError() );
}

// check if the item was checked out, and if it does - whether or not it was checked out by the user
if($row->isCheckedOut($user->id)) {
// check in the item
if ($row->checkin()) {
echo 'The item was checked in, and can now be edited by other users.';
} else {
return JError::raiseWarning( 500, $row->getError() );
}
}
</pre>
We use '''isCheckedOut()''' to find out whether the item was checked out, it returns TRUE in the following cases:
<ul>
<li>Item is empty (i.e no data was loaded to the item).</li>
<li>The item does not support checkout, which can be as a result of database design.</li>
<li>The supplied user ID does not match the ID of the user who checked out the item, meaning the item is probably being edited by another user already, or the user who last checked out the item did not properly checked in the item. '''This is probably the most common scenario''' when dealing with items in the backend.</li>
</ul>
'''isCheckedOut()''' returns FALSE in the following cases:
<ul>
<li>The item was not checked out by any user.</li>
<li>The item was checked out, but by the same user who checked it out (i.e the user with the ID we passed to isCheckedOut()).
</ul>

'''checkin()''' will purge any checkout state that was applied to the item.

=== Create/Update ===
In a typical situation, you will have an HTML form submitted by the user which will PHP will interpret for you as an associative array. The JRequest class in Joomla! has functions ready to assist with retrieving this data safely. Use JRequest::get('post') to retrieve all of the elements in the HTTP POST request as a sanitized array.

Once you have this array, you can pass it into the bind() method of JTable. Doing this will match the associated items of the array with member variables of the class. In the following example, the array is retrieved from JRequest::get('post') and immediately passed into bind().

<pre>
if (!$row->bind( JRequest::get( 'post' ) )) {
return JError::raiseWarning( 500, $row->getError() );
}
</pre>

If bind() fails, you want to stop the application and explain the failure before your extension attempts to send the data. The raiseWarning() function of JError allows you to stop Joomla!, while the getError() function returns the error message stored in the JTable object.

When binding succeeds and your object is ready, call the store() function. Again, if something goes wrong, stop the application and explain why.

<pre>
if (!$row->store()) {
JError::raiseError(500, $row->getError() );
}
</pre>

Notes:
* If any member variables of your JTable object are null when store() is called, they are ignored by default. This allows you to update specific columns of your table, while leaving the others untouched. If you wish to override this behavior to ensure that all columns have a value, pass true into store().
* The JTable::bind() and JRequest::get() functions do not enforce data types. If you need a column to be a specific type (for instance, integer), you need to add this logic to your code before calling store().

=== Read ===
To load a specific row of the database with JTable, pass the key into the load() member function.

<pre>
$row->load( $id );
</pre>

This relies on the key column you specified in the second parameter of parent::__construct() when you extended JTable.

=== Delete ===
Like read(), delete() allows you to destroy a specific row in the table based on the key specified earlier.

<pre>
$row->delete( $id );
</pre>

If you want to delete multiple rows at once, you will need to write the query manually.

== Member Functions ==
{{jfr summary|class=JTable|methods=yes}}

== Summary ==
When properly extended, JTable gives you all of the basic functions you need for managing and retrieving records in a database table. Member functions take care of the rest when you add member variables, the table name, and the key column.