Joomla! Documentation - User contributions [en]

Manifest files

2015-09-24T20:49:34Z

Mvangeest: Added information about the plugin attribute

<noinclude><languages /></noinclude>
<noinclude>{{page|needs updating|}}</noinclude>
<noinclude>
{{Joomla version|version=3.x}} {{Joomla version|version=2.5|status=eos}}
</noinclude>
<translate>
Within Joomla there are manifest files for all of the extensions. These files include the general installation information as well as parameters for the configuration of the [[S:MyLanguage/extension|extension]] itself. Since Joomla! 2.5, there are very few differences between the manifest file formats for the different [[S:MyLanguage/Extension types (technical definitions)|types of extensions]], allowing each type to access the full power of the Joomla! installer.</translate>

<translate>==Naming conventions== 
The file must be named <tt>manifest.xml</tt> or <tt><extension_name>.xml</tt> and located in the root directory of the installation package.</translate>

<translate>==Syntax== </translate>

<translate>=== Root element === 
The primary tag of the installation file is:</translate>
<source lang=xml><extension></extension></source>

<translate>
This starting and closing tags are now valid for all extensions. The new tag <code><extension></code> replaces the old <code><install></install></code> from Joomla {{JVer|1.5}}. The following attributes are allowed within the tag:</translate>

{|class="wikitable"
|-
! style="width: 150px" | <translate>
Attribute</translate> || style="width: 150px" | <translate>
Values</translate> || <translate>
Applicable to</translate> || <translate>
Description</translate>
|-
| type || <code>component</code><br /><code>file</code><br /><code>language</code><br /><code>library</code><br /><code>module</code><br /><code>package</code><br /><code>plugin</code><br /><code>template</code> || <translate>
All extensions</translate>
| <translate>
This attribute describes the type of the extension for the installer. Based on this type further requirements to sub-tags apply.</translate>
|-
| version
| <code>2.5</code><br /><code>3.0</code> || <translate>
All extensions</translate>
| <translate>
String that identifies the version of Joomla for which this extension is developed.</translate>
|-
| method
| <code>install</code><br /><code>upgrade</code> || <translate>
All extensions</translate>
| <translate>
The default value <code>install</code> will be also used if the method attribute is not used. The <code>install</code> value means the installer will gracefully stop if it finds any existing file/folder of the new extension.</translate>
|-
| client
| <code>site</code><br /><code>administrator</code> || <translate>
Modules</translate>
| <translate>
The client attribute allows you to specify for which application client the new module is available.</translate>
|-
| group
| ''string'' || <translate>
Plugins</translate>
| <translate>
The group name specifies for which group of plugins the new plugin is available. The existing groups are the folder names within the directory <tt>/plugins</tt>. The installer will create new folder names for group names that do not exist yet.</translate>
|}

<translate>=== Metadata === </translate>

<translate>
The following elements can be used to insert metadata. None of these elements are required; if they are present, they must be a child of the root element.</translate>

<pre>
<name> – raw component name (e.g. com_banners).
<author> – author's name (e.g. Joomla! Project)
<creationDate> – date of creation or release (e.g. April 2006)
<copyright> – a copyright statement (e.g. (C) 2005 - 2011 Open Source Matters. All rights reserved.)
<license> – a license statement (e.g. NU General Public License version 2 or later; see LICENSE.txt)
<authorEmail> – author's email address (e.g. admin@joomla.org)
<authorUrl> – URL to the author's website (e.g. www.joomla.org)
<version> – the version number of the extension (e.g. 1.6.0)
<description> – the description of the component. This is a translatable field. (e.g. COM_BANNERS_XML_DESCRIPTION)
</pre>

<translate>
Note: The <name> and <description> tags are also translatable fields so that the name and description of the extension can be shown to the user in their native language.</translate>

<translate>=== Front-end files === </translate>

<source lang="xml">
<files folder="from-folder">
<filename>example.php</filename>
<folder>examples</folder>
</files>
</source>

<translate>
Files to copy to the front-end directory should be placed in the <code><files></code> element. You can use the optional <code>folder</code> attribute to specify a directory '''in the ZIP package''' to copy '''from'''. Each file to copy must be represented by a <code><filename></code> element. If you want to copy an entire folder at once, you can define it as a <code><folder></code>.</translate>

<translate>
For '''plugins''', the raw name of the plugin should be placed in the <code>plugin</code> attribute on the <code><filename></code> element that points to the file containing the plugin's class. For example, in the case of a system plugin called "example" (full name <code>plg_system_example</code>), use <code><filename plugin="example">example.php</filename></code>.</translate>

<translate>=== Media files === </translate>

<source lang="xml>
<media folder="media" destination="com_example">
<filename>com_example_logo.png</filename>
<folder>css</folder>
<folder>js</folder>
</media>
</source>

<translate>
This example will copy the file(s) (<tt>/media/com_example_logo.png</tt>) and folders ( <tt>/media/css/</tt> and <tt>/media/js/</tt> ) listed to <tt>/media/com_example/</tt>, creating the <tt>com_example</tt> folder if required. You can use the optional <code>folder</code> attribute to specify a directory '''in the ZIP package''' to copy '''from''' (in this case, <tt>media</tt>).</translate>

<translate>
Extensions should be storing assets they need to be web accessible (JS, CSS, images etc) in <code>media</code>. Amongst other things this feature was added as step in the progression to multi-site support and the eventual move of code files (PHP) out of the web accessible areas of the server.</translate>

Ref:
* [https://groups.google.com/forum/#!msg/joomla-dev-cms/4CAASJqFY-k/PvPj14gP29EJ Google Groups - joomla-dev-cms thread]
* [https://groups.google.com/forum/#!msg/joomla-dev-cms/uNmhX98sKbE/p8p68Jke680J Google Groups - joomla-dev-cms thread]

<translate>=== Administration section === </translate>

<source lang="xml">
<administration>

</administration>
</source>

<translate>
The administration section is defined in the <code><administration></code> element. Since only [[S:MyLanguage/Component|components]] apply to both the [[S:MyLanguage/Site (Application)|site]] and the [[S:MyLanguage/Administrator (Application)|administrator]], '''only component manifests can include this element'''.</translate>

<translate>==== Back-end files ==== </translate>

<translate>
Files to copy to the back-end directory should be placed in the <code><files></code> element under the <code><administration></code>. You can use the optional <code>folder</code> attribute to specify a directory '''in the ZIP package''' to copy '''from'''. See ''Front-end files'' for further rules.</translate>

<translate>==== Menu links and submenus ==== </translate>
{{dablink|<translate>
'''Version Note:''' Prior to Joomla 3.4, not having a <code><nowiki><menu></nowiki></code> tag in your manifest XML file still led to a menu item being created. This bug was fixed in Joomla 3.4, so if there is no <code><nowiki><menu></nowiki></code> tag in your manifest file, then no admin menu item is created for the component.</translate>}}

<source lang="xml">
<menu>COM_EXAMPLE</menu>
<submenu>

<menu link="anoption=avalue&anoption1=avalue1">COM_EXAMPLE_SUBMENU_ANOPTION</menu>
<menu view="viewname">COM_EXAMPLE_SUBMENU_VIEWNAME</menu>
</submenu>
</source>

<translate>
The text for the main menu item for the component is defined in the <code><menu></code> item, a child of <code><administration></code>. A <code><submenu></code> element may also be present (also a child of <code><administration></code>), which may contain more menu items defined by <code><menu></code>.</translate>

<translate>
Additionally, each <code><menu></code> item can define the following attributes:</translate>

{| class="wikitable"
! style="width: 150px" | <translate>
Attribute</translate> || <translate>
Description</translate>
|-
| link || <translate>
A link to send the user to when the menu item is clicked</translate>
|-
| img || <translate>
The (relative) path to an image (16x16 pixels) to appear beside the menu item.
<u>Must be an url compatible as a file too (e.g. no spaces) !</u></translate>
|-
| alt ||
|-
| ''string'' || <translate>
An URL parameter to add to the link. For example, <code><menu view="cpanel">COM_EXAMPLE</menu></code> in com_example's XML manifest would cause the URL of the menu item to be <tt>index.php?option=com_example&view=cpanel</tt>.</translate>
|-
|}

<translate>
The value inside the tag is the menu's label. Unlike Joomla! 1.5, you can not use a natural language string. For example, if you would enter "Example Component" instead of COM_EXAMPLE, it would result in your component name appearing as example-component in the menu and you would be unable to provide a translation. In order to provide a translation you need to create a file named en-GB.com_example.sys.ini in administrator/languages/en-GB (you can use the manifest's <code><languages></code> tag to copy it during installation) or in administrator/components/com_example/language/en-GB. In the latter case, you must not include the translation file in the <code><languages></code> tag. As long as you have placed the language directory in your <code><files></code> tag, it will be copied along when the component is being installed.</translate>

<translate>
The contents of that file should be:</translate>

<source>
COM_EXAMPLE="Example Component"
COM_EXAMPLE_SUBMENU_ANOPTION="Another Option"
COM_EXAMPLE_SUBMENU_VIEWNAME="Another View"
</source>

<translate>
Please note that the language string must be enclosed in double quotes, as per Joomla!'s translation standards. Important note: Joomla! 1.6 and later sorts the Component menu items based on the actual translation of the key you supply in your XML manifest. This means that the sorting order is correct no matter what you call your translation key and no matter which language the site is being displayed in. Essentially, Joomla! 1.6 fixed the wrong sorting of the Components menu experienced under Joomla! 1.5 for the majority (non-English speaking!) of Joomla! users.</translate>

<translate>=== Configuration === </translate>
{{warning|<translate>
Components '''do not support''' configuration definitions '''in the manifest'''. This is a way implemented in Joomla! 1.5. They can define configuration options for multiple levels using [[S:MyLanguage/Component configuration metadata|Component configuration metadata]].</translate>}}
<translate>
The <code><config></code> element, a child of the root, describes the configuration options for the extension. If applicable, the options will be shown by the appropriate Manager (Plugin Manager, Module Manager or Template Manager). '''Configuration options can also be defined in a separate file named <code>config.xml</code>. Its root element should be <code><config></code>.'''</translate>

<translate>
Each fieldset must contain one or more <code><field></code> elements, each representing a single [[S:MyLanguage/form field|form field]] with a label. See [[S:MyLanguage/Standard form field types|Standard form field types]] for a list of allowed form field types and example XML form field definitions.</translate>

<translate>=== SQL === </translate>

<source lang="xml">
<install>
<sql>
<file driver="mysql" charset="utf8">sql/example.install.sql</file>
</sql>
</install>
<uninstall>
<sql>
<file driver="mysql" charset="utf8">sql/example.uninstall.sql</file>
</sql>
</uninstall>
</source>

<translate>
In the above example, we put the SQL files in the <tt>admin/sql</tt> folder of the installation package. You have to include the <tt>sql</tt> folder in the administration files (as described in ''Back-end files'').</translate>

<translate>
You can execute SQL during the installation and/or uninstallation using the <code><install></code> and <code><uninstall></code> elements, respectively. A <code><sql></code> element should appear as a child of these elements. <code><sql></code> can contain any number of <code><file></code> elements, each defining a single SQL file to execute. Their database driver types are described by the <code>driver</code> attribute, their character sets by the <code>charset</code> attribute.</translate>

<translate>==== Update of the SQL schema ==== </translate>

<source lang="xml">
<update>
<schemas>
<schemapath type="mysql">sql/updates/mysql</schemapath>
<schemapath type="sqlsrv">sql/updates/sqlsrv</schemapath>
</schemas>
</update>
</source>

<translate>
Since 1.6, there is also an <code><update></code> tag, which allows you to provide a series of SQL files to update the current schema.</translate>

<translate>=== Language files === </translate>
<translate>
In Joomla! 1.5, extension developers had to put extension language files in the Joomla! main language file, using the <languages>...</languages> tag as shown below. '''This method can still be used in Joomla!''' {{JVer|3.x}}.</translate>

<source lang="xml">

<languages folder="langfiles">
<language tag="en-GB">en-GB.com_example.ini</language>
</languages>
</source>

<translate>
Since Joomla! 1.6 it has been encouraged placing your extension's language files in your extension folder. Joomla! will then automatically load your extension's language files.</translate>

<translate>
By storing extension language files in the extension folder, you gain the benefit of isolating and protecting your extension's language files. For example, an administrator removes a language from their Joomla! installation. Your extension's language files will not be removed. They will remain in place and will be available if the language is installed again.</translate>

<translate>
The structure of the language folder for frontend and backend is the same. You put them in the language tag (e.g. '''en-GB''' ) of each language in your language folder i.e. '''language/en-GB/'''. You have to specify those folders in the front-end and back-end files too.</translate>

<translate>
In your manifest you simply include the ''''language'''' folder in your files section, the sub-directories for each language automatically be copied. Inside the <files> group you simply add a <folder> element alongside the items in the '''<files>''' group as shown in this example:</translate>

<source lang="xml">
<files>
<filename plugin="alpha">alpha.php</filename>
<folder>sql</folder>
<folder>language</folder>
</files>
</source>

<translate>
It is also notable that both ways can work together. Here is an example from core:</translate>

<source lang="xml">
<files>
<filename plugin="languagecode">languagecode.php</filename>
<filename>index.html</filename>
<folder>language</folder>
</files>
<languages>
<language tag="en-GB">language/en-GB/en-GB.plg_system_languagecode.ini</language>
<language tag="en-GB">language/en-GB/en-GB.plg_system_languagecode.sys.ini</language>
</languages>
</source>

<translate>
The advantages of this solution are the following:</translate>

<translate>
All ini files present in the core folder have precedence over the files in the extension language/ folder.
For example a sys.ini file will always be loaded from core folders in back-end if it exists, except when installing an extension which contains a sys.ini file in a language folder. In that case and only that case, the sys.ini file in the extension folder will display its translated content at install time. This is very handy as a developer can have 2 sys.ini files with different contents. A description of the successful install as well as a tutorial in back-end for example.</translate>

<translate>
Also, it is much easier for a user needing an ini file for an extension that does not provide it in the language desired, to add it in the main folders. No risk for it to be deleted in case of uninstalling the extension by mistake or any other reason.</translate>

<translate>
See also:
*[[S:MyLanguage/J2.5:Making non-core language packs|Making non-core language packs]]
*[[S:MyLanguage/Creating language packs for extensions in Joomla 2.5|Creating language packs for extensions in Joomla 2.5]]</translate>

<translate>
During development you can turn on language debugging in the Joomla! global configuration. So you can investigate if a problems arises. As of 3.2, this is necessary to help debug as en-GB is '''always''' loaded first when not in debug mode to prevent displaying Constants.</translate>

<translate>=== Script file === </translate>

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

<translate>
An optional '''script file''' (PHP code that is run before, during and/or after installation, uninstallation and upgrading) can be defined using a <code><scriptfile></code> element. This file should contain a class named "<element_name>InstallerScript" where <element_name> is the name of your extension (e.g. com_componentname, mod_modulename, etc.). Plugins requires to state the group (e.g. plgsystempluginname). Library packages do not support scriptfiles. The structure of the class is as follows:</translate>

<source lang="php">

class com_componentnameInstallerScript
{
/**
* Constructor
*
* @param JAdapterInstance $adapter The object responsible for running this script
*/
public function __construct(JAdapterInstance $adapter);

/**
* Called before any type of action
*
* @param string $route Which action is happening (install|uninstall|discover_install|update)
* @param JAdapterInstance $adapter The object responsible for running this script
*
* @return boolean True on success
*/
public function preflight($route, JAdapterInstance $adapter);

/**
* Called after any type of action
*
* @param string $route Which action is happening (install|uninstall|discover_install|update)
* @param JAdapterInstance $adapter The object responsible for running this script
*
* @return boolean True on success
*/
public function postflight($route, JAdapterInstance $adapter);

/**
* Called on installation
*
* @param JAdapterInstance $adapter The object responsible for running this script
*
* @return boolean True on success
*/
public function install(JAdapterInstance $adapter);

/**
* Called on update
*
* @param JAdapterInstance $adapter The object responsible for running this script
*
* @return boolean True on success
*/
public function update(JAdapterInstance $adapter);

/**
* Called on uninstallation
*
* @param JAdapterInstance $adapter The object responsible for running this script
*/
public function uninstall(JAdapterInstance $adapter);
}

</source>

<translate>=== Update servers === </translate>

<source lang="xml">
<updateservers>
<server type="extension" priority="1" name="Extension Update Site">http://example.com/extension.xml</server>
<server type="collection" priority="2" name="Collection Update Site">http://example.com/collection.xml</server>
</updateservers>
</source>

<translate>
Update servers can be defined in the <code><updateservers></code> element, a child of the root. This element may contain one or more <code><server></code> element, each describing a location to fetch updates from. Each <code><server></code> item can define the following attributes:</translate>

{| class="wikitable"
! style="width: 150px" | <translate>
Attribute</translate> || style="width: 150px" | <translate>
Values</translate> || <translate>
Description</translate>
|-
| type || <code>extension</code><br /><code>collection</code> || <translate>
The update server type</translate>
|-
| priority || ''integer'' || <translate>
The priority of the update server</translate>
|-
| name || ''string'' || <translate>
The name of the update server</translate>
|}

<translate>
More info:
* [[S:MyLanguage/J2.5:Developing a MVC Component/Adding an update server|Building a Joomla! Extension - Adding an update server]]
* [[S:MyLanguage/J2.5:Managing Component Updates|Managing Component Updates in Joomla 2.5]]</translate>

<translate>== Examples == 
For a real-life example, see [https://github.com/joomla/joomla-cms/blob/2.5.x/administrator/components/com_banners/banners.xml the manifest of the Banner component in the latest version of Joomla! 2.5].</translate>

<translate>
The Joomla testing process uses several extensions to test whether the installer works correctly. The latest versions of the manifests of these extensions are:</translate>

* [http://svn.joomla.org/project/cms/development/trunk/tests/_data/installer_packages/com_alpha/alpha.xml com_alpha manifest]
* [http://svn.joomla.org/project/cms/development/trunk/tests/_data/installer_packages/mod_alpha/mod_alpha.xml mod_alpha manifest]
* [http://svn.joomla.org/project/cms/development/trunk/tests/_data/installer_packages/plg_system_alpha/alpha.xml plg_system_alpha manifest]
* [http://svn.joomla.org/project/cms/development/trunk/tests/_data/installer_packages/tpl_simple/templateDetails.xml tpl_simple manifest]
* [http://svn.joomla.org/project/cms/development/trunk/tests/_data/installer_packages/lng_xx-XX/xx-XX.xml lng_xx-XX manifest]

<translate>== Contributors == </translate>
*[[User:akede|Alex Kempkens]]
*[[User:dperaza|Daniel Peraza]]
*[[User:nikosdion|Nicholas K. Dionysopoulos]]
*[[User:mrs.siam|Prasit Gebsaap]]
*[[User:cppl|Craig Phillips]]

<noinclude>
<translate>

[[Category:Development]]
[[Category:Extension development]]
[[Category:Specifications]]
</translate>
</noinclude>

Manifest files

2015-09-19T14:05:19Z

Mvangeest: Adjusted wording

<noinclude><languages /></noinclude>
<noinclude>{{page|needs updating|}}</noinclude>
<noinclude>
{{Joomla version|version=3.x}} {{Joomla version|version=2.5|time=and after|status=eos}}
</noinclude>
<translate>
Within Joomla there are manifest files for all of the extensions. These files include the general installation information as well as parameters for the configuration of the [[S:MyLanguage/extension|extension]] itself. Since Joomla! 2.5, there are very few differences between the manifest file formats for the different [[S:MyLanguage/Extension types (technical definitions)|types of extensions]], allowing each type to access the full power of the Joomla! installer.</translate>

<translate>==Naming conventions== 
The file must be named <tt>manifest.xml</tt> or <tt><extension_name>.xml</tt> and located in the root directory of the installation package.</translate>

<translate>==Syntax== </translate>

<translate>=== Root element === 
The primary tag of the installation file is:</translate>
<source lang=xml><extension></extension></source>

<translate>
This starting and closing tags are now valid for all extensions. The new tag <code><extension></code> replaces the old <code><install></install></code> from Joomla {{JVer|1.5}}. The following attributes are allowed within the tag:</translate>

{|class="wikitable"
|-
! style="width: 150px" | <translate>
Attribute</translate> || style="width: 150px" | <translate>
Values</translate> || <translate>
Applicable to</translate> || <translate>
Description</translate>
|-
| type || <code>component</code><br /><code>file</code><br /><code>language</code><br /><code>library</code><br /><code>module</code><br /><code>package</code><br /><code>plugin</code><br /><code>template</code> || <translate>
All extensions</translate>
| <translate>
This attribute describes the type of the extension for the installer. Based on this type further requirements to sub-tags apply.</translate>
|-
| version
| <code>2.5</code><br /><code>3.0</code> || <translate>
All extensions</translate>
| <translate>
String that identifies the version of Joomla for which this extension is developed.</translate>
|-
| method
| <code>install</code><br /><code>upgrade</code> || <translate>
All extensions</translate>
| <translate>
The default value <code>install</code> will be also used if the method attribute is not used. The <code>install</code> value means the installer will gracefully stop if it finds any existing file/folder of the new extension.</translate>
|-
| client
| <code>site</code><br /><code>administrator</code> || <translate>
Modules</translate>
| <translate>
The client attribute allows you to specify for which application client the new module is available.</translate>
|-
| group
| ''string'' || <translate>
Plugins</translate>
| <translate>
The group name specifies for which group of plugins the new plugin is available. The existing groups are the folder names within the directory <tt>/plugins</tt>. The installer will create new folder names for group names that do not exist yet.</translate>
|}

<translate>=== Metadata === </translate>

<translate>
The following elements can be used to insert metadata. None of these elements are required; if they are present, they must be a child of the root element.</translate>

<pre>
<name> – raw component name (e.g. com_banners).
<author> – author's name (e.g. Joomla! Project)
<creationDate> – date of creation or release (e.g. April 2006)
<copyright> – a copyright statement (e.g. (C) 2005 - 2011 Open Source Matters. All rights reserved.)
<license> – a license statement (e.g. NU General Public License version 2 or later; see LICENSE.txt)
<authorEmail> – author's email address (e.g. admin@joomla.org)
<authorUrl> – URL to the author's website (e.g. www.joomla.org)
<version> – the version number of the extension (e.g. 1.6.0)
<description> – the description of the component. This is a translatable field. (e.g. COM_BANNERS_XML_DESCRIPTION)
</pre>

<translate>
Note: The <name> and <description> tags are also translatable fields so that the name and description of the extension can be shown to the user in their native language.</translate>

<translate>=== Front-end files === </translate>

<source lang="xml">
<files folder="from-folder">
<filename>example.php</filename>
<folder>examples</folder>
</files>
</source>

<translate>
Files to copy to the front-end directory should be placed in the <code><files></code> element. You can use the optional <code>folder</code> attribute to specify a directory '''in the ZIP package''' to copy '''from'''. Each file to copy must be represented by a <code><filename></code> element. If you want to copy an entire folder at once, you can define it as a <code><folder></code>.</translate>

<translate>=== Media files === </translate>

<source lang="xml>
<media folder="media" destination="com_example">
<filename>com_example_logo.png</filename>
<folder>css</folder>
<folder>js</folder>
</media>
</source>

<translate>
This example will copy the file(s) (<tt>/media/com_example_logo.png</tt>) and folders ( <tt>/media/css/</tt> and <tt>/media/js/</tt> ) listed to <tt>/media/com_example/</tt>, creating the <tt>com_example</tt> folder if required. You can use the optional <code>folder</code> attribute to specify a directory '''in the ZIP package''' to copy '''from''' (in this case, <tt>media</tt>).</translate>

<translate>
Extensions should be storing assets they need to be web accessible (JS, CSS, images etc) in <code>media</code>. Amongst other things this feature was added as step in the progression to multi-site support and the eventual move of code files (PHP) out of the web accessible areas of the server.</translate>

Ref:
* [https://groups.google.com/forum/#!msg/joomla-dev-cms/4CAASJqFY-k/PvPj14gP29EJ Google Groups - joomla-dev-cms thread]
* [https://groups.google.com/forum/#!msg/joomla-dev-cms/uNmhX98sKbE/p8p68Jke680J Google Groups - joomla-dev-cms thread]

<translate>=== Administration section === </translate>

<source lang="xml">
<administration>

</administration>
</source>

<translate>
The administration section is defined in the <code><administration></code> element. Since only [[S:MyLanguage/Component|components]] apply to both the [[S:MyLanguage/Site (Application)|site]] and the [[S:MyLanguage/Administrator (Application)|administrator]], '''only component manifests can include this element'''.</translate>

<translate>==== Back-end files ==== </translate>

<translate>
Files to copy to the back-end directory should be placed in the <code><files></code> element under the <code><administration></code>. You can use the optional <code>folder</code> attribute to specify a directory '''in the ZIP package''' to copy '''from'''. See ''Front-end files'' for further rules.</translate>

<translate>==== Menu links and submenus ==== </translate>
{{dablink|<translate>
'''Version Note:''' Prior to Joomla 3.4, not having a <code><nowiki><menu></nowiki></code> tag in your manifest XML file still led to a menu item being created. This bug was fixed in Joomla 3.4, so if there is no <code><nowiki><menu></nowiki></code> tag in your manifest file, then no admin menu item is created for the component.</translate>}}

<source lang="xml">
<menu>COM_EXAMPLE</menu>
<submenu>

<menu link="anoption=avalue&anoption1=avalue1">COM_EXAMPLE_SUBMENU_ANOPTION</menu>
<menu view="viewname">COM_EXAMPLE_SUBMENU_VIEWNAME</menu>
</submenu>
</source>

<translate>
The text for the main menu item for the component is defined in the <code><menu></code> item, a child of <code><administration></code>. A <code><submenu></code> element may also be present (also a child of <code><administration></code>), which may contain more menu items defined by <code><menu></code>.</translate>

<translate>
Additionally, each <code><menu></code> item can define the following attributes:</translate>

{| class="wikitable"
! style="width: 150px" | <translate>
Attribute</translate> || <translate>
Description</translate>
|-
| link || <translate>
A link to send the user to when the menu item is clicked</translate>
|-
| img || <translate>
The (relative) path to an image (16x16 pixels) to appear beside the menu item.
<u>Must be an url compatible as a file too (e.g. no spaces) !</u></translate>
|-
| alt ||
|-
| ''string'' || <translate>
An URL parameter to add to the link. For example, <code><menu view="cpanel">COM_EXAMPLE</menu></code> in com_example's XML manifest would cause the URL of the menu item to be <tt>index.php?option=com_example&view=cpanel</tt>.</translate>
|-
|}

<translate>
The value inside the tag is the menu's label. Unlike Joomla! 1.5, you can not use a natural language string. For example, if you would enter "Example Component" instead of COM_EXAMPLE, it would result in your component name appearing as example-component in the menu and you would be unable to provide a translation. In order to provide a translation you need to create a file named en-GB.com_example.sys.ini in administrator/languages/en-GB (you can use the manifest's <code><languages></code> tag to copy it during installation) or in administrator/components/com_example/language/en-GB. In the latter case, you must not include the translation file in the <code><languages></code> tag. As long as you have placed the language directory in your <code><files></code> tag, it will be copied along when the component is being installed.</translate>

<translate>
The contents of that file should be:</translate>

<source>
COM_EXAMPLE="Example Component"
COM_EXAMPLE_SUBMENU_ANOPTION="Another Option"
COM_EXAMPLE_SUBMENU_VIEWNAME="Another View"
</source>

<translate>
Please note that the language string must be enclosed in double quotes, as per Joomla!'s translation standards. Important note: Joomla! 1.6 and later sorts the Component menu items based on the actual translation of the key you supply in your XML manifest. This means that the sorting order is correct no matter what you call your translation key and no matter which language the site is being displayed in. Essentially, Joomla! 1.6 fixed the wrong sorting of the Components menu experienced under Joomla! 1.5 for the majority (non-English speaking!) of Joomla! users.</translate>

<translate>=== Configuration === </translate>
{{warning|<translate>
Components '''do not support''' configuration definitions '''in the manifest'''. This is a way implemented in Joomla! 1.5. They can define configuration options for multiple levels using [[S:MyLanguage/Component configuration metadata|Component configuration metadata]].</translate>}}
<translate>
The <code><config></code> element, a child of the root, describes the configuration options for the extension. If applicable, the options will be shown by the appropriate Manager (Plugin Manager, Module Manager or Template Manager). '''Configuration options can also be defined in a separate file named <code>config.xml</code>. Its root element should be <code><config></code>.'''</translate>

<translate>
Each fieldset must contain one or more <code><field></code> elements, each representing a single [[S:MyLanguage/form field|form field]] with a label. See [[S:MyLanguage/Standard form field types|Standard form field types]] for a list of allowed form field types and example XML form field definitions.</translate>

<translate>=== SQL === </translate>

<source lang="xml">
<install>
<sql>
<file driver="mysql" charset="utf8">sql/example.install.sql</file>
</sql>
</install>
<uninstall>
<sql>
<file driver="mysql" charset="utf8">sql/example.uninstall.sql</file>
</sql>
</uninstall>
</source>

<translate>
In the above example, we put the SQL files in the <tt>admin/sql</tt> folder of the installation package. You have to include the <tt>sql</tt> folder in the administration files (as described in ''Back-end files'').</translate>

<translate>
You can execute SQL during the installation and/or uninstallation using the <code><install></code> and <code><uninstall></code> elements, respectively. A <code><sql></code> element should appear as a child of these elements. <code><sql></code> can contain any number of <code><file></code> elements, each defining a single SQL file to execute. Their database driver types are described by the <code>driver</code> attribute, their character sets by the <code>charset</code> attribute.</translate>

<translate>==== Update of the SQL schema ==== </translate>

<source lang="xml">
<update>
<schemas>
<schemapath type="mysql">sql/updates/mysql</schemapath>
<schemapath type="sqlsrv">sql/updates/sqlsrv</schemapath>
</schemas>
</update>
</source>

<translate>
Since 1.6, there is also an <code><update></code> tag, which allows you to provide a series of SQL files to update the current schema.</translate>

<translate>=== Language files === </translate>
<translate>
In Joomla! 1.5, extension developers had to put extension language files in the Joomla! main language file, using the <languages>...</languages> tag as shown below. '''This method can still be used in Joomla!''' {{JVer|3.x}}.</translate>

<source lang="xml">

<languages folder="langfiles">
<language tag="en-GB">en-GB.com_example.ini</language>
</languages>
</source>

<translate>
Since Joomla! 1.6 it has been encouraged placing your extension's language files in your extension folder. Joomla! will then automatically load your extension's language files.</translate>

<translate>
By storing extension language files in the extension folder, you gain the benefit of isolating and protecting your extension's language files. For example, an administrator removes a language from their Joomla! installation. Your extension's language files will not be removed. They will remain in place and will be available if the language is installed again.</translate>

<translate>
The structure of the language folder for frontend and backend is the same. You put them in the language tag (e.g. '''en-GB''' ) of each language in your language folder i.e. '''language/en-GB/'''. You have to specify those folders in the front-end and back-end files too.</translate>

<translate>
In your manifest you simply include the ''''language'''' folder in your files section, the sub-directories for each language automatically be copied. Inside the <files> group you simply add a <folder> element alongside the items in the '''<files>''' group as shown in this example:</translate>

<source lang="xml">
<files>
<filename plugin="alpha">alpha.php</filename>
<folder>sql</folder>
<folder>language</folder>
</files>
</source>

<translate>
It is also notable that both ways can work together. Here is an example from core:</translate>

<source lang="xml">
<files>
<filename plugin="languagecode">languagecode.php</filename>
<filename>index.html</filename>
<folder>language</folder>
</files>
<languages>
<language tag="en-GB">language/en-GB/en-GB.plg_system_languagecode.ini</language>
<language tag="en-GB">language/en-GB/en-GB.plg_system_languagecode.sys.ini</language>
</languages>
</source>

<translate>
The advantages of this solution are the following:</translate>

<translate>
All ini files present in the core folder have precedence over the files in the extension language/ folder.
For example a sys.ini file will always be loaded from core folders in back-end if it exists, except when installing an extension which contains a sys.ini file in a language folder. In that case and only that case, the sys.ini file in the extension folder will display its translated content at install time. This is very handy as a developer can have 2 sys.ini files with different contents. A description of the successful install as well as a tutorial in back-end for example.</translate>

<translate>
Also, it is much easier for a user needing an ini file for an extension that does not provide it in the language desired, to add it in the main folders. No risk for it to be deleted in case of uninstalling the extension by mistake or any other reason.</translate>

<translate>
See also:
*[[S:MyLanguage/J2.5:Making non-core language packs|Making non-core language packs]]
*[[S:MyLanguage/Creating language packs for extensions in Joomla 2.5|Creating language packs for extensions in Joomla 2.5]]</translate>

<translate>
During development you can turn on language debugging in the Joomla! global configuration. So you can investigate if a problems arises. As of 3.2, this is necessary to help debug as en-GB is '''always''' loaded first when not in debug mode to prevent displaying Constants.</translate>

<translate>=== Script file === </translate>

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

<translate>
An optional '''script file''' (PHP code that is run before, during and/or after installation, uninstallation and upgrading) can be defined using a <code><scriptfile></code> element. This file should contain a class named "<element_name>InstallerScript" where <element_name> is the name of your extension (e.g. com_componentname, mod_modulename, etc.). Plugins requires to state the group (e.g. plgsystempluginname). Library packages do not support scriptfiles. The structure of the class is as follows:</translate>

<source lang="php">

class com_componentnameInstallerScript
{
/**
* Constructor
*
* @param JAdapterInstance $adapter The object responsible for running this script
*/
public function __construct(JAdapterInstance $adapter);

/**
* Called before any type of action
*
* @param string $route Which action is happening (install|uninstall|discover_install|update)
* @param JAdapterInstance $adapter The object responsible for running this script
*
* @return boolean True on success
*/
public function preflight($route, JAdapterInstance $adapter);

/**
* Called after any type of action
*
* @param string $route Which action is happening (install|uninstall|discover_install|update)
* @param JAdapterInstance $adapter The object responsible for running this script
*
* @return boolean True on success
*/
public function postflight($route, JAdapterInstance $adapter);

/**
* Called on installation
*
* @param JAdapterInstance $adapter The object responsible for running this script
*
* @return boolean True on success
*/
public function install(JAdapterInstance $adapter);

/**
* Called on update
*
* @param JAdapterInstance $adapter The object responsible for running this script
*
* @return boolean True on success
*/
public function update(JAdapterInstance $adapter);

/**
* Called on uninstallation
*
* @param JAdapterInstance $adapter The object responsible for running this script
*/
public function uninstall(JAdapterInstance $adapter);
}

</source>

<translate>=== Update servers === </translate>

<source lang="xml">
<updateservers>
<server type="extension" priority="1" name="Extension Update Site">http://example.com/extension.xml</server>
<server type="collection" priority="2" name="Collection Update Site">http://example.com/collection.xml</server>
</updateservers>
</source>

<translate>
Update servers can be defined in the <code><updateservers></code> element, a child of the root. This element may contain one or more <code><server></code> element, each describing a location to fetch updates from. Each <code><server></code> item can define the following attributes:</translate>

{| class="wikitable"
! style="width: 150px" | <translate>
Attribute</translate> || style="width: 150px" | <translate>
Values</translate> || <translate>
Description</translate>
|-
| type || <code>extension</code><br /><code>collection</code> || <translate>
The update server type</translate>
|-
| priority || ''integer'' || <translate>
The priority of the update server</translate>
|-
| name || ''string'' || <translate>
The name of the update server</translate>
|}

<translate>
More info:
* [[S:MyLanguage/J2.5:Developing a MVC Component/Adding an update server|Building a Joomla! Extension - Adding an update server]]
* [[S:MyLanguage/J2.5:Managing Component Updates|Managing Component Updates in Joomla 2.5]]</translate>

<translate>== Examples == 
For a real-life example, see [https://github.com/joomla/joomla-cms/blob/2.5.x/administrator/components/com_banners/banners.xml the manifest of the Banner component in the latest version of Joomla! 2.5].</translate>

<translate>
The Joomla testing process uses several extensions to test whether the installer works correctly. The latest versions of the manifests of these extensions are:</translate>

* [http://svn.joomla.org/project/cms/development/trunk/tests/_data/installer_packages/com_alpha/alpha.xml com_alpha manifest]
* [http://svn.joomla.org/project/cms/development/trunk/tests/_data/installer_packages/mod_alpha/mod_alpha.xml mod_alpha manifest]
* [http://svn.joomla.org/project/cms/development/trunk/tests/_data/installer_packages/plg_system_alpha/alpha.xml plg_system_alpha manifest]
* [http://svn.joomla.org/project/cms/development/trunk/tests/_data/installer_packages/tpl_simple/templateDetails.xml tpl_simple manifest]
* [http://svn.joomla.org/project/cms/development/trunk/tests/_data/installer_packages/lng_xx-XX/xx-XX.xml lng_xx-XX manifest]

<translate>== Contributors == </translate>
*[[User:akede|Alex Kempkens]]
*[[User:dperaza|Daniel Peraza]]
*[[User:nikosdion|Nicholas K. Dionysopoulos]]
*[[User:mrs.siam|Prasit Gebsaap]]
*[[User:cppl|Craig Phillips]]

<noinclude>
<translate>

[[Category:Development]]
[[Category:Extension development]]
[[Category:Specifications]]
</translate>
</noinclude>

Creating a language definition file

2015-09-17T21:03:41Z

Mvangeest: Rewrote article for Joomla 3 based on the Specification page, the PHP docs, the JLanguage source code, core language files and user comments. The warning is no longer necessary.

<noinclude><languages /></noinclude>
{{Joomla version|version=3.x|comment=<translate>
series</translate>}}
{{-}}
{{notice|<translate>
The page [[S:MyLanguage/Specification of language files|Specification of language files]] contains some more details that should be '''verified''' - as it is no longer completely up-to-date - and then merged into this page.</translate>}}

<translate>

Joomla! language definition files are written in the very basic ''[[wikipedia:INI file|INI file format]]''. They must be saved ''using the UTF-8 encoding''. Blank lines and lines beginning with <code>;</code> are ignored and the latter may be used to add comments to the file. Each line consists of a key-value pair separated by an equals sign like this:
</translate>

<translate>
<source lang="ini">
KEY="value"
</source></translate>

<translate>

where <code>KEY</code> is a string to be translated and <code>value</code> is the translated string. For example:
</translate>

<source lang="ini">
ADDITIONAL_INFORMATION="Additional Information"
</source>

<translate>
Different versions of Joomla have used slightly different ways to read language files (namely a custom parser and the native PHP INI parser, the latter of which was buggy in PHP 5.2 and older), leading to different rules for what exactly is allowed in keys and values. Language files that abide by the following rules should work under many versions of Joomla, but at least under Joomla {{jver|3.x}} and newer.
</translate>

<translate>

The <code>KEY</code> should only use ASCII characters. It should only contain capital letters, digits, underscores and hyphens, and it should start with a capital letter. (Dots (<code>.</code>) are formally allowed, but do not appear to be completely supported.) It is a convention to replace any whitespace in the string to be translated with underscores. If more than one entry has the same key, the last one to be encountered is the one that will be used. When you use the key in a <code>JText::_</code> call, the case does not matter as strings are folded to upper case before searching takes place. So <code>additional_information</code>, <code>Additional_Information</code> or even <code>AdDiTiOnAl_InFoRmAtIoN</code> will be matched.
</translate>

<translate>

The <code>value</code> should always be surrounded by double-quote characters (<code>"</code>), as in the example. The value itself cannot include double-quote characters (<code>"</code>), although single-quote characters (<code>'</code>) are valid. Use <code>"_QQ_"</code>, ''including the double quotes'', to place a double-quote character in your value. For example, to attach the value <code><nowiki><span class="red">Warning!</span></nowiki></code> to the key <code>WARNING_TEXT</code>, use following line:
</translate>

<source lang="ini">
WARNING_TEXT="<span class="_QQ_"red"_QQ_">Warning!</span>"
</source>

<translate>
Note that these rules are stricter than required by [http://php.net/manual/en/function.parse-ini-file.php the PHP INI parser]. For example, the PHP INI parser allows you to omit the double quotes around the value as long as it does not contain certain characters. Using the rules above should make it much easier to avoid mistakes like forgetting double quotes when they ''are'' required.
</translate>

<translate>

Information about the changes in the language file format between the Joomla 1.5, 2.5 and 3.x series can be found on the page [[S:MyLanguage/Specification of language files|Specification of language files]].
</translate>

<noinclude>
----
<references/>
<translate>

[[Category:Tutorials]]
[[Category:Language Development]]
</translate>
</noinclude>

Creating a language definition file

2015-09-17T18:19:08Z

Mvangeest: Added warning: this page's contents are *not* - at least not entirely - valid for the 3 series. The Specification page should be merged into this one.

<noinclude><languages /></noinclude>

{{Joomla version|version=3.x|comment=<translate>
series</translate>}}
{{warning|This page was written for Joomla {{jver|1.5}}. Joomla {{jver|3.x}} has slightly different requirements, as explained in [[Specification of language files]]. See [http://php.net/manual/en/function.parse-ini-string.php the PHP documentation] for more details.}}

<translate>

Important note: Joomla language <code>.ini</code> files must be saved as UTF-8
</translate>

<translate>

The format of language definition files is very basic. Blanks lines and lines beginning with “#” are ignored and the latter may be used to add comments to the file. Each line consists of a pair of strings separated by an equals sign like this :
</translate>

<translate>
KEY=Value</translate>

<translate>

where “''KEY''” is a string to be translated and “''Value''” is the translated string. For example :
</translate>

ADDITIONAL_INFORMATION="Additional Information"

<translate>

The “''KEY''” must be in all capitals or the string will not be found. The case of the source string does not matter as strings are folded to upper case before searching takes place. So “additional information”, “Additional Information” or even “AdDiTiOnAl InFoRmAtIoN” will be matched.
</translate>

<translate>

The “''KEY''” can include spaces and other punctuation characters but there should not be any spaces either side of the equals sign as spaces are significant. If more than one entry has the same left-hand side, the last one to be encountered is the one that will be used.
</translate>

<translate>

The "''VALUE''" cannot include double-quote characters ("). To get a double-quote character you must use the HTML special character sequence "&quot;" instead. Single-quote characters (') are valid.
</translate>

<translate>

More information about the discussed changes for the Joomla 2.5 and 3.x series can be found on the page [[S:MyLanguage/Specification of language files|Specification of language files]]
</translate>

<noinclude>
----
<references/>
<translate>

[[Category:Tutorials]]
[[Category:Language Development]]
</translate>
</noinclude>

Retrieving request data using JInput

2015-09-06T00:16:43Z

Mvangeest: Fixed own incorrect edit (revision 68329): a single PHP object was meant (see revision 68300)

Retrieving request data using JInput

2015-09-05T17:53:19Z

Mvangeest: Adjusted version template

Retrieving request data using JInput

2015-09-05T17:33:59Z

Mvangeest: Added clarification after user request

Magic quotes and security

2015-03-10T14:54:36Z

Mvangeest: Adjusted layout

{{version|2.5,3.x}}
'''Magic Quotes''' was a PHP feature, enabled using the <code>magic_quotes_gpc</code> setting, that escaped (in a very limited way) most of the input data accessible to PHP scripts. It has been removed from PHP for [http://php.net/manual/en/security.magicquotes.whynot.php a variety of reasons]. For more on Magic Quotes, see [http://php.net/magic_quotes PHP Manual, Chapter 31. Magic Quotes].

This PHP feature has been '''deprecated''' as of PHP 5.3.0 (30-06-2009) and has been '''removed''' from PHP as of PHP 5.4.0.

: {{JVer|3.x}} Joomla! 3.0 and above requires <code>magic_quotes_gpc</code> to be set to '''off''' and will not install if <code>magic_quotes_gpc</code> is on.
: {{JVer|2.5}} Joomla! 2.5 advises <code>magic_quotes_gpc</code> to be set to '''off'''.

JRequest automatically takes into account the setting of <code>magic_quotes_gpc</code> and adjusts accordingly. If developers are using JRequest to request input then the actual value of the setting doesn't matter. If developers aren't using it then they will have to take the setting of <code>magic_quotes_gpc</code> into account (for this reason it is still common practice for developers to use JRequest in Joomla 2.5 - even though it is deprecated).

JInput does not take this into account. However, due to Joomla 3.x and higher requiring that magic quotes are disabled, this is no longer a problem.


[[Category:Security Checklist]]

Magic quotes and security

2015-03-10T14:52:23Z

Mvangeest: Fixed minor issues

{{version|2.5,3.x}}

'''Magic Quotes''' was a PHP feature, enabled using the <code>magic_quotes_gpc</code> setting, that escaped (in a very limited way) most of the input data accessible to PHP scripts. It has been removed from PHP for [http://php.net/manual/en/security.magicquotes.whynot.php a variety of reasons]. For more on Magic Quotes, see [http://php.net/magic_quotes PHP Manual, Chapter 31. Magic Quotes].

'''''This PHP feature has been deprecated as of PHP 5.3.0 (30-06-2009) and has been removed from PHP as of PHP 5.4.0.'''''

: {{JVer|3.x}} Joomla! 3.0 and above requires <code>magic_quotes_gpc</code> to be set to '''off''' and will not install if <code>magic_quotes_gpc</code> is on.
: {{JVer|2.5}} Joomla! 2.5 advises <code>magic_quotes_gpc</code> to be set to '''off'''.

JRequest automatically takes into account the setting of <code>magic_quotes_gpc</code> and adjusts accordingly. If developers are using JRequest to request input then the actual value of the setting doesn't matter. If developers aren't using it then they will have to take the setting of <code>magic_quotes_gpc</code> into account (for this reason it is still common practice for developers to use JRequest in Joomla 2.5 - even though it is deprecated).

JInput does not take this into account. However, due to Joomla 3.x and higher requiring that magic quotes are disabled, this is no longer a problem.


[[Category:Security Checklist]]

J2.5:Supporting SEF URLs in your component

2015-03-01T20:43:37Z

Mvangeest: Fixed minor issues

{{version/tutor|2.5,3.1}}
{{:Search Engine Friendly URLs/en}}
In Joomla!, each [[component]] is responsible for handling its own SEF URLs. Therefore, as the [[Developers|developer]] of a component, you will have to create your own '''router''' to allow your component to use SEF URLs.

'''''{{JVer|3.3}} Note:''''' Since Joomla 3.3, one should rather implement the interface <code>[https://api.joomla.org/cms-3/classes/JComponentRouterInterface.html JComponentRouterInterface]</code> and handle the routing and parsing similar as below, but via the methods of this interface. This will also evade the now fixed [https://github.com/joomla/joomla-cms/issues/5579 one way dash-to-colon issue].

== The Concept ==

Assuming you are following standard development practices, your component is probably using "system URLs" that look a lot like <tt><nowiki>http://www.example.com/index.php?option=com_yourcomponent&view=article&id=1&catid=20&Itemid=50</nowiki></tt>, and your goal is to transform this into <tt><nowiki>http://www.example.com/example-menu-item/20/1</nowiki></tt>. As the developer, you have two tasks: signalling the system that certain pieces of text are URLs and need to be transformed, and explaining the system how to transform URLs.

=== Applying <code>JRoute::_</code> ===

It is difficult and inefficient for Joomla! to figure out which parts of your component's output are URLs. To support SEF URLs, you will need to change URL-generating code so that it applies <code>JRoute::_</code> before outputting the URL:

<source lang="php">
echo JRoute::_('index.php?view=article&id=1&catid=20');
</source>

Notice that it is possible to leave out the parameters <code>option</code> and <code>Itemid</code>. <code>option</code> defaults to the name of the component currently being executed, and <code>Itemid</code> defaults to the current menu item's ID.

In general, you should only apply this to URLs that users and/or search engines are able to see. For example, there is no need to transform URLs used in redirects that immediately result in other redirects.

If the user turns off SEF URLs in the site's settings, <code>JRoute::_</code> will produce working non-SEF URLs without any changes to the code.

=== Writing a router ===

You'll also need to write a router, which is a single file with two functions that convert system URLs to and from SEF URLs. This file needs to be placed at <tt>/components/com_yourcomponent/router.php</tt>.

The first function, <code>[componentname]BuildRoute(&$query)</code>, must transform an array of URL parameters into an array of segments that will form the SEF URL. Schematically, the transformation works as follows:

:<tt><nowiki>http://www.example.com/index.php?option=com_yourcomponent&view=article&id=1&catid=20&Itemid=50</nowiki></tt>

::<span style="font-size: xx-large">↓</span> <code>JRoute::_</code>, called by your component or any other extension

:<code>$query = array('view' => 'article', 'id' => 1, 'catid' => 20)</code>

::<span style="font-size: xx-large">↓</span> Your router's <code>com_yourcomponentBuildRoute</code>

:<code>$segments = array(20, 1);</code>

::<span style="font-size: xx-large">↓</span> Joomla's internal route building (for display)

:<tt><nowiki>http://www.example.com/example-menu-item/20/1</nowiki></tt>

The second function, <code>[componentname]ParseRoute($segments)</code>, must transform an array of segments back into an array of URL parameters. Schematically:

:<tt><nowiki>http://www.example.com/example-menu-item/20/1</nowiki></tt>

::<span style="font-size: xx-large">↓</span> Joomla's internal route parsing

:<code>$segments = array(20, 1);</code>

::<span style="font-size: xx-large">↓</span> Your router's <code>com_yourcomponentParseRoute</code>

:<code>$query = array('view' => 'article', 'id' => 1, 'catid' => 20)</code>

The two functions must cooperate in such a way that the original URL can be reconstructed. You can think of <code>BuildRoute</code> as a form of [[wikipedia:Encoding|encoding]] and <code>ParseRoute</code> as the corresponding decoding. When the original URL isn't properly reproduced, your component will stop working.

== Preparing Your Data for Routing ==

Clearly, any URL format needs to contain some kind of information that identifies the data you want to show. If your system URLs look like <tt><nowiki>http://www.example.com/index.php?option=com_yourcomponent&view=article&id=1&catid=20&Itemid=50</nowiki></tt>, that information is currently the <tt>id</tt> URL parameter (<tt>id=1</tt>). You probably want your SEF URLs to contain a textual description of the data they point to. In Joomla!, this is usually done by giving your users a way to enter an '''alias''' to be used in the URL.

=== The Alias ===

Even if your users can enter an alias, they might not do so, leaving the generation of a sensible alias up to your component. If your data has a title field, you can use that as a candidate for the alias (like the core [[Content]] component does).

Considering that the alias will be used in URLs, it has to be URL safe. Joomla! provides a method making arbitrary strings URI safe, which includes replacing accented UTF8 characters by their ASCII7 equivalents, white spaces by hyphens, etc. Whether the user entered the alias or a candidate has been chosen automatically, you should ensure that the above requirements for a URL safe alias are met. A good place for implementing this, if you are using <code>JTable</code>, is the <code>JTable::check()</code> method, which is called during the save process. Have a look at this example code:

<source lang="php">

function check()
{
jimport('joomla.filter.output');
if (empty($this->alias))
{
$this->alias = $this->title;
}
$this->alias = JFilterOutput::stringURLSafe($this->alias);

/* All your other checks */
return true;
}
</source>

If the alias field is empty the title is used as alias. Then the alias is made URL safe using the <code>JFilterOutput::stringURLSafe()</code> method.

=== The Slug ===

A '''slug''' is used to minimise the amount of code you need to support SEF URLs. It consists of the numerical identifier (<tt>id</tt>) your system URLs used, a colon (<tt>:</tt>), and the alias you created as described above.

Consider a SEF URL for an [[Article]] with <tt>id</tt> 1 and title "Welcome to Joomla!". The automatically generated alias for this article is <tt>welcome-to-joomla</tt>, and the slug becomes <tt>1:welcome-to-joomla</tt>. In the [[Content]] component, the two elements are combined during the database query in the model (<code>a</code> represents <code>#__content</code>):

<source lang="php">$query = 'SELECT a.*, '.
'CASE WHEN CHAR_LENGTH(a.alias) THEN CONCAT_WS(":", a.id, a.alias) ELSE a.id END as slug,'
/*...*/;</source>

The advantage of this method of creating a slug is that you can simply use the slug as a drop-in replacement for the id in most places. For example, you don't need to check for and remove the colon and the alias from the request data manually: if you use [[Retrieving request data using JInput|JInput]]'s <code>int</code> (integer) filter, it will do that automatically.

== Routing URLs ==

The <code>JRoute::_</code> method translates the internal Joomla! URL to a custom URL. <code>JRoute::_</code> has three parameters and its prototype is:

<source lang="php">JRoute::_($url, $xhtml = true, $ssl = null);</source>

Where:

* <code>$url</code> is a string containing the absolute or relative internal Joomla! URL.
* <code>$xhtml</code> is a boolean value that specifies whether or not the output should be in XHTML. This parameter is optional and if omitted defaults to true.
* <code>$ssl</code> is an integer value that specifies whether the URI should be secure. It should be set to 1 to force the URI to be secure using the global secure site URI, 0 to leave it in the same state as when it was passed, and -1 to force the URI to be unsecure using the global unsecure site URI.

The most important parameter is <code>$url</code>. A call to this method might look like:

<source lang="php">JRoute::_('index.php?view=article&id=' . $row->slug);</source>

<code>$row->slug</code> is the value that was generated in step 2 from a combination of id and title alias.

Another advantage of using <code>JRoute::_</code> is that the router now handles <code>$option</code> (the component name) and the <code>$Itemid</code> (the menu item ID). The component itself doesn't have to know its name (<code>$option</code>) or the active menu item (<code>$Itemid</code>) like it did in previous version of Joomla!.

It is important that you think about the sequence of the URL parameter in this stage. This will be more clear when we have a deeper look at the <tt>router.php</tt> in the next section.

The building process of JRouter is divided into two steps:

* Create the application route. The application route is fully handled by JRouter and the component developer doesn’t have to do anything to make it work.
* Create the component route. To create the component route, JRouter looks for the <tt>router.php</tt> in the component directory which is responsible for building the route for the component.

== The Component Router ==

We will have two functions in the <tt>router.php</tt>. One is responsible for building the URL and the other is responsible for parsing it. In the next examples, a very basic and a more advanced one, we assume that we have three views that links can point to. The first is a categories overview (<code>view=categories</code>), the second is a single category (<code>view=category</code>) and the third is a single article (<code>view=article</code>).

The file <tt>router.php</tt> should be in the site area of your component. It is not used on admin/backend pages. Don't forget to add it to your XML [[Manifest files|manifest file]] in the site folder.

=== A Simple Example ===

This simple example will illustrate the basics of implementing a router for your component.

<source lang="php">
function [componentname]BuildRoute(&$query)
{
$segments = array();
if (isset($query['view']))
{
$segments[] = $query['view'];
unset($query['view']);
}
if (isset($query['id']))
{
$segments[] = $query['id'];
unset($query['id']);
};
return $segments;
}

</source>

<code>JRouter</code> passes a <code>$query</code> array to the <code>[''componentname'']BuildRoute</code> function. This function will add the relevant parts of the array to the $segments array in the right order and will return the properly ordered array. The content of the <code>$query</code> array needs to be unset, otherwise <code>JRouter</code> will add it to the URL in the form of a query string (i.e. any variables that are not handled by the router will be passed in the query string).

The prefix ''componentname'' is the name for your component, as found in the directory holding the component's files. For instance, a component "Magic" in directory <tt>/components/com_magic/...</tt> would use a prefix <code>magic</code> (all lower case).

The next function in the <tt>router.php</tt> parses the URL:

<source lang="php">
function [componentname]ParseRoute($segments)
{
$vars = array();
switch($segments[0])
{
case 'categories':
$vars['view'] = 'categories';
break;
case 'category':
$vars['view'] = 'category';
$id = explode(':', $segments[1]);
$vars['id'] = (int) $id[0];
break;
case 'article':
$vars['view'] = 'article';
$id = explode(':', $segments[1]);
$vars['id'] = (int) $id[0];
break;
}
return $vars;
}
</source>

What happens here? In the function <code>[''componentname'']BuildRoute</code> we arranged the items in the <code>$query</code> array in a specific sequence. This means that in this example the view is first and the id is second in the array.

By reading <code>$segments[0]</code>, we access the name of the view. We set the right view and/or identifier depending on its value and we return the <code>$vars</code> array to <code>JRouter</code>. <code>$vars</code> should be an associative array similar to the array that was passed to the BuildRoute method.

The above example of the <tt>router.php</tt> is a very simple way to generate SEF URLs but should show how this works quite clearly.

The generated URL in this example contains the name of the view and doesn't reflect the content hierarchy:

<tt><nowiki>http://www.example.com/[menualias]/[view]/[slug]</nowiki></tt>

=== A More Advanced Example ===

In the next example we will try to get rid of the need for the view and we will try to reflect the current hierarchy level in the URL.

The goal is URL's that look like:

* When viewing an article: <tt><nowiki>http://www.example.com/[menualias]/[category]/[article]</nowiki></tt>
* When viewing a category: <tt><nowiki>http://www.example.com/[menualias]/[category]</nowiki></tt>
* When viewing the categories overview: <tt><nowiki>http://www.example.com/[menualias]</nowiki></tt>

Let's assume we have done step 1 and 2 also for the category.

The link to the article would look like this:

<source lang="php">
JRoute::_('index.php?view=article&catid=' . $row->catslug . '&id='.$row->slug);
</source>

And the Link to the category would look like this:

<source lang="php">
JRoute::_('index.php?view=category&id=' . $row->catslug);
</source>

The corresponding <tt>router.php</tt>:

<source lang="php">

function [componentname]BuildRoute(&$query)
{
$segments = array();
if (isset($query['catid']))
{
$segments[] = $query['catid'];
unset($query['catid']);
};
if (isset($query['id']))
{
$segments[] = $query['id'];
unset($query['id']);
};
unset($query['view']);
return $segments;
}
</source>

The difference now is that we don’t add the name of the view to the <code>$segments</code> array. We still unset the view key since otherwise, <code>JRouter</code> would add it to the URL as part of the query string. Another new thing here is the additional parameter catid that we push into the <code>$segments</code> array.

<source lang="php">
function [componentname]ParseRoute($segments)
{
$vars = array();
$app = JFactory::getApplication();
$menu = $app->getMenu();
$item = $menu->getActive();
// Count segments
$count = count($segments);
// Handle View and Identifier
switch ($item->query['view'])
{
case 'categories':
if ($count == 1)
{
$vars['view'] = 'category';
}
if ($count == 2)
{
$vars['view'] = 'article';
}
$id = explode(':', $segments[$count-1]);
$vars['id'] = (int) $id[0];
break;
case 'category':
$id = explode(':', $segments[$count-1]);
$vars['id'] = (int) $id[0];
$vars['view'] = 'article';
break;
}
return $vars;
}
</source>

You can see that this ParseRoute function has a lot of different code parts in comparison to the previous. The reason for this is simple. We don’t have the name of the view in the <code>$segments</code> array and we need to find another way to determine it.

We need to find out which level of hierarchy we are in by receiving the root element. We do this by looking to the view name of the active menu item:

<source lang="php">
$item->query['view']
</source>

Also we need to know the number of items in the <code>$segments</code> array:

<source lang="php">
$count = count($segments);
</source>

With this information we can correctly set the view for all possible three cases:

* The menu item is a link to the categories view and the <code>$segments</code> array has two items (<code>$catid</code> and <code>$id</code>). In this case we know that we need to parse a link to an article.
* The menu item is a link to the categories view and the <code>$segments</code> array has one item (<code>$id</code>). In this case we know that we need to parse a link to a category.
* The menu item is a link to a category. In this case, we know that any item in the <code>$segments</code> array is the identifier for an article.

The result of all this code is clean and human-readable component URLs.

== Routers and Menu Items ==

A last important part of creating a router is considering what to do with menu items. As explained on [[Search Engine Friendly URLs]], the output of the component router is used ''after'' the first segment of a route, the first segment being the menu item's alias. This creates a difficult question: how is your router and/or other code to know which menu item to route through?

Suppose, for example, that your component is currently producing output for the page <tt>/dogs</tt>, which lists all dogs in the system. Of course, the items in the list need to be links to pages that display more details about one dog. What should the URL to the dog with ID 21 and name Fido become? Using a router that works according to the principles we've seen so far, the route that is produced is <tt>dogs/21-fido</tt>, or with some additional work <tt>/dogs/fido</tt>. But perhaps the user has created a menu item with the alias <tt>mydoggy</tt> which displays exactly that dog's details. Then it is probably the user's intention to route this URL through that menu item, and the item in the list should link to the page <tt>/mydoggy</tt>.

More generally, whenever you are building a route, you will need to find the menu item that is most suitable as a ''starting point'' for building your route. The term ''starting point'' is emphasized because the rest of the route depends on the configuration of the menu item. In our example above, <tt>/dogs/21-fido</tt> is an acceptable route, <tt>/mydoggy</tt> is arguably even better, but <tt>/mydoggy/21-fido</tt> is simply wrong, since <tt>/mydoggy</tt> is in itself a menu item that is set up to display <tt>fido</tt>'s information.

Several approaches are available to tackle this problem. Joomla!'s core components take a mixed approach, separating responsibilities in two units of code: the router itself and the so-called <code>[componentname]RouteHelper</code>. The <code>[componentname]RouteHelper</code> provides methods that find the most suitable menu item for a given piece of data to be displayed, while the router analyzes the menu item and puts any information that is not determined by the menu item's configuration into the route. This does mean that the ''calling code'' must explicitly call the helper's method before routing (<code>echo JRoute::_(DogsRouteHelper::getDogRoute(21));</code>).

== See Also ==

There is a useful thread on this subject here: [[jtopic:148632]] (note, may be out of date)

For details on the internals of routing, see [[Routing implementation details]].
<noinclude>[[Category:Tutorials]][[Category:Component Development]][[Category:Search Engine Friendly URLs]]</noinclude>

Manifest files

2014-08-29T12:25:28Z

Mvangeest: /* SQL */ Removed nonexistent attributes

{{version|2.5,3.x}}

Within Joomla there are manifest files for all of the extensions. These files include the general installation information as well as parameters for the configuration of the [[extension]] itself. Since Joomla! 2.5 {{JVer|2.5}}, there are very few differences between the manifest file formats for the different [[Extension types (technical definitions)|types of extensions]], allowing each type to access the full power of the Joomla! installer.

==Naming conventions==
The file must be named <tt>manifest.xml</tt> or <tt><extension_name>.xml</tt> and located in the root directory of the installation package.

==Syntax==

=== Root element ===
The primary tag of the installation file is:
<source lang=xml><extension></extension></source>

This starting and closing tags are now valid for all extensions. The new tag <code><extension></code> replaces the old <code><install></install></code> from Joomla {{JVer|1.5}}. The following attributes are allowed within the tag:

{|class="wikitable"
|-
! style="width: 150px" | Attribute || style="width: 150px" | Values || Applicable to || Description
|-
| type || <code>component</code><br /><code>file</code><br /><code>language</code><br /><code>library</code><br /><code>module</code><br /><code>package</code><br /><code>plugin</code><br /><code>template</code> || All extensions
| This attribute describes the type of the extension for the installer. Based on this type further requirements to sub-tags apply.
|-
| version
| <code>2.5</code><br /><code>3.0</code> || All extensions
| String that identifies the version of Joomla for which this extension is developed.
|-
| method
| <code>install</code><br /><code>upgrade</code> || All extensions
| The default value <code>install</code> will be also used if the method attribute is not used. The <code>install</code> value means the installer will gracefully stop if it finds any existing file/folder of the new extension.
|-
| client
| <code>site</code><br /><code>administrator</code> || Modules
| The client attribute allows you to specify for which application client the new module is available.
|-
| group
| ''string'' || Plugins
| The group name specifies for which group of plugins the new plugin is available. The existing groups are the folder names within the directory <tt>/plugins</tt>. The installer will create new folder names for group names that do not exist yet.
|}

=== Metadata ===

The following elements can be used to insert metadata. None of these elements are required; if they are present, they must be a child of the root element.

<pre>
<name> – raw component name (e.g. com_banners).
<author> – author's name (e.g. Joomla! Project)
<creationDate> – date of creation or release (e.g. April 2006)
<copyright> – a copyright statement (e.g. (C) 2005 - 2011 Open Source Matters. All rights reserved.)
<license> – a license statement (e.g. NU General Public License version 2 or later; see LICENSE.txt)
<authorEmail> – author's email address (e.g. admin@joomla.org)
<authorUrl> – URL to the author's website (e.g. www.joomla.org)
<version> – the version number of the extension (e.g. 1.6.0)
<description> – the description of the component. This is a translatable field. (e.g. COM_BANNERS_XML_DESCRIPTION)
</pre>

Note: The <name> and <description> tags are also translatable fields so that the name and description of the extension can be shown to the user in their native language.

=== Front-end files ===

<source lang="xml">
<files folder="from-folder">
<filename>example.php</filename>
<folder>examples</folder>
</files>
</source>

Files to copy to the front-end directory should be placed in the <code><files></code> element. You can use the optional <code>folder</code> attribute to specify a directory '''in the ZIP package''' to copy '''from'''. Each file to copy must be represented by a <code><filename></code> element. If you want to copy an entire folder at once, you can define it as a <code><folder></code>.

=== Media files ===

<source lang="xml>
<media folder="media" destination="com_example">
<filename>com_example_logo.png</filename>
<folder>css</folder>
<folder>js</folder>
</media>
</source>

This example will copy the file(s) (<tt>/media/com_example_logo.png</tt>) and folders ( <tt>/media/css/</tt> and <tt>/media/js/</tt> ) listed to <tt>/media/com_example/</tt>, creating the <tt>com_example</tt> folder if required. You can use the optional <code>folder</code> attribute to specify a directory '''in the ZIP package''' to copy '''from''' (in this case, <tt>media</tt>).

Extensions should be storing assets they need to be web accessible (JS, CSS, images etc) in <code>media</code>. Amongst other things this feature was added as step in the progression to multi-site support and the eventual move of code files (PHP) out of the web accessible areas of the server.

Ref:
* [https://groups.google.com/forum/#!msg/joomla-dev-cms/4CAASJqFY-k/PvPj14gP29EJ Google Groups - joomla-dev-cms thread]
* [https://groups.google.com/forum/#!msg/joomla-dev-cms/uNmhX98sKbE/p8p68Jke680J Google Groups - joomla-dev-cms thread]

=== Administration section ===

<source lang="xml">
<administration>

</administration>
</source>

The administration section is defined in the <code><administration></code> element. Since only [[Component|components]] apply to both the [[Site (Application)|site]] and the [[Administrator (Application)|administrator]], '''only component manifests can include this element'''.

==== Back-end files ====

Files to copy to the back-end directory should be placed in the <code><files></code> element under the <code><administration></code>. You can use the optional <code>folder</code> attribute to specify a directory '''in the ZIP package''' to copy '''from'''. See ''Front-end files'' for further rules.

==== Menu links and submenus ====

<source lang="xml">
<menu>COM_EXAMPLE</menu>
<submenu>
<menu link="anoption=avalue">COM_EXAMPLE_SUBMENU_ANOPTION</menu>
<menu view="viewname">COM_EXAMPLE_SUBMENU_VIEWNAME</menu>
</submenu>
</source>

The text for the main menu item for the component is defined in the <code><menu></code> item, a child of <code><administration></code>. A <code><submenu></code> element may also be present (also a child of <code><administration></code>), which may contain more menu items defined by <code><menu></code>.

Additionally, each <code><menu></code> item can define the following attributes:

{| class="wikitable"
! style="width: 150px" | Attribute || Description
|-
| link || A link to send the user to when the menu item is clicked
|-
| img || The (relative) path to an image (16x16 pixels) to appear beside the menu item.
<u>Must be an url compatible as a file too (e.g. no spaces) !</u>
|-
| alt ||
|-
| ''string'' || An URL parameter to add to the link. For example, <code><menu view="cpanel">COM_EXAMPLE</menu></code> in com_example's XML manifest would cause the URL of the menu item to be <tt>index.php?option=com_example&view=cpanel</tt>.
|-
|}

The value inside the tag is the menu's label. Unlike Joomla! 1.5, you can not use a natural language string. For example, if you would enter "Example Component" instead of COM_EXAMPLE, it would result in your component name appearing as example-component in the menu and you would be unable to provide a translation. In order to provide a translation you need to create a file named en-GB.com_example.sys.ini in administrator/languages/en-GB (you can use the manifest's <code><languages></code> tag to copy it during installation) or in administrator/components/com_example/language/en-GB. In the latter case, you must not include the translation file in the <code><languages></code> tag. As long as you have placed the language directory in your <code><files></code> tag, it will be copied along when the component is being installed.

The contents of that file should be:
<source>
COM_EXAMPLE="Example Component"
COM_EXAMPLE_SUBMENU_ANOPTION="Another Option"
COM_EXAMPLE_SUBMENU_VIEWNAME="Another View"

</source>

Please note that the language string must be enclosed in double quotes, as per Joomla!'s translation standards. Important note: Joomla! 1.6 and later sorts the Component menu items based on the actual translation of the key you supply in your XML manifest. This means that the sorting order is correct no matter what you call your translation key and no matter which language the site is being displayed in. Essentially, Joomla! 1.6 fixed the wrong sorting of the Components menu experienced under Joomla! 1.5 for the majority (non-English speaking!) of Joomla! users.

{{Needsinfo|In Platform 11.1 no alt attribute processed and if link provide in menu tag other provided attributes were ignore. The other tags are task, view, controller, act, layout, sub. Please confirm this, please.}}

=== Configuration ===
{{warning|Components '''do not support''' configuration definitions '''in the manifest'''. This is a way implemented in Joomla! 1.5. They can define configuration options for multiple levels using [[Component configuration metadata]].}}
The <code><config></code> element, a child of the root, describes the configuration options for the extension. If applicable, the options will be shown by the appropriate Manager (Plugin Manager, Module Manager or Template Manager). '''Configuration options can also be defined in a separate file named <code>config.xml</code>. Its root element should be <code><config></code>.'''

{{:XML JForm form definitions}}

=== SQL ===

<source lang="xml">
<install>
<sql>
<file driver="mysql" charset="utf8">sql/example.install.sql</file>
</sql>
</install>
<uninstall>
<sql>
<file driver="mysql" charset="utf8">sql/example.uninstall.sql</file>
</sql>
</uninstall>
</source>

In the above example, we put the SQL files in the <tt>admin/sql</tt> folder of the installation package. You have to include the <tt>sql</tt> folder in the administration files (as described in ''Back-end files'').

You can execute SQL during the installation and/or uninstallation using the <code><install></code> and <code><uninstall></code> elements, respectively. A <code><sql></code> element should appear as a child of these elements. <code><sql></code> can contain any number of <code><file></code> elements, each defining a single SQL file to execute. Their database driver types are described by the <code>driver</code> attribute, their character sets by the <code>charset</code> attribute.

==== Update of the SQL schema ====

<source lang="xml">
<update>
<schemas>
<schemapath type="mysql">sql/updates/mysql</schemapath>
<schemapath type="sqlsrv">sql/updates/sqlsrv</schemapath>
</schemas>
</update>
</source>

Since 1.6, there is also an <code><update></code> tag, which allows you to provide a series of SQL files to update the current schema.

=== Language files ===
In Joomla! 1.5, extension developers had to put extension language files in the Joomla! main language file, using the <languages>..</languages> tag as shown below. '''This method can still be used in''' {{rarr|2.5,3.x}}.

<source lang="xml">

<languages folder="langfiles">
<language tag="en-GB">en-GB.com_example.ini</language>
</languages>
</source>

Since Joomla! 1.6 it has been encouraged placing your extension's language files in your extension folder. Joomla! will then automatically load your extension's language files.

By storing extension language files in the extension folder, you gain the benefit of isolating and protecting your extension's language files. For example, an administrator removes a language from their Joomla! installation. Your extension's language files will not be removed. They will remain in place and will be available if the language is installed again.

The structure of the language folder for frontend and backend is the same. You put them in the language tag (e.g. '''en-GB''' ) of each language in your language folder i.e. '''language/en-GB/'''. You have to specify those folders in the front-end and back-end files too.

In your manifest you simply include the ''''language'''' folder in your files section, the sub-directories for each language automatically be copied. Inside the <files> group you simply add a <folder> element alongside the items in the '''<files>''' group as shown in this example:

<source lang="xml">
<files>
<filename plugin="alpha">alpha.php</filename>
<folder>sql</folder>
<folder>language</folder>
</files>
</source>

It is also notable that both ways can work together. Here is an example from core:
<source lang="xml">
<files>
<filename plugin="languagecode">languagecode.php</filename>
<filename>index.html</filename>
<folder>language</folder>
</files>
<languages>
<language tag="en-GB">language/en-GB/en-GB.plg_system_languagecode.ini</language>
<language tag="en-GB">language/en-GB/en-GB.plg_system_languagecode.sys.ini</language>
</languages>
</source>

The advantages of this solution are the following:

All ini files present in the core folder have precedence over the files in the extension language/ folder.
For example a sys.ini file will always be loaded from core folders in back-end if it exists, except when installing an extension which contains a sys.ini file in a language folder. In that case and only that case, the sys.ini file in the extension folder will display its translated content at install time. This is very handy as a developer can have 2 sys.ini files with different contents. A description of the successful install as well as a tutorial in back-end for example.

Also, it is much easier for a user needing an ini file for an extension that does not provide it in the language desired, to add it in the main folders. No risk for it to be deleted in case of uninstalling the extension by mistake or any other reason.

See also:
*[[J2.5:Making non-core language packs|Making non-core language packs]]
*[[Creating language packs for extensions in Joomla 2.5]]

During development you can turn on language debugging in the Joomla! global configuration. So you can investigate if a problems arises. As of 3.2, this is necessary to help debug as en-GB is '''always''' loaded first when not in debug mode to prevent displaying Constants.

=== Script file ===

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

An optional '''script file''' (PHP code that is run before, during and/or after installation, uninstallation and upgrading) can be defined using a <code><scriptfile></code> element. This file should contain a class named "<element_name>IntallerScript" where <element_name> is the name of your extension (e.g. com_componentname, mod_modulename, etc.). Plugins requires to state the group (e.g. plgsystempluginname). Library packages do not support scriptfiles. The structure of the class is as follows:

<source lang="php">

class com_componentnameInstallerScript
{
/**
* Constructor
*
* @param JAdapterInstance $adapter The object responsible for running this script
*/
public function __construct(JAdapterInstance $adapter);

/**
* Called before any type of action
*
* @param string $route Which action is happening (install|uninstall|discover_install|update)
* @param JAdapterInstance $adapter The object responsible for running this script
*
* @return boolean True on success
*/
public function preflight($route, JAdapterInstance $adapter);

/**
* Called after any type of action
*
* @param string $route Which action is happening (install|uninstall|discover_install|update)
* @param JAdapterInstance $adapter The object responsible for running this script
*
* @return boolean True on success
*/
public function postflight($route, JAdapterInstance $adapter);

/**
* Called on installation
*
* @param JAdapterInstance $adapter The object responsible for running this script
*
* @return boolean True on success
*/
public function install(JAdapterInstance $adapter);

/**
* Called on update
*
* @param JAdapterInstance $adapter The object responsible for running this script
*
* @return boolean True on success
*/
public function update(JAdapterInstance $adapter);

/**
* Called on uninstallation
*
* @param JAdapterInstance $adapter The object responsible for running this script
*/
public function uninstall(JAdapterInstance $adapter);
}

</source>

=== Update servers ===

<source lang="xml">
<updateservers>
<server type="extension" priority="1" name="Extension Update Site">http://example.com/extension.xml</server>
<server type="collection" priority="2" name="Collection Update Site">http://example.com/collection.xml</server>
</updateservers>
</source>

Update servers can be defined in the <code><updateservers></code> element, a child of the root. This element may contain one or more <code><server></code> element, each describing a location to fetch updates from. Each <code><server></code> item can define the following attributes:

{| class="wikitable"
! style="width: 150px" | Attribute || style="width: 150px" | Values || Description
|-
| type || <code>extension</code><br /><code>collection</code> || The update server type
|-
| priority || ''integer'' || The priority of the update server
|-
| name || ''string'' || The name of the update server
|}

More info:
* [[J2.5:Developing a MVC Component/Adding an update server|Building a Joomla! Extension - Adding an update server]]
* [[J2.5:Managing Component Updates|Managing Component Updates in Joomla 2.5]]

== Examples ==
For a real-life example, see [https://github.com/joomla/joomla-cms/blob/2.5.x/administrator/components/com_banners/banners.xml the manifest of the Banner component in the latest version of Joomla! 2.5].

The Joomla testing process uses several extensions to test whether the installer works correctly. The latest versions of the manifests of these extensions are:

* [http://svn.joomla.org/project/cms/development/trunk/tests/_data/installer_packages/com_alpha/alpha.xml com_alpha manifest]
* [http://svn.joomla.org/project/cms/development/trunk/tests/_data/installer_packages/mod_alpha/mod_alpha.xml mod_alpha manifest]
* [http://svn.joomla.org/project/cms/development/trunk/tests/_data/installer_packages/plg_system_alpha/alpha.xml plg_system_alpha manifest]
* [http://svn.joomla.org/project/cms/development/trunk/tests/_data/installer_packages/tpl_simple/templateDetails.xml tpl_simple manifest]
* [http://svn.joomla.org/project/cms/development/trunk/tests/_data/installer_packages/lng_xx-XX/xx-XX.xml lng_xx-XX manifest]

== Contributors ==
*[[User:akede|Alex Kempkens]]
*[[User:dperaza|Daniel Peraza]]
*[[User:nikosdion|Nicholas K. Dionysopoulos]]
*[[User:mrs.siam|Prasit Gebsaap]]
*[[User:cppl|Craig Phillips]]

[[Category:Extension development]]
[[Category:Specifications]]

J2.5:Supporting SEF URLs in your component

2014-08-28T22:22:01Z

Mvangeest: /* Preparing Your Data for Routing */

{{version/tutor|2.5,3.1}}
{{:Search Engine Friendly URLs}}
In Joomla!, each [[component]] is responsible for handling its own SEF URLs. Therefore, as the [[Developers|developer]] of a component, you will have to create your own '''router''' to allow your component to use SEF URLs.

== The Concept ==

Assuming you are following standard development practices, your component is probably using "system URLs" that look a lot like <tt><nowiki>http://www.example.com/index.php?option=com_yourcomponent&view=article&id=1&catid=20&Itemid=50</nowiki></tt>, and your goal is to transform this into <tt><nowiki>http://www.example.com/example-menu-item/20/1</nowiki></tt>. As the developer, you have two tasks: signalling the system that certain pieces of text are URLs and need to be transformed, and explaining the system how to transform URLs.

=== Applying <code>JRoute::_</code> ===

It is difficult and inefficient for Joomla! to figure out which parts of your component's output are URLs. To support SEF URLs, you will need to change URL-generating code so that it applies <code>JRoute::_</code> before outputting the URL:

<source lang="php">
echo JRoute::_('index.php?view=article&id=1&catid=20');
</source>

Notice that it is possible to leave out the parameters <code>option</code> and <code>Itemid</code>. <code>option</code> defaults to the name of the component currently being executed, and <code>Itemid</code> defaults to the current menu item's ID.

In general, you should only apply this to URLs that users and/or search engines are able to see. For example, there is no need to transform URLs used in redirects that immediately result in other redirects.

If the user turns off SEF URLs in the site's settings, <code>JRoute::_</code> will produce working non-SEF URLs without any changes to the code.

=== Writing a router ===

You'll also need to write a router, which is a single file with two functions that convert system URLs to and from SEF URLs. This file needs to be placed at <tt>/components/com_yourcomponent/router.php</tt>.

The first function, <code>[componentname]BuildRoute(&$query)</code>, must transform an array of URL parameters into an array of segments that will form the SEF URL. Schematically, the transformation works as follows:

:<tt><nowiki>http://www.example.com/index.php?option=com_yourcomponent&view=article&id=1&catid=20&Itemid=50</nowiki></tt>

::<span style="font-size: xx-large">↓</span> <code>JRoute::_</code>, called by your component or any other extension

:<code>$query = array('view' => 'article', 'id' => 1, 'catid' => 20)</code>

::<span style="font-size: xx-large">↓</span> Your router's <code>com_yourcomponentBuildRoute</code>

:<code>$segments = array(20, 1);</code>

::<span style="font-size: xx-large">↓</span> Joomla's internal route building (for display)

:<tt><nowiki>http://www.example.com/example-menu-item/20/1</nowiki></tt>

The second function, <code>[componentname]ParseRoute($segments)</code>, must transform an array of segments back into an array of URL parameters. Schematically:

:<tt><nowiki>http://www.example.com/example-menu-item/20/1</nowiki></tt>

::<span style="font-size: xx-large">↓</span> Joomla's internal route parsing

:<code>$segments = array(20, 1);</code>

::<span style="font-size: xx-large">↓</span> Your router's <code>com_yourcomponentParseRoute</code>

:<code>$query = array('view' => 'article', 'id' => 1, 'catid' => 20)</code>

The two functions must cooperate in such a way that the original URL can be reconstructed. You can think of <code>BuildRoute</code> as a form of [[wikipedia:Encoding|encoding]] and <code>ParseRoute</code> as the corresponding decoding. When the original URL isn't properly reproduced, your component will stop working.

== Preparing Your Data for Routing ==

Clearly, any URL format needs to contain some kind of information that identifies the data you want to show. If your system URLs look like <tt><nowiki>http://www.example.com/index.php?option=com_yourcomponent&view=article&id=1&catid=20&Itemid=50</nowiki></tt>, that information is currently the <tt>id</tt> URL parameter (<tt>id=1</tt>). You probably want your SEF URLs to contain a textual description of the data they point to. In Joomla!, this is usually done by giving your users a way to enter an '''alias''' to be used in the URL.

=== The Alias ===

Even if your users can enter an alias, they might not do so, leaving the generation of a sensible alias up to your component. If your data has a title field, you can use that as a candidate for the alias (like the core [[Content]] component does).

Considering that the alias will be used in URLs, it has to be URL safe. Joomla! provides a method making arbitrary strings URI safe, which includes replacing accented UTF8 characters by their ASCII7 equivalents, white spaces by hyphens, etc. Whether the user entered the alias or a candidate has been chosen automatically, you should ensure that the above requirements for a URL safe alias are met. A good place for implementing this, if you are using <code>JTable</code>, is the <code>JTable::check()</code> method, which is called during the save process. Have a look at this example code:

<source lang="php">

function check()
{
jimport('joomla.filter.output');
if (empty($this->alias))
{
$this->alias = $this->title;
}
$this->alias = JFilterOutput::stringURLSafe($this->alias);

/* All your other checks */
return true;
}
</source>

If the alias field is empty the title is used as alias. Then the alias is made URL safe using the <code>JFilterOutput::stringURLSafe()</code> method.

=== The Slug ===

A '''slug''' is used to minimise the amount of code you need to support SEF URLs. It consists of the numerical identifier (<tt>id</tt>) your system URLs used, a colon (<tt>:</tt>), and the alias you created as described above.

Consider a SEF URL for an [[Article]] with <tt>id</tt> 1 and title "Welcome to Joomla!". The automatically generated alias for this article is <tt>welcome-to-joomla</tt>, and the slug becomes <tt>1:welcome-to-joomla</tt>. In the [[Content]] component, the two elements are combined during the database query in the model (<code>a</code> represents <code>#__content</code>):

<source lang="php">$query = 'SELECT a.*, '.
'CASE WHEN CHAR_LENGTH(a.alias) THEN CONCAT_WS(":", a.id, a.alias) ELSE a.id END as slug,'
/*...*/;</source>

The advantage of this method of creating a slug is that you can simply use the slug as a drop-in replacement for the id in most places. For example, you don't need to check for and remove the colon and the alias from the request data manually: if you use [[Retrieving request data using JInput|JInput]]'s <code>int</code> (integer) filter, it will do that automatically.

== Routing URLs ==

The <code>JRoute::_</code> method translates the internal Joomla! URL to a custom URL. <code>JRoute::_</code> has three parameters and its prototype is:

<source lang="php">JRoute::_($url, $xhtml = true, $ssl = null);</source>

Where:

* <code>$url</code> is a string containing the absolute or relative internal Joomla! URL.
* <code>$xhtml</code> is a boolean value that specifies whether or not the output should be in XHTML. This parameter is optional and if omitted defaults to true.
* <code>$ssl</code> is an integer value that specifies whether the URI should be secure. It should be set to 1 to force the URI to be secure using the global secure site URI, 0 to leave it in the same state as when it was passed, and -1 to force the URI to be unsecure using the global unsecure site URI.

The most important parameter is <code>$url</code>. A call to this method might look like:

<source lang="php">JRoute::_('index.php?view=article&id=' . $row->slug);</source>

<code>$row->slug</code> is the value that was generated in step 2 from a combination of id and title alias.

Another advantage of using <code>JRoute::_</code> is that the router now handles <code>$option</code> (the component name) and the <code>$Itemid</code> (the menu item ID). The component itself doesn't have to know its name (<code>$option</code>) or the active menu item (<code>$Itemid</code>) like it did in previous version of Joomla!.

It is important that you think about the sequence of the URL parameter in this stage. This will be more clear when we have a deeper look at the <tt>router.php</tt> in the next section.

The building process of JRouter is divided into two steps:

* Create the application route. The application route is fully handled by JRouter and the component developer doesn’t have to do anything to make it work.
* Create the component route. To create the component route, JRouter looks for the <tt>router.php</tt> in the component directory which is responsible for building the route for the component.

== The Component Router ==

We will have two functions in the <tt>router.php</tt>. One is responsible for building the URL and the other is responsible for parsing it. In the next examples, a very basic and a more advanced one, we assume that we have three views that links can point to. The first is a categories overview (<code>view=categories</code>), the second is a single category (<code>view=category</code>) and the third is a single article (<code>view=article</code>).

The file <tt>router.php</tt> should be in the site area of your component. It is not used on admin/backend pages. Don't forget to add it to your XML [[Manifest files|manifest file]] in the site folder.

=== A Simple Example ===

This simple example will illustrate the basics of implementing a router for your component.

<source lang="php">
function [componentname]BuildRoute(&$query)
{
$segments = array();
if (isset($query['view']))
{
$segments[] = $query['view'];
unset($query['view']);
}
if (isset($query['id']))
{
$segments[] = $query['id'];
unset($query['id']);
};
return $segments;
}

</source>

<code>JRouter</code> passes a <code>$query</code> array to the <code>[''componentname'']BuildRoute</code> function. This function will add the relevant parts of the array to the $segments array in the right order and will return the properly ordered array. The content of the <code>$query</code> array needs to be unset, otherwise <code>JRouter</code> will add it to the URL in the form of a query string (i.e. any variables that are not handled by the router will be passed in the query string).

The prefix ''componentname'' is the name for your component, as found in the directory holding the component's files. For instance, a component "Magic" in directory <tt>/components/com_magic/...</tt> would use a prefix <code>magic</code> (all lower case).

The next function in the <tt>router.php</tt> parses the URL:

<source lang="php">
function [componentname]ParseRoute($segments)
{
$vars = array();
switch($segments[0])
{
case 'categories':
$vars['view'] = 'categories';
break;
case 'category':
$vars['view'] = 'category';
$id = explode(':', $segments[1]);
$vars['id'] = (int) $id[0];
break;
case 'article':
$vars['view'] = 'article';
$id = explode(':', $segments[1]);
$vars['id'] = (int) $id[0];
break;
}
return $vars;
}
</source>

What happens here? In the function <code>[''componentname'']BuildRoute</code> we arranged the items in the <code>$query</code> array in a specific sequence. This means that in this example the view is first and the id is second in the array.

By reading <code>$segments[0]</code>, we access the name of the view. We set the right view and/or identifier depending on its value and we return the <code>$vars</code> array to <code>JRouter</code>. <code>$vars</code> should be an associative array similar to the array that was passed to the BuildRoute method.

The above example of the <tt>router.php</tt> is a very simple way to generate SEF URLs but should show how this works quite clearly.

The generated URL in this example contains the name of the view and doesn't reflect the content hierarchy:

<tt><nowiki>http://www.example.com/[menualias]/[view]/[slug]</nowiki></tt>

=== A More Advanced Example ===

In the next example we will try to get rid of the need for the view and we will try to reflect the current hierarchy level in the URL.

The goal is URL's that look like:

* When viewing an article: <tt><nowiki>http://www.example.com/[menualias]/[category]/[article]</nowiki></tt>
* When viewing a category: <tt><nowiki>http://www.example.com/[menualias]/[category]</nowiki></tt>
* When viewing the categories overview: <tt><nowiki>http://www.example.com/[menualias]</nowiki></tt>

Let's assume we have done step 1 and 2 also for the category.

The link to the article would look like this:

<source lang="php">
JRoute::_('index.php?view=article&catid=' . $row->catslug . '&id='.$row->slug);
</source>

And the Link to the category would look like this:

<source lang="php">
JRoute::_('index.php?view=category&id=' . $row->catslug);
</source>

The corresponding <tt>router.php</tt>:

<source lang="php">

function [componentname]BuildRoute(&$query)
{
$segments = array();
if (isset($query['catid']))
{
$segments[] = $query['catid'];
unset($query['catid']);
};
if (isset($query['id']))
{
$segments[] = $query['id'];
unset($query['id']);
};
unset($query['view']);
return $segments;
}
</source>

The difference now is that we don’t add the name of the view to the <code>$segments</code> array. We still unset the view key since otherwise, <code>JRouter</code> would add it to the URL as part of the query string. Another new thing here is the additional parameter catid that we push into the <code>$segments</code> array.

<source lang="php">
function [componentname]ParseRoute($segments)
{
$vars = array();
$app = JFactory::getApplication();
$menu = $app->getMenu();
$item = $menu->getActive();
// Count segments
$count = count($segments);
// Handle View and Identifier
switch ($item->query['view'])
{
case 'categories':
if ($count == 1)
{
$vars['view'] = 'category';
}
if ($count == 2)
{
$vars['view'] = 'article';
}
$id = explode(':', $segments[$count-1]);
$vars['id'] = (int) $id[0];
break;
case 'category':
$id = explode(':', $segments[$count-1]);
$vars['id'] = (int) $id[0];
$vars['view'] = 'article';
break;
}
return $vars;
}
</source>

You can see that this ParseRoute function has a lot of different code parts in comparison to the previous. The reason for this is simple. We don’t have the name of the view in the <code>$segments</code> array and we need to find another way to determine it.

We need to find out which level of hierarchy we are in by receiving the root element. We do this by looking to the view name of the active menu item:

<source lang="php">
$item->query['view']
</source>

Also we need to know the number of items in the <code>$segments</code> array:

<source lang="php">
$count = count($segments);
</source>

With this information we can correctly set the view for all possible three cases:

* The menu item is a link to the categories view and the <code>$segments</code> array has two items (<code>$catid</code> and <code>$id</code>). In this case we know that we need to parse a link to an article.
* The menu item is a link to the categories view and the <code>$segments</code> array has one item (<code>$id</code>). In this case we know that we need to parse a link to a category.
* The menu item is a link to a category. In this case, we know that any item in the <code>$segments</code> array is the identifier for an article.

The result of all this code is clean and human-readable component URLs.

== Routers and Menu Items ==

A last important part of creating a router is considering what to do with menu items. As explained on [[Search Engine Friendly URLs]], the output of the component router is used ''after'' the first segment of a route, the first segment being the menu item's alias. This creates a difficult question: how is your router and/or other code to know which menu item to route through?

Suppose, for example, that your component is currently producing output for the page <tt>/dogs</tt>, which lists all dogs in the system. Of course, the items in the list need to be links to pages that display more details about one dog. What should the URL to the dog with ID 21 and name Fido become? Using a router that works according to the principles we've seen so far, the route that is produced is <tt>dogs/21-fido</tt>, or with some additional work <tt>/dogs/fido</tt>. But perhaps the user has created a menu item with the alias <tt>mydoggy</tt> which displays exactly that dog's details. Then it is probably the user's intention to route this URL through that menu item, and the item in the list should link to the page <tt>/mydoggy</tt>.

More generally, whenever you are building a route, you will need to find the menu item that is most suitable as a ''starting point'' for building your route. The term ''starting point'' is emphasized because the rest of the route depends on the configuration of the menu item. In our example above, <tt>/dogs/21-fido</tt> is an acceptable route, <tt>/mydoggy</tt> is arguably even better, but <tt>/mydoggy/21-fido</tt> is simply wrong, since <tt>/mydoggy</tt> is in itself a menu item that is set up to display <tt>fido</tt>'s information.

Several approaches are available to tackle this problem. Joomla!'s core components take a mixed approach, separating responsibilities in two units of code: the router itself and the so-called <code>[componentname]RouteHelper</code>. The <code>[componentname]RouteHelper</code> provides methods that find the most suitable menu item for a given piece of data to be displayed, while the router analyzes the menu item and puts any information that is not determined by the menu item's configuration into the route. This does mean that the ''calling code'' must explicitly call the helper's method before routing (<code>echo JRoute::_(DogsRouteHelper::getDogRoute(21));</code>).

== See Also ==

There is a useful thread on this subject here: [[jtopic:148632]] (note, may be out of date)

For details on the internals of routing, see [[Routing implementation details]].
<noinclude>[[Category:Tutorials]][[Category:Component Development]][[Category:Search Engine Friendly URLs]]</noinclude>

J2.5:Supporting SEF URLs in your component

2014-08-28T00:13:17Z

Mvangeest: /* Preparing Your Data for Routing */

{{version/tutor|2.5,3.1}}
{{:Search Engine Friendly URLs}}
In Joomla!, each [[component]] is responsible for handling its own SEF URLs. Therefore, as the [[Developers|developer]] of a component, you will have to create your own '''router''' to allow your component to use SEF URLs.

== The Concept ==

Assuming you are following standard development practices, your component is probably using "system URLs" that look a lot like <tt><nowiki>http://www.example.com/index.php?option=com_yourcomponent&view=article&id=1&catid=20&Itemid=50</nowiki></tt>, and your goal is to transform this into <tt><nowiki>http://www.example.com/example-menu-item/20/1</nowiki></tt>. As the developer, you have two tasks: signalling the system that certain pieces of text are URLs and need to be transformed, and explaining the system how to transform URLs.

=== Applying <code>JRoute::_</code> ===

It is difficult and inefficient for Joomla! to figure out which parts of your component's output are URLs. To support SEF URLs, you will need to change URL-generating code so that it applies <code>JRoute::_</code> before outputting the URL:

<source lang="php">
echo JRoute::_('index.php?view=article&id=1&catid=20');
</source>

Notice that it is possible to leave out the parameters <code>option</code> and <code>Itemid</code>. <code>option</code> defaults to the name of the component currently being executed, and <code>Itemid</code> defaults to the current menu item's ID.

In general, you should only apply this to URLs that users and/or search engines are able to see. For example, there is no need to transform URLs used in redirects that immediately result in other redirects.

If the user turns off SEF URLs in the site's settings, <code>JRoute::_</code> will produce working non-SEF URLs without any changes to the code.

=== Writing a router ===

You'll also need to write a router, which is a single file with two functions that convert system URLs to and from SEF URLs. This file needs to be placed at <tt>/components/com_yourcomponent/router.php</tt>.

The first function, <code>[componentname]BuildRoute(&$query)</code>, must transform an array of URL parameters into an array of segments that will form the SEF URL. Schematically, the transformation works as follows:

:<tt><nowiki>http://www.example.com/index.php?option=com_yourcomponent&view=article&id=1&catid=20&Itemid=50</nowiki></tt>

::<span style="font-size: xx-large">↓</span> <code>JRoute::_</code>, called by your component or any other extension

:<code>$query = array('view' => 'article', 'id' => 1, 'catid' => 20)</code>

::<span style="font-size: xx-large">↓</span> Your router's <code>com_yourcomponentBuildRoute</code>

:<code>$segments = array(20, 1);</code>

::<span style="font-size: xx-large">↓</span> Joomla's internal route building (for display)

:<tt><nowiki>http://www.example.com/example-menu-item/20/1</nowiki></tt>

The second function, <code>[componentname]ParseRoute($segments)</code>, must transform an array of segments back into an array of URL parameters. Schematically:

:<tt><nowiki>http://www.example.com/example-menu-item/20/1</nowiki></tt>

::<span style="font-size: xx-large">↓</span> Joomla's internal route parsing

:<code>$segments = array(20, 1);</code>

::<span style="font-size: xx-large">↓</span> Your router's <code>com_yourcomponentParseRoute</code>

:<code>$query = array('view' => 'article', 'id' => 1, 'catid' => 20)</code>

The two functions must cooperate in such a way that the original URL can be reconstructed. You can think of <code>BuildRoute</code> as a form of [[wikipedia:Encoding|encoding]] and <code>ParseRoute</code> as the corresponding decoding. When the original URL isn't properly reproduced, your component will stop working.

== Preparing Your Data for Routing ==

Clearly, any URL format needs to contain some kind of information that identifies the data you want to show. If your system URLs look like <tt><nowiki>http://www.example.com/index.php?option=com_yourcomponent&view=article&id=1&catid=20&Itemid=50</nowiki></tt>, that information is currently the <tt>id</tt> URL parameter (<tt>id=1</tt>). You probably want your SEF URLs to contain a textual description of the data they point to. In Joomla!, this is usually done by giving your users a way to enter an '''alias''' to be used in the URL.

=== The Alias ===

Even if your users can enter an alias, they might not do so, leaving the generation of a sensible alias up to your component. If your data has a title field, you can use that as a candidate alias (like the core [[Content]] component does).

Considering that the alias will be used in URLs, it has to be URL safe. Joomla! provides a method making arbitrary strings URI safe, which includes replacing accented UTF8 characters by their ASCII7 equivalents, white spaces by hyphens, etc. Whether the user entered the alias or a candidate has been chosen automatically, you should ensure that the above requirements for a URL safe alias are met. A good place for implementing this, if you are using <code>JTable</code>, is the <code>JTable::check()</code> method, which is called during the save process. Have a look at this example code:

<source lang="php">

function check()
{
jimport('joomla.filter.output');
if (empty($this->alias))
{
$this->alias = $this->title;
}
$this->alias = JFilterOutput::stringURLSafe($this->alias);

/* All your other checks */
return true;
}
</source>

If the alias field is empty the title is used as alias. Then the alias is made URL safe using the <code>JFilterOutput::stringURLSafe()</code> method.

=== The Slug ===

A '''slug''' is used to minimise the amount of code you need to support SEF URLs. It consists of the numerical identifier (<tt>id</tt>) your system URLs used, a colon (<tt>:</tt>), and the alias you created as described above.

Consider a SEF URL for an [[Article]] with <tt>id</tt> 1 and title "Welcome to Joomla!". The automatically generated alias for this article is <tt>welcome-to-joomla</tt>, and the slug becomes <tt>1:welcome-to-joomla</tt>. In the [[Content]] component, the two elements are combined during the database query in the model (<code>a</code> represents <code>#__content</code>):

<source lang="php">$query = 'SELECT a.*, '.
'CASE WHEN CHAR_LENGTH(a.alias) THEN CONCAT_WS(":", a.id, a.alias) ELSE a.id END as slug,'
/*...*/;</source>

The advantage of this method of creating a slug is that you can simply use the slug as a drop-in replacement for the id in most places. For example, you don't need to check for and remove the colon and the alias from the request data manually: if you use [[Retrieving request data using JInput|JInput]]'s <code>int</code> (integer) filter, it will do that automatically.

== Routing URLs ==

The <code>JRoute::_</code> method translates the internal Joomla! URL to a custom URL. <code>JRoute::_</code> has three parameters and its prototype is:

<source lang="php">JRoute::_($url, $xhtml = true, $ssl = null);</source>

Where:

* <code>$url</code> is a string containing the absolute or relative internal Joomla! URL.
* <code>$xhtml</code> is a boolean value that specifies whether or not the output should be in XHTML. This parameter is optional and if omitted defaults to true.
* <code>$ssl</code> is an integer value that specifies whether the URI should be secure. It should be set to 1 to force the URI to be secure using the global secure site URI, 0 to leave it in the same state as when it was passed, and -1 to force the URI to be unsecure using the global unsecure site URI.

The most important parameter is <code>$url</code>. A call to this method might look like:

<source lang="php">JRoute::_('index.php?view=article&id=' . $row->slug);</source>

<code>$row->slug</code> is the value that was generated in step 2 from a combination of id and title alias.

Another advantage of using <code>JRoute::_</code> is that the router now handles <code>$option</code> (the component name) and the <code>$Itemid</code> (the menu item ID). The component itself doesn't have to know its name (<code>$option</code>) or the active menu item (<code>$Itemid</code>) like it did in previous version of Joomla!.

It is important that you think about the sequence of the URL parameter in this stage. This will be more clear when we have a deeper look at the <tt>router.php</tt> in the next section.

The building process of JRouter is divided into two steps:

* Create the application route. The application route is fully handled by JRouter and the component developer doesn’t have to do anything to make it work.
* Create the component route. To create the component route, JRouter looks for the <tt>router.php</tt> in the component directory which is responsible for building the route for the component.

== The Component Router ==

We will have two functions in the <tt>router.php</tt>. One is responsible for building the URL and the other is responsible for parsing it. In the next examples, a very basic and a more advanced one, we assume that we have three views that links can point to. The first is a categories overview (<code>view=categories</code>), the second is a single category (<code>view=category</code>) and the third is a single article (<code>view=article</code>).

The file <tt>router.php</tt> should be in the site area of your component. It is not used on admin/backend pages. Don't forget to add it to your XML [[Manifest files|manifest file]] in the site folder.

=== A Simple Example ===

This simple example will illustrate the basics of implementing a router for your component.

<source lang="php">
function [componentname]BuildRoute(&$query)
{
$segments = array();
if (isset($query['view']))
{
$segments[] = $query['view'];
unset($query['view']);
}
if (isset($query['id']))
{
$segments[] = $query['id'];
unset($query['id']);
};
return $segments;
}

</source>

<code>JRouter</code> passes a <code>$query</code> array to the <code>[''componentname'']BuildRoute</code> function. This function will add the relevant parts of the array to the $segments array in the right order and will return the properly ordered array. The content of the <code>$query</code> array needs to be unset, otherwise <code>JRouter</code> will add it to the URL in the form of a query string (i.e. any variables that are not handled by the router will be passed in the query string).

The prefix ''componentname'' is the name for your component, as found in the directory holding the component's files. For instance, a component "Magic" in directory <tt>/components/com_magic/...</tt> would use a prefix <code>magic</code> (all lower case).

The next function in the <tt>router.php</tt> parses the URL:

<source lang="php">
function [componentname]ParseRoute($segments)
{
$vars = array();
switch($segments[0])
{
case 'categories':
$vars['view'] = 'categories';
break;
case 'category':
$vars['view'] = 'category';
$id = explode(':', $segments[1]);
$vars['id'] = (int) $id[0];
break;
case 'article':
$vars['view'] = 'article';
$id = explode(':', $segments[1]);
$vars['id'] = (int) $id[0];
break;
}
return $vars;
}
</source>

What happens here? In the function <code>[''componentname'']BuildRoute</code> we arranged the items in the <code>$query</code> array in a specific sequence. This means that in this example the view is first and the id is second in the array.

By reading <code>$segments[0]</code>, we access the name of the view. We set the right view and/or identifier depending on its value and we return the <code>$vars</code> array to <code>JRouter</code>. <code>$vars</code> should be an associative array similar to the array that was passed to the BuildRoute method.

The above example of the <tt>router.php</tt> is a very simple way to generate SEF URLs but should show how this works quite clearly.

The generated URL in this example contains the name of the view and doesn't reflect the content hierarchy:

<tt><nowiki>http://www.example.com/[menualias]/[view]/[slug]</nowiki></tt>

=== A More Advanced Example ===

In the next example we will try to get rid of the need for the view and we will try to reflect the current hierarchy level in the URL.

The goal is URL's that look like:

* When viewing an article: <tt><nowiki>http://www.example.com/[menualias]/[category]/[article]</nowiki></tt>
* When viewing a category: <tt><nowiki>http://www.example.com/[menualias]/[category]</nowiki></tt>
* When viewing the categories overview: <tt><nowiki>http://www.example.com/[menualias]</nowiki></tt>

Let's assume we have done step 1 and 2 also for the category.

The link to the article would look like this:

<source lang="php">
JRoute::_('index.php?view=article&catid=' . $row->catslug . '&id='.$row->slug);
</source>

And the Link to the category would look like this:

<source lang="php">
JRoute::_('index.php?view=category&id=' . $row->catslug);
</source>

The corresponding <tt>router.php</tt>:

<source lang="php">

function [componentname]BuildRoute(&$query)
{
$segments = array();
if (isset($query['catid']))
{
$segments[] = $query['catid'];
unset($query['catid']);
};
if (isset($query['id']))
{
$segments[] = $query['id'];
unset($query['id']);
};
unset($query['view']);
return $segments;
}
</source>

The difference now is that we don’t add the name of the view to the <code>$segments</code> array. We still unset the view key since otherwise, <code>JRouter</code> would add it to the URL as part of the query string. Another new thing here is the additional parameter catid that we push into the <code>$segments</code> array.

<source lang="php">
function [componentname]ParseRoute($segments)
{
$vars = array();
$app = JFactory::getApplication();
$menu = $app->getMenu();
$item = $menu->getActive();
// Count segments
$count = count($segments);
// Handle View and Identifier
switch ($item->query['view'])
{
case 'categories':
if ($count == 1)
{
$vars['view'] = 'category';
}
if ($count == 2)
{
$vars['view'] = 'article';
}
$id = explode(':', $segments[$count-1]);
$vars['id'] = (int) $id[0];
break;
case 'category':
$id = explode(':', $segments[$count-1]);
$vars['id'] = (int) $id[0];
$vars['view'] = 'article';
break;
}
return $vars;
}
</source>

You can see that this ParseRoute function has a lot of different code parts in comparison to the previous. The reason for this is simple. We don’t have the name of the view in the <code>$segments</code> array and we need to find another way to determine it.

We need to find out which level of hierarchy we are in by receiving the root element. We do this by looking to the view name of the active menu item:

<source lang="php">
$item->query['view']
</source>

Also we need to know the number of items in the <code>$segments</code> array:

<source lang="php">
$count = count($segments);
</source>

With this information we can correctly set the view for all possible three cases:

* The menu item is a link to the categories view and the <code>$segments</code> array has two items (<code>$catid</code> and <code>$id</code>). In this case we know that we need to parse a link to an article.
* The menu item is a link to the categories view and the <code>$segments</code> array has one item (<code>$id</code>). In this case we know that we need to parse a link to a category.
* The menu item is a link to a category. In this case, we know that any item in the <code>$segments</code> array is the identifier for an article.

The result of all this code is clean and human-readable component URLs.

== Routers and Menu Items ==

A last important part of creating a router is considering what to do with menu items. As explained on [[Search Engine Friendly URLs]], the output of the component router is used ''after'' the first segment of a route, the first segment being the menu item's alias. This creates a difficult question: how is your router and/or other code to know which menu item to route through?

Suppose, for example, that your component is currently producing output for the page <tt>/dogs</tt>, which lists all dogs in the system. Of course, the items in the list need to be links to pages that display more details about one dog. What should the URL to the dog with ID 21 and name Fido become? Using a router that works according to the principles we've seen so far, the route that is produced is <tt>dogs/21-fido</tt>, or with some additional work <tt>/dogs/fido</tt>. But perhaps the user has created a menu item with the alias <tt>mydoggy</tt> which displays exactly that dog's details. Then it is probably the user's intention to route this URL through that menu item, and the item in the list should link to the page <tt>/mydoggy</tt>.

More generally, whenever you are building a route, you will need to find the menu item that is most suitable as a ''starting point'' for building your route. The term ''starting point'' is emphasized because the rest of the route depends on the configuration of the menu item. In our example above, <tt>/dogs/21-fido</tt> is an acceptable route, <tt>/mydoggy</tt> is arguably even better, but <tt>/mydoggy/21-fido</tt> is simply wrong, since <tt>/mydoggy</tt> is in itself a menu item that is set up to display <tt>fido</tt>'s information.

Several approaches are available to tackle this problem. Joomla!'s core components take a mixed approach, separating responsibilities in two units of code: the router itself and the so-called <code>[componentname]RouteHelper</code>. The <code>[componentname]RouteHelper</code> provides methods that find the most suitable menu item for a given piece of data to be displayed, while the router analyzes the menu item and puts any information that is not determined by the menu item's configuration into the route. This does mean that the ''calling code'' must explicitly call the helper's method before routing (<code>echo JRoute::_(DogsRouteHelper::getDogRoute(21));</code>).

== See Also ==

There is a useful thread on this subject here: [[jtopic:148632]] (note, may be out of date)

For details on the internals of routing, see [[Routing implementation details]].
<noinclude>[[Category:Tutorials]][[Category:Component Development]][[Category:Search Engine Friendly URLs]]</noinclude>

J2.5:Supporting SEF URLs in your component

2014-08-26T15:20:33Z

Mvangeest: Adjusted layout

{{version/tutor|2.5,3.1}}
{{:Search Engine Friendly URLs}}
In Joomla!, each [[component]] is responsible for handling its own SEF URLs. Therefore, as the [[Developers|developer]] of a component, you will have to create your own '''router''' to allow your component to use SEF URLs.

== The Concept ==

Assuming you are following standard development practices, your component is probably using "system URLs" that look a lot like <tt><nowiki>http://www.example.com/index.php?option=com_yourcomponent&view=article&id=1&catid=20&Itemid=50</nowiki></tt>, and your goal is to transform this into <tt><nowiki>http://www.example.com/example-menu-item/20/1</nowiki></tt>. As the developer, you have two tasks: signalling the system that certain pieces of text are URLs and need to be transformed, and explaining the system how to transform URLs.

=== Applying <code>JRoute::_</code> ===

It is difficult and inefficient for Joomla! to figure out which parts of your component's output are URLs. To support SEF URLs, you will need to change URL-generating code so that it applies <code>JRoute::_</code> before outputting the URL:

<source lang="php">
echo JRoute::_('index.php?view=article&id=1&catid=20');
</source>

Notice that it is possible to leave out the parameters <code>option</code> and <code>Itemid</code>. <code>option</code> defaults to the name of the component currently being executed, and <code>Itemid</code> defaults to the current menu item's ID.

In general, you should only apply this to URLs that users and/or search engines are able to see. For example, there is no need to transform URLs used in redirects that immediately result in other redirects.

If the user turns off SEF URLs in the site's settings, <code>JRoute::_</code> will produce working non-SEF URLs without any changes to the code.

=== Writing a router ===

You'll also need to write a router, which is a single file with two functions that convert system URLs to and from SEF URLs. This file needs to be placed at <tt>/components/com_yourcomponent/router.php</tt>.

The first function, <code>[componentname]BuildRoute(&$query)</code>, must transform an array of URL parameters into an array of segments that will form the SEF URL. Schematically, the transformation works as follows:

:<tt><nowiki>http://www.example.com/index.php?option=com_yourcomponent&view=article&id=1&catid=20&Itemid=50</nowiki></tt>

::<span style="font-size: xx-large">↓</span> <code>JRoute::_</code>, called by your component or any other extension

:<code>$query = array('view' => 'article', 'id' => 1, 'catid' => 20)</code>

::<span style="font-size: xx-large">↓</span> Your router's <code>com_yourcomponentBuildRoute</code>

:<code>$segments = array(20, 1);</code>

::<span style="font-size: xx-large">↓</span> Joomla's internal route building (for display)

:<tt><nowiki>http://www.example.com/example-menu-item/20/1</nowiki></tt>

The second function, <code>[componentname]ParseRoute($segments)</code>, must transform an array of segments back into an array of URL parameters. Schematically:

:<tt><nowiki>http://www.example.com/example-menu-item/20/1</nowiki></tt>

::<span style="font-size: xx-large">↓</span> Joomla's internal route parsing

:<code>$segments = array(20, 1);</code>

::<span style="font-size: xx-large">↓</span> Your router's <code>com_yourcomponentParseRoute</code>

:<code>$query = array('view' => 'article', 'id' => 1, 'catid' => 20)</code>

The two functions must cooperate in such a way that the original URL can be reconstructed. You can think of <code>BuildRoute</code> as a form of [[wikipedia:Encoding|encoding]] and <code>ParseRoute</code> as the corresponding decoding. When the original URL isn't properly reproduced, your component will stop working.

== Preparing Your Data for Routing ==

=== The Alias ===

The first step is the generation of the so called alias. The alias is used in the URL instead of the title (the alias is the text you want to have in the URL). The alias has to be URI safe, which means accented UTF8 characters are replaced by their ASCII7 equivalents, white spaces by hyphens, etc.

The alias can be defined by the user, but you should ensure that the above requirements for a URL safe alias are met. A good way to do so is to use the <code>JTable::check()</code> method during the save process. Have a look at this example code:

<source lang="php">

function check()
{
jimport('joomla.filter.output');
if (empty($this->alias))
{
$this->alias = $this->title;
}
$this->alias = JFilterOutput::stringURLSafe($this->alias);

/* All your other checks */
return true;
}
</source>

If the alias field is empty the title will be used as alias. Then the alias will be made URLSafe using the <code>JFilterOutput::stringURLSafe()</code> method.

=== The Slug ===

Continuing with the same example, the "slug" - "1:welcome-to-joomla" has two parts. The first part is the article identifier (id) and the second is the alias. They are separated by a colon. These two elements were combined during the database query in the model:

<source lang="php">$query = 'SELECT a.*, '.
'CASE WHEN CHAR_LENGTH(a.alias) THEN CONCAT_WS(":", a.id, a.alias) ELSE a.id END as slug,'
/*...*/;</source>

After this step the slug is used instead of the id.

== Routing URLs ==

The <code>JRoute::_</code> method translates the internal Joomla! URL to a custom URL. <code>JRoute::_</code> has three parameters and its prototype is:

<source lang="php">JRoute::_($url, $xhtml = true, $ssl = null);</source>

Where:

* <code>$url</code> is a string containing the absolute or relative internal Joomla! URL.
* <code>$xhtml</code> is a boolean value that specifies whether or not the output should be in XHTML. This parameter is optional and if omitted defaults to true.
* <code>$ssl</code> is an integer value that specifies whether the URI should be secure. It should be set to 1 to force the URI to be secure using the global secure site URI, 0 to leave it in the same state as when it was passed, and -1 to force the URI to be unsecure using the global unsecure site URI.

The most important parameter is <code>$url</code>. A call to this method might look like:

<source lang="php">JRoute::_('index.php?view=article&id=' . $row->slug);</source>

<code>$row->slug</code> is the value that was generated in step 2 from a combination of id and title alias.

Another advantage of using <code>JRoute::_</code> is that the router now handles <code>$option</code> (the component name) and the <code>$Itemid</code> (the menu item ID). The component itself doesn't have to know its name (<code>$option</code>) or the active menu item (<code>$Itemid</code>) like it did in previous version of Joomla!.

It is important that you think about the sequence of the URL parameter in this stage. This will be more clear when we have a deeper look at the <tt>router.php</tt> in the next section.

The building process of JRouter is divided into two steps:

* Create the application route. The application route is fully handled by JRouter and the component developer doesn’t have to do anything to make it work.
* Create the component route. To create the component route, JRouter looks for the <tt>router.php</tt> in the component directory which is responsible for building the route for the component.

== The Component Router ==

We will have two functions in the <tt>router.php</tt>. One is responsible for building the URL and the other is responsible for parsing it. In the next examples, a very basic and a more advanced one, we assume that we have three views that links can point to. The first is a categories overview (<code>view=categories</code>), the second is a single category (<code>view=category</code>) and the third is a single article (<code>view=article</code>).

The file <tt>router.php</tt> should be in the site area of your component. It is not used on admin/backend pages. Don't forget to add it to your XML [[Manifest files|manifest file]] in the site folder.

=== A Simple Example ===

This simple example will illustrate the basics of implementing a router for your component.

<source lang="php">
function [componentname]BuildRoute(&$query)
{
$segments = array();
if (isset($query['view']))
{
$segments[] = $query['view'];
unset($query['view']);
}
if (isset($query['id']))
{
$segments[] = $query['id'];
unset($query['id']);
};
return $segments;
}

</source>

<code>JRouter</code> passes a <code>$query</code> array to the <code>[''componentname'']BuildRoute</code> function. This function will add the relevant parts of the array to the $segments array in the right order and will return the properly ordered array. The content of the <code>$query</code> array needs to be unset, otherwise <code>JRouter</code> will add it to the URL in the form of a query string (i.e. any variables that are not handled by the router will be passed in the query string).

The prefix ''componentname'' is the name for your component, as found in the directory holding the component's files. For instance, a component "Magic" in directory <tt>/components/com_magic/...</tt> would use a prefix <code>magic</code> (all lower case).

The next function in the <tt>router.php</tt> parses the URL:

<source lang="php">
function [componentname]ParseRoute($segments)
{
$vars = array();
switch($segments[0])
{
case 'categories':
$vars['view'] = 'categories';
break;
case 'category':
$vars['view'] = 'category';
$id = explode(':', $segments[1]);
$vars['id'] = (int) $id[0];
break;
case 'article':
$vars['view'] = 'article';
$id = explode(':', $segments[1]);
$vars['id'] = (int) $id[0];
break;
}
return $vars;
}
</source>

What happens here? In the function <code>[''componentname'']BuildRoute</code> we arranged the items in the <code>$query</code> array in a specific sequence. This means that in this example the view is first and the id is second in the array.

By reading <code>$segments[0]</code>, we access the name of the view. We set the right view and/or identifier depending on its value and we return the <code>$vars</code> array to <code>JRouter</code>. <code>$vars</code> should be an associative array similar to the array that was passed to the BuildRoute method.

The above example of the <tt>router.php</tt> is a very simple way to generate SEF URLs but should show how this works quite clearly.

The generated URL in this example contains the name of the view and doesn't reflect the content hierarchy:

<tt><nowiki>http://www.example.com/[menualias]/[view]/[slug]</nowiki></tt>

=== A More Advanced Example ===

In the next example we will try to get rid of the need for the view and we will try to reflect the current hierarchy level in the URL.

The goal is URL's that look like:

* When viewing an article: <tt><nowiki>http://www.example.com/[menualias]/[category]/[article]</nowiki></tt>
* When viewing a category: <tt><nowiki>http://www.example.com/[menualias]/[category]</nowiki></tt>
* When viewing the categories overview: <tt><nowiki>http://www.example.com/[menualias]</nowiki></tt>

Let's assume we have done step 1 and 2 also for the category.

The link to the article would look like this:

<source lang="php">
JRoute::_('index.php?view=article&catid=' . $row->catslug . '&id='.$row->slug);
</source>

And the Link to the category would look like this:

<source lang="php">
JRoute::_('index.php?view=category&id=' . $row->catslug);
</source>

The corresponding <tt>router.php</tt>:

<source lang="php">

function [componentname]BuildRoute(&$query)
{
$segments = array();
if (isset($query['catid']))
{
$segments[] = $query['catid'];
unset($query['catid']);
};
if (isset($query['id']))
{
$segments[] = $query['id'];
unset($query['id']);
};
unset($query['view']);
return $segments;
}
</source>

The difference now is that we don’t add the name of the view to the <code>$segments</code> array. We still unset the view key since otherwise, <code>JRouter</code> would add it to the URL as part of the query string. Another new thing here is the additional parameter catid that we push into the <code>$segments</code> array.

<source lang="php">
function [componentname]ParseRoute($segments)
{
$vars = array();
$app = JFactory::getApplication();
$menu = $app->getMenu();
$item = $menu->getActive();
// Count segments
$count = count($segments);
// Handle View and Identifier
switch ($item->query['view'])
{
case 'categories':
if ($count == 1)
{
$vars['view'] = 'category';
}
if ($count == 2)
{
$vars['view'] = 'article';
}
$id = explode(':', $segments[$count-1]);
$vars['id'] = (int) $id[0];
break;
case 'category':
$id = explode(':', $segments[$count-1]);
$vars['id'] = (int) $id[0];
$vars['view'] = 'article';
break;
}
return $vars;
}
</source>

You can see that this ParseRoute function has a lot of different code parts in comparison to the previous. The reason for this is simple. We don’t have the name of the view in the <code>$segments</code> array and we need to find another way to determine it.

We need to find out which level of hierarchy we are in by receiving the root element. We do this by looking to the view name of the active menu item:

<source lang="php">
$item->query['view']
</source>

Also we need to know the number of items in the <code>$segments</code> array:

<source lang="php">
$count = count($segments);
</source>

With this information we can correctly set the view for all possible three cases:

* The menu item is a link to the categories view and the <code>$segments</code> array has two items (<code>$catid</code> and <code>$id</code>). In this case we know that we need to parse a link to an article.
* The menu item is a link to the categories view and the <code>$segments</code> array has one item (<code>$id</code>). In this case we know that we need to parse a link to a category.
* The menu item is a link to a category. In this case, we know that any item in the <code>$segments</code> array is the identifier for an article.

The result of all this code is clean and human-readable component URLs.

== Routers and Menu Items ==

A last important part of creating a router is considering what to do with menu items. As explained on [[Search Engine Friendly URLs]], the output of the component router is used ''after'' the first segment of a route, the first segment being the menu item's alias. This creates a difficult question: how is your router and/or other code to know which menu item to route through?

Suppose, for example, that your component is currently producing output for the page <tt>/dogs</tt>, which lists all dogs in the system. Of course, the items in the list need to be links to pages that display more details about one dog. What should the URL to the dog with ID 21 and name Fido become? Using a router that works according to the principles we've seen so far, the route that is produced is <tt>dogs/21-fido</tt>, or with some additional work <tt>/dogs/fido</tt>. But perhaps the user has created a menu item with the alias <tt>mydoggy</tt> which displays exactly that dog's details. Then it is probably the user's intention to route this URL through that menu item, and the item in the list should link to the page <tt>/mydoggy</tt>.

More generally, whenever you are building a route, you will need to find the menu item that is most suitable as a ''starting point'' for building your route. The term ''starting point'' is emphasized because the rest of the route depends on the configuration of the menu item. In our example above, <tt>/dogs/21-fido</tt> is an acceptable route, <tt>/mydoggy</tt> is arguably even better, but <tt>/mydoggy/21-fido</tt> is simply wrong, since <tt>/mydoggy</tt> is in itself a menu item that is set up to display <tt>fido</tt>'s information.

Several approaches are available to tackle this problem. Joomla!'s core components take a mixed approach, separating responsibilities in two units of code: the router itself and the so-called <code>[componentname]RouteHelper</code>. The <code>[componentname]RouteHelper</code> provides methods that find the most suitable menu item for a given piece of data to be displayed, while the router analyzes the menu item and puts any information that is not determined by the menu item's configuration into the route. This does mean that the ''calling code'' must explicitly call the helper's method before routing (<code>echo JRoute::_(DogsRouteHelper::getDogRoute(21));</code>).

== See Also ==

There is a useful thread on this subject here: [[jtopic:148632]] (note, may be out of date)

For details on the internals of routing, see [[Routing implementation details]].
<noinclude>[[Category:Tutorials]][[Category:Component Development]][[Category:Search Engine Friendly URLs]]</noinclude>

J2.5:Supporting SEF URLs in your component

2014-08-26T15:13:22Z

Mvangeest: Adjusted code style

{{version/tutor|2.5,3.1}}
{{:Search Engine Friendly URLs}}
In Joomla!, each [[component]] is responsible for handling its own SEF URLs. Therefore, as the [[Developers|developer]] of a component, you will have to create your own '''router''' to allow your component to use SEF URLs.

== The Concept ==

Assuming you are following standard development practices, your component is probably using "system URLs" that look a lot like <tt><nowiki>http://www.example.com/index.php?option=com_yourcomponent&view=article&id=1&catid=20&Itemid=50</nowiki></tt>, and your goal is to transform this into <tt><nowiki>http://www.example.com/example-menu-item/20/1</nowiki></tt>. As the developer, you have two tasks: signalling the system that certain pieces of text are URLs and need to be transformed, and explaining the system how to transform URLs.

=== Applying <code>JRoute::_</code> ===

It is difficult and inefficient for Joomla! to figure out which parts of your component's output are URLs. To support SEF URLs, you will need to change URL-generating code so that it applies <code>JRoute::_</code> before outputting the URL:

<source lang="php">
echo JRoute::_('index.php?view=article&id=1&catid=20');
</source>

Notice that it is possible to leave out the parameters <code>option</code> and <code>Itemid</code>. <code>option</code> defaults to the name of the component currently being executed, and <code>Itemid</code> defaults to the current menu item's ID.

In general, you should only apply this to URLs that users and/or search engines are able to see. For example, there is no need to transform URLs used in redirects that immediately result in other redirects.

If the user turns off SEF URLs in the site's settings, <code>JRoute::_</code> will produce working non-SEF URLs without any changes to the code.

=== Writing a router ===

You'll also need to write a router, which is a single file with two functions that convert system URLs to and from SEF URLs. This file needs to be placed at <tt>/components/com_yourcomponent/router.php</tt>.

The first function, <code>[componentname]BuildRoute(&$query)</code>, must transform an array of URL parameters into an array of segments that will form the SEF URL. Schematically, the transformation works as follows:

:<tt><nowiki>http://www.example.com/index.php?option=com_yourcomponent&view=article&id=1&catid=20&Itemid=50</nowiki></tt>

::<span style="font-size: xx-large">↓</span> <code>JRoute::_</code>, called by your component or any other extension

:<code>$query = array('view' => 'article', 'id' => 1, 'catid' => 20)</code>

::<span style="font-size: xx-large">↓</span> Your router's <code>com_yourcomponentBuildRoute</code>

:<code>$segments = array(20, 1);</code>

::<span style="font-size: xx-large">↓</span> Joomla's internal route building (for display)

:<tt><nowiki>http://www.example.com/example-menu-item/20/1</nowiki></tt>

The second function, <code>[componentname]ParseRoute($segments)</code>, must transform an array of segments back into an array of URL parameters. Schematically:

:<tt><nowiki>http://www.example.com/example-menu-item/20/1</nowiki></tt>

::<span style="font-size: xx-large">↓</span> Joomla's internal route parsing

:<code>$segments = array(20, 1);</code>

::<span style="font-size: xx-large">↓</span> Your router's <code>com_yourcomponentParseRoute</code>

:<code>$query = array('view' => 'article', 'id' => 1, 'catid' => 20)</code>

The two functions must cooperate in such a way that the original URL can be reconstructed. You can think of <code>BuildRoute</code> as a form of [[wikipedia:Encoding|encoding]] and <code>ParseRoute</code> as the corresponding decoding. When the original URL isn't properly reproduced, your component will stop working.

== Preparing Your Data for Routing ==

=== The Alias ===

The first step is the generation of the so called alias. The alias is used in the URL instead of the title (the alias is the text you want to have in the URL). The alias has to be URI safe, which means accented UTF8 characters are replaced by their ASCII7 equivalents, white spaces by hyphens, etc.

The alias can be defined by the user, but you should ensure that the above requirements for a URL safe alias are met. A good way to do so is to use the JTable::check() method during the save process. Have a look at this example code:

<source lang="php">

function check()
{
jimport('joomla.filter.output');
if (empty($this->alias))
{
$this->alias = $this->title;
}
$this->alias = JFilterOutput::stringURLSafe($this->alias);

/* All your other checks */
return true;
}
</source>

If the alias field is empty the title will be used as alias. Then the alias will be made URLSafe using the <code>JFilterOutput::stringURLSafe()</code> method.

=== The Slug ===

Continuing with the same example, the "slug" - "1:welcome-to-joomla" has two parts. The first part is the article identifier (id) and the second is the alias. They are separated by a colon. These two elements were combined during the database query in the model:

<source lang="php">$query = 'SELECT a.*, '.
'CASE WHEN CHAR_LENGTH(a.alias) THEN CONCAT_WS(":", a.id, a.alias) ELSE a.id END as slug,'
/*...*/;</source>

After this step the slug is used instead of the id.

== Routing URLs ==

The <code>JRoute::_</code> method translates the internal Joomla! URL to a custom URL. <tt>JRoute</tt> has three parameters and its prototype is:

<source lang="php">JRoute::_($url, $xhtml = true, $ssl = null);</source>

Where:

* <code>$url</code> is a string containing the absolute or relative internal Joomla! URL.
* <code>$xhtml</code> is a boolean value that specifies whether or not the output should be in XHTML. This parameter is optional and if omitted defaults to true.
* <code>$ssl</code> is an integer value that specifies whether the URI should be secure. It should be set to 1 to force the URI to be secure using the global secure site URI, 0 to leave it in the same state as when it was passed, and -1 to force the URI to be unsecure using the global unsecure site URI.

The most important parameter is <code>$url</code>. A call to this method might look like:

<source lang="php">JRoute::_('index.php?view=article&id=' . $row->slug);</source>

<code>$row->slug</code> is the value that was generated in step 2 from a combination of id and title alias.

Another advantage of using JRoute is that the router now handles $option (the component name) and the $Itemid (the menu item ID). The component itself doesn’t have to know its name ($option) or the active menu item ($Itemid) like it did in previous version of Joomla!.

It is important that you think about the sequence of the URL parameter in this stage. This will be more clear when we have a deeper look at the router.php in the next section.

The building process of JRouter is divided into two steps:

* Create the application route. The application route is fully handled by JRouter and the component developer doesn’t have to do anything to make it work.
* Create the component route. To create the component route, JRouter looks for the <tt>router.php</tt> in the component directory which is responsible for building the route for the component.

== The Component Router ==

We will have two functions in the <tt>router.php</tt>. One is responsible for building the URL and the other is responsible for parsing it. In the next examples, a very basic and a more advanced one, we assume that we have three views that links can point to. The first is a categories overview (<code>view=categories</code>), the second is a single category (<code>view=category</code>) and the third is a single article (<code>view=article</code>).

The file <tt>router.php</tt> should be in the site area of your component. It is not used on admin/backend pages. Don't forget to add it to your XML [[Manifest files|manifest file]] in the site folder.

=== A Simple Example ===

This simple example will illustrate the basics of implementing a router for your component.

<source lang="php">
function [componentname]BuildRoute(&$query)
{
$segments = array();
if (isset($query['view']))
{
$segments[] = $query['view'];
unset($query['view']);
}
if (isset($query['id']))
{
$segments[] = $query['id'];
unset($query['id']);
};
return $segments;
}

</source>

<code>JRouter</code> passes a $query array to the <code>[''componentname'']BuildRoute</code> function. This function will add the relevant parts of the array to the $segments array in the right order and will return the properly ordered array. The content of the <code>$query</code> array needs to be unset, otherwise <code>JRouter</code> will add it to the URL in the form of a query string (i.e. any variables that are not handled by the router will be passed in the query string).

The prefix ''componentname'' is the name for your component, as found in the directory holding the component's files. For instance, a component "Magic" in directory <tt>/components/com_magic/...</tt> would use a prefix <code>magic</code> (all lower case).

The next function in the <tt>router.php</tt> parses the URL:

<source lang="php">
function [componentname]ParseRoute($segments)
{
$vars = array();
switch($segments[0])
{
case 'categories':
$vars['view'] = 'categories';
break;
case 'category':
$vars['view'] = 'category';
$id = explode(':', $segments[1]);
$vars['id'] = (int) $id[0];
break;
case 'article':
$vars['view'] = 'article';
$id = explode(':', $segments[1]);
$vars['id'] = (int) $id[0];
break;
}
return $vars;
}
</source>

What happens here? In the function <code>[''componentname'']BuildRoute</code> we arranged the items in the <code>$query</code> array in a specific sequence. This means that in this example the view is first and the id is second in the array.

By reading <code>$segments[0]</code>, we access the name of the view. We set the right view and/or identifier depending on its value and we return the <code>$vars</code> array to <code>JRouter</code>. $vars should be an associative array similar to the array that was passed to the BuildRoute method.

The above example of the <tt>router.php</tt> is a very simple way to generate SEF URLs but should show how this works quite clearly.

The generated URL in this example contains the name of the view and doesn't reflect the content hierarchy:

<tt><nowiki>http://www.example.com/[menualias]/[view]/[slug]</nowiki></tt>

=== A More Advanced Example ===

In the next example we will try to get rid of the need for the view and we will try to reflect the current hierarchy level in the URL.

The goal is URL's that look like:

* When viewing an article: <tt><nowiki>http://www.example.com/[menualias]/[category]/[article]</nowiki></tt>
* When viewing a category: <tt><nowiki>http://www.example.com/[menualias]/[category]</nowiki></tt>
* When viewing the categories overview: <tt><nowiki>http://www.example.com/[menualias]</nowiki></tt>

Let's assume we have done step 1 and 2 also for the category.

The link to the article would look like this:

<source lang="php">
JRoute::_('index.php?view=article&catid=' . $row->catslug . '&id='.$row->slug);
</source>

And the Link to the category would look like this:

<source lang="php">
JRoute::_('index.php?view=category&id=' . $row->catslug);
</source>

The corresponding <tt>router.php</tt>:

<source lang="php">

function [componentname]BuildRoute(&$query)
{
$segments = array();
if (isset($query['catid']))
{
$segments[] = $query['catid'];
unset($query['catid']);
};
if (isset($query['id']))
{
$segments[] = $query['id'];
unset($query['id']);
};
unset($query['view']);
return $segments;
}
</source>

The difference now is that we don’t add the name of the view to the <code>$segments</code> array. We still unset the view key since otherwise, <code>JRouter</code> would add it to the URL as part of the query string. Another new thing here is the additional parameter catid that we push into the <code>$segments</code> array.

<source lang="php">
function [componentname]ParseRoute($segments)
{
$vars = array();
$app = JFactory::getApplication();
$menu = $app->getMenu();
$item = $menu->getActive();
// Count segments
$count = count($segments);
// Handle View and Identifier
switch ($item->query['view'])
{
case 'categories':
if ($count == 1)
{
$vars['view'] = 'category';
}
if ($count == 2)
{
$vars['view'] = 'article';
}
$id = explode(':', $segments[$count-1]);
$vars['id'] = (int) $id[0];
break;
case 'category':
$id = explode(':', $segments[$count-1]);
$vars['id'] = (int) $id[0];
$vars['view'] = 'article';
break;
}
return $vars;
}
</source>

You can see that this ParseRoute function has a lot of different code parts in comparison to the previous. The reason for this is simple. We don’t have the name of the view in the <code>$segments</code> array and we need to find another way to determine it.

We need to find out which level of hierarchy we are in by receiving the root element. We do this by looking to the view name of the active menu item:

<source lang="php">
$item->query['view']
</source>

Also we need to know the number of items in the <code>$segments</code> array:

<source lang="php">
$count = count($segments);
</source>

With this information we can correctly set the view for all possible three cases:

* The menu item is a link to the categories view and the <code>$segments</code> array has two items (<code>$catid</code> and <code>$id</code>). In this case we know that we need to parse a link to an article.
* The menu item is a link to the categories view and the <code>$segments</code> array has one item (<code>$id</code>). In this case we know that we need to parse a link to a category.
* The menu item is a link to a category. In this case, we know that any item in the <code>$segments</code> array is the identifier for an article.

The result of all this code is clean and human-readable component URLs.

== Routers and Menu Items ==

A last important part of creating a router is considering what to do with menu items. As explained on [[Search Engine Friendly URLs]], the output of the component router is used ''after'' the first segment of a route, the first segment being the menu item's alias. This creates a difficult question: how is your router and/or other code to know which menu item to route through?

Suppose, for example, that your component is currently producing output for the page <tt>/dogs</tt>, which lists all dogs in the system. Of course, the items in the list need to be links to pages that display more details about one dog. What should the URL to the dog with ID 21 and name Fido become? Using a router that works according to the principles we've seen so far, the route that is produced is <tt>dogs/21-fido</tt>, or with some additional work <tt>/dogs/fido</tt>. But perhaps the user has created a menu item with the alias <tt>mydoggy</tt> which displays exactly that dog's details. Then it is probably the user's intention to route this URL through that menu item, and the item in the list should link to the page <tt>/mydoggy</tt>.

More generally, whenever you are building a route, you will need to find the menu item that is most suitable as a ''starting point'' for building your route. The term ''starting point'' is emphasized because the rest of the route depends on the configuration of the menu item. In our example above, <tt>/dogs/21-fido</tt> is an acceptable route, <tt>/mydoggy</tt> is arguably even better, but <tt>/mydoggy/21-fido</tt> is simply wrong, since <tt>/mydoggy</tt> is in itself a menu item that is set up to display <tt>fido</tt>'s information.

Several approaches are available to tackle this problem. Joomla!'s core components take a mixed approach, separating responsibilities in two units of code: the router itself and the so-called <code>[componentname]RouteHelper</code>. The <code>[componentname]RouteHelper</code> provides methods that find the most suitable menu item for a given piece of data to be displayed, while the router analyzes the menu item and puts any information that is not determined by the menu item's configuration into the route. This does mean that the ''calling code'' must explicitly call the helper's method before routing (<code>echo JRoute::_(DogsRouteHelper::getDogRoute(21));</code>).

== See Also ==

There is a useful thread on this subject here: [[jtopic:148632]] (note, may be out of date)

For details on the internals of routing, see [[Routing implementation details]].
<noinclude>[[Category:Tutorials]][[Category:Component Development]][[Category:Search Engine Friendly URLs]]</noinclude>

Manifest files

2014-07-07T22:54:25Z

Mvangeest: Fixed layout

{{version|2.5,3.x}}

Within Joomla there are manifest files for all of the extensions. These files include the general installation information as well as parameters for the configuration of the [[extension]] itself. Since Joomla! 2.5 {{JVer|2.5}}, there are very few differences between the manifest file formats for the different [[Extension types (technical definitions)|types of extensions]], allowing each type to access the full power of the Joomla! installer.

==Naming conventions==
The file must be named <tt>manifest.xml</tt> or <tt><extension_name>.xml</tt> and located in the root directory of the installation package.

==Syntax==

=== Root element ===
The primary tag of the installation file is:
<source lang=xml><extension></extension></source>

This starting and closing tags are now valid for all extensions. The new tag <code><extension></code> replaces the old <code><install></install></code> from Joomla {{JVer|1.5}}. The following attributes are allowed within the tag:

{|class="wikitable"
|-
! style="width: 150px" | Attribute || style="width: 150px" | Values || Applicable to || Description
|-
| type || <code>component</code><br /><code>file</code><br /><code>language</code><br /><code>library</code><br /><code>module</code><br /><code>package</code><br /><code>plugin</code><br /><code>template</code> || All extensions
| This attribute describes the type of the extension for the installer. Based on this type further requirements to sub-tags apply.
|-
| version
| <code>2.5</code><br /><code>3.0</code> || All extensions
| String that identifies the version of Joomla for which this extension is developed.
|-
| method
| <code>install</code><br /><code>upgrade</code> || All extensions
| The default value <code>install</code> will be also used if the method attribute is not used. The <code>install</code> value means the installer will gracefully stop if it finds any existing file/folder of the new extension.
|-
| client
| <code>site</code><br /><code>administrator</code> || Modules
| The client attribute allows you to specify for which application client the new module is available.
|-
| group
| ''string'' || Plugins
| The group name specifies for which group of plugins the new plugin is available. The existing groups are the folder names within the directory <tt>/plugins</tt>. The installer will create new folder names for group names that do not exist yet.
|}

=== Metadata ===

The following elements can be used to insert metadata. None of these elements are required; if they are present, they must be a child of the root element.

<pre>
<name> – raw component name (e.g. com_banners).
<author> – author's name (e.g. Joomla! Project)
<creationDate> – date of creation or release (e.g. April 2006)
<copyright> – a copyright statement (e.g. (C) 2005 - 2011 Open Source Matters. All rights reserved.)
<license> – a license statement (e.g. NU General Public License version 2 or later; see LICENSE.txt)
<authorEmail> – author's email address (e.g. admin@joomla.org)
<authorUrl> – URL to the author's website (e.g. www.joomla.org)
<version> – the version number of the extension (e.g. 1.6.0)
<description> – the description of the component. This is a translatable field. (e.g. COM_BANNERS_XML_DESCRIPTION)
</pre>

Note: The <name> and <description> tags are also translatable fields so that the name and description of the extension can be shown to the user in their native language.

=== Front-end files ===

<source lang="xml">
<files folder="from-folder">
<filename>example.php</filename>
<folder>examples</folder>
</files>
</source>

Files to copy to the front-end directory should be placed in the <code><files></code> element. You can use the optional <code>folder</code> attribute to specify a directory '''in the ZIP package''' to copy '''from'''. Each file to copy must be represented by a <code><filename></code> element. If you want to copy an entire folder at once, you can define it as a <code><folder></code>.

=== Media files ===

<source lang="xml>
<media folder="media" destination="com_example">
<filename>com_example_logo.png</filename>
<folder>css</folder>
<folder>js</folder>
</media>
</source>

This example will copy the file(s) (<tt>/media/com_example_logo.png</tt>) and folders ( <tt>/media/css/</tt> and <tt>/media/js/</tt> ) listed to <tt>/media/com_example/</tt>, creating the <tt>com_example</tt> folder if required. You can use the optional <code>folder</code> attribute to specify a directory '''in the ZIP package''' to copy '''from''' (in this case, <tt>media</tt>).

Extensions should be storing assets they need to be web accessible (JS, CSS, images etc) in <code>media</code>. Amongst other things this feature was added as step in the progression to multi-site support and the eventual move of code files (PHP) out of the web accessible areas of the server.

Ref:
* [https://groups.google.com/forum/#!msg/joomla-dev-cms/4CAASJqFY-k/PvPj14gP29EJ Google Groups - joomla-dev-cms thread]
* [https://groups.google.com/forum/#!msg/joomla-dev-cms/uNmhX98sKbE/p8p68Jke680J Google Groups - joomla-dev-cms thread]

=== Administration section ===

<source lang="xml">
<administration>

</administration>
</source>

The administration section is defined in the <code><administration></code> element. Since only [[Component|components]] apply to both the [[Site (Application)|site]] and the [[Administrator (Application)|administrator]], '''only component manifests can include this element'''.

==== Back-end files ====

Files to copy to the back-end directory should be placed in the <code><files></code> element under the <code><administration></code>. You can use the optional <code>folder</code> attribute to specify a directory '''in the ZIP package''' to copy '''from'''. See ''Front-end files'' for further rules.

==== Menu links and submenus ====

<source lang="xml">
<menu>COM_EXAMPLE</menu>
<submenu>
<menu link="anoption=avalue">COM_EXAMPLE_SUBMENU_ANOPTION</menu>
<menu view="viewname">COM_EXAMPLE_SUBMENU_VIEWNAME</menu>
</submenu>
</source>

The text for the main menu item for the component is defined in the <code><menu></code> item, a child of <code><administration></code>. A <code><submenu></code> element may also be present (also a child of <code><administration></code>), which may contain more menu items defined by <code><menu></code>.

Additionally, each <code><menu></code> item can define the following attributes:

{| class="wikitable"
! style="width: 150px" | Attribute || Description
|-
| link || A link to send the user to when the menu item is clicked
|-
| img || The (relative) path to an image (16x16 pixels) to appear beside the menu item.
<u>Must be an url compatible as a file too (e.g. no spaces) !</u>
|-
| alt ||
|-
| ''string'' || An URL parameter to add to the link. For example, <code><menu view="cpanel">COM_EXAMPLE</menu></code> in com_example's XML manifest would cause the URL of the menu item to be <tt>index.php?option=com_example&view=cpanel</tt>.
|-
|}

The value inside the tag is the menu's label. Unlike Joomla! 1.5, you can not use a natural language string. For example, if you would enter "Example Component" instead of COM_EXAMPLE, it would result in your component name appearing as example-component in the menu and you would be unable to provide a translation. In order to provide a translation you need to create a file named en-GB.com_example.sys.ini in administrator/languages/en-GB (you can use the manifest's <code><languages></code> tag to copy it during installation) or in administrator/components/com_example/language/en-GB. In the latter case, you must not include the translation file in the <code><languages></code> tag. As long as you have placed the language directory in your <code><files></code> tag, it will be copied along when the component is being installed.

The contents of that file should be:
<source>
COM_EXAMPLE="Example Component"
COM_EXAMPLE_SUBMENU_ANOPTION="Another Option"
COM_EXAMPLE_SUBMENU_VIEWNAME="Another View"

</source>

Please note that the language string must be enclosed in double quotes, as per Joomla!'s translation standards. Important note: Joomla! 1.6 and later sorts the Component menu items based on the actual translation of the key you supply in your XML manifest. This means that the sorting order is correct no matter what you call your translation key and no matter which language the site is being displayed in. Essentially, Joomla! 1.6 fixed the wrong sorting of the Components menu experienced under Joomla! 1.5 for the majority (non-English speaking!) of Joomla! users.

{{Needsinfo|In Platform 11.1 no alt attribute processed and if link provide in menu tag other provided attributes were ignore. The other tags are task, view, controller, act, layout, sub. Please confirm this, please.}}

=== Configuration ===
{{warning|Components '''do not support''' configuration definitions '''in the manifest'''. This is a way implemented in Joomla! 1.5. They can define configuration options for multiple levels using [[Component configuration metadata]].}}
The <code><config></code> element, a child of the root, describes the configuration options for the extension. If applicable, the options will be shown by the appropriate Manager (Plugin Manager, Module Manager or Template Manager). '''Configuration options can also be defined in a separate file named <code>config.xml</code>. Its root element should be <code><config></code>.'''

{{:XML JForm form definitions}}

=== SQL ===

<source lang="xml">
<install folder="admin">
<sql>
<file driver="mysql" charset="utf8">sql/example.install.sql</file>
</sql>
</install>
<uninstall folder="admin">
<sql>
<file driver="mysql" charset="utf8">sql/example.uninstall.sql</file>
</sql>
</uninstall>
</source>

In the above example, we put the SQL files in the "admin/sql" folder of the installation package. You have to include the "sql" folder in the administration files.

You can execute SQL during the installation and/or uninstallation using the <code><install></code> and <code><uninstall></code> elements, respectively. A <code><sql></code> element should appear as a child of these elements. <code><sql></code> can contain any number of <code><file></code> elements, each defining a single SQL file to execute. Their database driver types are described by the <code>driver</code> attribute, their character sets by the <code>charset</code> attribute.

==== Update of the SQL schema ====

<source lang="xml">
<update>
<schemas>
<schemapath type="mysql">sql/updates/mysql</schemapath>
<schemapath type="sqlsrv">sql/updates/sqlsrv</schemapath>
</schemas>
</update>
</source>

Since 1.6, there is also an <code><update></code> tag, which allows you to provide a series of SQL files to update the current schema.

=== Language files ===
In Joomla! 1.5, extension developers had to put extension language files in the Joomla! main language file, using the <languages>..</languages> tag as shown below. '''This method can still be used in''' {{rarr|2.5,3.x}}.

<source lang="xml">

<languages folder="langfiles">
<language tag="en-GB">en-GB.com_example.ini</language>
</languages>
</source>

Since Joomla! 1.6 it has been encouraged placing your extension's language files in your extension folder. Joomla! will then automatically load your extension's language files.

By storing extension language files in the extension folder, you gain the benefit of isolating and protecting your extension's language files. For example, an administrator removes a language from their Joomla! installation. Your extension's language files will not be removed. They will remain in place and will be available if the language is installed again.

The structure of the language folder for frontend and backend is the same. You put them in the language tag (e.g. '''en-GB''' ) of each language in your language folder i.e. '''language/en-GB/'''. You have to specify those folders in the front-end and back-end files too.

In your manifest you simply include the ''''language'''' folder in your files section, the sub-directories for each language automatically be copied. Inside the <files> group you simply add a <folder> element alongside the items in the '''<files>''' group as shown in this example:

<source lang="xml">
<files>
<filename plugin="alpha">alpha.php</filename>
<folder>sql</folder>
<folder>language</folder>
</files>
</source>

It is also notable that both ways can work together. Here is an example from core:
<source lang="xml">
<files>
<filename plugin="languagecode">languagecode.php</filename>
<filename>index.html</filename>
<folder>language</folder>
</files>
<languages>
<language tag="en-GB">language/en-GB/en-GB.plg_system_languagecode.ini</language>
<language tag="en-GB">language/en-GB/en-GB.plg_system_languagecode.sys.ini</language>
</languages>
</source>

The advantages of this solution are the following:

All ini files present in the core folder have precedence over the files in the extension language/ folder.
For example a sys.ini file will always be loaded from core folders in back-end if it exists, except when installing an extension which contains a sys.ini file in a language folder. In that case and only that case, the sys.ini file in the extension folder will display its translated content at install time. This is very handy as a developer can have 2 sys.ini files with different contents. A description of the successful install as well as a tutorial in back-end for example.

Also, it is much easier for a user needing an ini file for an extension that does not provide it in the language desired, to add it in the main folders. No risk for it to be deleted in case of uninstalling the extension by mistake or any other reason.

See also:
*[[J2.5:Making non-core language packs|Making non-core language packs]]
*[[Creating language packs for extensions in Joomla 2.5]]

During development you can turn on language debugging in the Joomla! global configuration. So you can investigate if a problems arises. As of 3.2, this is necessary to help debug as en-GB is '''always''' loaded first when not in debug mode to prevent displaying Constants.

=== Script file ===

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

An optional '''script file''' (PHP code that is run before, during and/or after installation, uninstallation and upgrading) can be defined using a <code><scriptfile></code> element. This file should contain a class named "<element_name>IntallerScript" where <element_name> is the name of your extension (e.g. com_componentname, mod_modulename, etc.). Plugins requires to state the group (e.g. plgsystempluginname). Library packages do not support scriptfiles. The structure of the class is as follows:

<source lang="php">

class com_componentnameInstallerScript
{
/**
* Constructor
*
* @param JAdapterInstance $adapter The object responsible for running this script
*/
public function __construct(JAdapterInstance $adapter);

/**
* Called before any type of action
*
* @param string $route Which action is happening (install|uninstall|discover_install|update)
* @param JAdapterInstance $adapter The object responsible for running this script
*
* @return boolean True on success
*/
public function preflight($route, JAdapterInstance $adapter);

/**
* Called after any type of action
*
* @param string $route Which action is happening (install|uninstall|discover_install|update)
* @param JAdapterInstance $adapter The object responsible for running this script
*
* @return boolean True on success
*/
public function postflight($route, JAdapterInstance $adapter);

/**
* Called on installation
*
* @param JAdapterInstance $adapter The object responsible for running this script
*
* @return boolean True on success
*/
public function install(JAdapterInstance $adapter);

/**
* Called on update
*
* @param JAdapterInstance $adapter The object responsible for running this script
*
* @return boolean True on success
*/
public function update(JAdapterInstance $adapter);

/**
* Called on uninstallation
*
* @param JAdapterInstance $adapter The object responsible for running this script
*/
public function uninstall(JAdapterInstance $adapter);
}

</source>

=== Update servers ===

<source lang="xml">
<updateservers>
<server type="extension" priority="1" name="Extension Update Site">http://example.com/extension.xml</server>
<server type="collection" priority="2" name="Collection Update Site">http://example.com/collection.xml</server>
</updateservers>
</source>

Update servers can be defined in the <code><updateservers></code> element, a child of the root. This element may contain one or more <code><server></code> element, each describing a location to fetch updates from. Each <code><server></code> item can define the following attributes:

{| class="wikitable"
! style="width: 150px" | Attribute || style="width: 150px" | Values || Description
|-
| type || <code>extension</code><br /><code>collection</code> || The update server type
|-
| priority || ''integer'' || The priority of the update server
|-
| name || ''string'' || The name of the update server
|}

More info:
* [[J2.5:Developing a MVC Component/Adding an update server|Building a Joomla! Extension - Adding an update server]]
* [[J2.5:Managing Component Updates|Managing Component Updates in Joomla 2.5]]

== Examples ==
For a real-life example, see [https://github.com/joomla/joomla-cms/blob/2.5.x/administrator/components/com_banners/banners.xml the manifest of the Banner component in the latest version of Joomla! 2.5].

The Joomla testing process uses several extensions to test whether the installer works correctly. The latest versions of the manifests of these extensions are:

* [http://svn.joomla.org/project/cms/development/trunk/tests/_data/installer_packages/com_alpha/alpha.xml com_alpha manifest]
* [http://svn.joomla.org/project/cms/development/trunk/tests/_data/installer_packages/mod_alpha/mod_alpha.xml mod_alpha manifest]
* [http://svn.joomla.org/project/cms/development/trunk/tests/_data/installer_packages/plg_system_alpha/alpha.xml plg_system_alpha manifest]
* [http://svn.joomla.org/project/cms/development/trunk/tests/_data/installer_packages/tpl_simple/templateDetails.xml tpl_simple manifest]
* [http://svn.joomla.org/project/cms/development/trunk/tests/_data/installer_packages/lng_xx-XX/xx-XX.xml lng_xx-XX manifest]

== Contributors ==
*[[User:akede|Alex Kempkens]]
*[[User:dperaza|Daniel Peraza]]
*[[User:nikosdion|Nicholas K. Dionysopoulos]]
*[[User:mrs.siam|Prasit Gebsaap]]
*[[User:cppl|Craig Phillips]]

[[Category:Extension development]]
[[Category:Specifications]]

Framework:Home

2013-06-15T15:54:48Z

Mvangeest: /* What is the Joomla Framework ? */ Fixed links

{{:{{FULLPAGENAME}}/header}}__NOTOC__
<div style="width:auto; vertical-align:top; background-color:#fff; margin:5px 0 10px 0; padding:8px; box-shadow: 1px 1px 8px #000;">
<div style="float:right; padding-left:15px;"><markdown>
[![Build Status](https://travis-ci.org/joomla/joomla-framework.png?branch=master)](https://travis-ci.org/joomla/joomla-framework)
</markdown></div>
== What is the Joomla Framework ? ==

The <code>Joomla Framework</code> is a platform for writing web and command line applications in PHP. It is free and open source software, distributed under the GNU General Public License version 2 or later.

It is comprises code originally developed for the Joomla Content Management System (CMS). For more information about the Joomla CMS visit http://www.joomla.org/about-joomla.html.

For news and information about developering with Joomla, please visit http://developer.joomla.org.

View the Joomla Framework API Documentation at http://joomla.github.io/joomla-framework. Powered by [http://www.phpdoc.org phpDocumentor 2].

You can discuss Joomla Framework development by joining the mailing list at http://groups.google.com/group/joomla-dev-framework.

== Requirements ==

* PHP 5.3.10

== Installation ==
=== Via Composer ===

* Create a project and add a <code>composer.json</code> file to it with the content :

<pre class="json">{
"require": {
"joomla/joomla-framework": "dev-master"
}
}</pre>
* Download Composer

<code>curl -sS <nowiki>https://getcomposer.org/installer</nowiki> | php</code>

* Install the Joomla Framework

<code>php composer.phar install</code>

=== Via Git ===

<code><nowiki>git clone git://github.com/joomla/joomla-framework.git</nowiki></code>

== Documentation ==

General documentation about the Joomla Platform can be found under the [https://github.com/joomla/joomla-framework/tree/master/docs /docs] folder of the Git repository. In addition, each package has documentation in a <code>README.md</code> file.

== Reporting Bugs and Issue ==

Bugs and issues found in the Joomla Framework code can be reported on the [https://github.com/joomla/joomla-framework/issues Issues] list.

== Contributing ==

All kind of contributions are welcome. Please read about how to contribute [https://github.com/joomla/joomla-framework/blob/master/CONTRIBUTING.markdown here].

You may find tasks you can do on the [https://github.com/joomla/joomla-framework/issues Issues] list by filtering on labels and milestones
</div>
[[Category:Joomla! Framework]]

Chunk:Platform

2013-06-14T23:37:13Z

Mvangeest: Cleaned up

<noinclude>{{chunk}}</noinclude>__NOTOC__
<blockquote style="width:auto; border:1px solid grey; background-color:cornsilk; padding:5px; font-style:italic;">The Joomla Platform is a platform for writing Web and command line applications in PHP. It is free and open source software, distributed under the GNU General Public License version 2 or later. The Joomla Content Management System (CMS) is built on top of the Joomla Platform.<ref>https://github.com/joomla/joomla-platform</ref></blockquote>

[[File:Architecture Joomla Platform.png|frame|400px|The Joomla! Platform]]

As of 24 April 2013, the Platform project has been retired. The Platform has been merged back into the [[CMS]], and the [[Framework]] has taken its place as the standalone application framework for Joomla! applications.<ref>[https://github.com/joomla/joomla-platform/blob/84014ad35b0d6294a43fcd2745aecb130849ed9e/CONTRIBUTING.markdown CONTRIBUTING.markdown]</ref><ref>https://groups.google.com/d/msg/joomla-dev-platform/zzNrsCUKCts/hsBntnONm9MJ</ref>

The release of the Joomla Platform on 5 July 2011<ref>http://developer.joomla.org/code/cms/history/2010/12/02.html</ref> marked an important change in the Joomla! CMS architecture. The Joomla! CMS was initially a monolithic application. One of the aims of the Joomla! project was to separate the codebase into the CMS and an underlying library, which could then be reused for other projects. In version 1.5 and 1.6, that separation was prepared by creating a division between the [[Framework (CMS 1.5 and 1.6)]] ''(which is unrelated to the new [[Framework]] project)'' and the Joomla! [[CMS]] Application. The Joomla! Platform project continued this effort by separating that framework into an independent project (both in terms of code and organization). The Joomla! Platform is an independent set of libraries which do not depend on the Joomla! CMS Application. These libraries are made up of libraries maintained by the Joomla! Project and libraries maintained by other 3rd party developers. The Platform could be used for web and command-line applications entirely independent of and unrelated to the CMS.

The home of the Joomla! Platform was [https://github.com/joomla/joomla-platform the ''joomla/joomla-platform'' GitHub repository] that contains the source and documentation. The Platform stopped accepting contributions on or before 24 April 2013.
<noinclude><references/></noinclude>

Framework (CMS 1.5 and 1.6)

2013-06-14T16:46:38Z

Mvangeest: Adjusted link after page move

{{Chunk:Framework quote}}
{{Chunk:Framework (CMS 1.5 and 1.6)}}
== API Reference ==

On this page we'd like to provide you a way to reference of all classes and respective methods. Use the links below to navigate to further information about framework versions or the version classes which include, where possible, examples of use.

If you would like to help us improve this resource, please read about the [[API Reference Project]].

{{Navbox
|state=off
|navbar=off
|title=API documentation is available in the following '''Joomla! Framework Versions'''
|titlestyle=font-weight:normal; padding:5px;
|image=[[File:Joomla vert logo.png|120px]]
|group1= Select a framework version
|group2= See also
|group1style=font-size:1.1em; width:18%;
|list1=
* [[API15:Framework|Framework]] {{JVer|1.5}}
* [[API16:Framework|Framework]] {{JVer|1.6}}
|list2=
* [[API17:Platform|Platform]] {{JVer|11.1}}
|list1style=padding-left:10px; font-size:1.2em;
|list2style=padding-left:10px; font-size:1.2em;
}}

=== See Also ===
<references/>
=== Further Reading ===
*[[Joomla! Framework vs Joomla! Platform]]
<noinclude>[[Category:Framework]][[Category:Subpackages]]</noinclude>

Joomla! Framework (CMS 1.5 and 1.6) vs Joomla! Platform

2013-06-14T16:28:07Z

Mvangeest: Updated contents

{{notice|This page discusses the differences between the Framework in the 1.5 and 1.6 versions of the Joomla CMS and the now-retired Joomla Platform. For information about the Joomla Framework project, see [[Framework]].}}

== Framework (CMS 1.5 and 1.6) ==
{{Chunk:Framework (CMS 1.5 and 1.6)}}
== Introduction to Platform ==
{{Chunk:Platform}}
== Differences ==
The Joomla! Platform can now be used to build other CMS Applications or Web and command line Applications specific to a developer's needs such as eCommerce, Social Media, and other stand alone Applications. The Platform is stored on GitHub, which allows developers to easily fork the Platform code for their own purposes, and then if they want, integrate it into the main code branch. This will encourage more developers and even attract larger corporations to contribute to the Joomla! Platform who might not have done so before.<ref>http://magazine.joomla.org/issues/Issue-Dec-2011/item/616-Write-your-own-App-using-Joomla-Platform?tmpl=component&print=1</ref>

Another good thing about the separation of the the Joomla! Platform it has a release schedule of every 3 months which allows for a faster integration of core features used by extension developers. The version number is determined by the the year of its release. For example, Joomla! Platform 11.1 was released in 2011 and 12.1 was released in 2012.<ref>http://magazine.joomla.org/issues/Issue-Dec-2011/item/616-Write-your-own-App-using-Joomla-Platform?tmpl=component&print=1</ref>
== See also and References ==
<references/>
<noinclude>[[Category:Platform]][[Category:Framework]][[Category:Frameworks and Platforms]]</noinclude>

Joomla! Framework vs Joomla! Platform

2013-06-14T16:24:16Z

Mvangeest: Mvangeest moved page Joomla! Framework vs Joomla! Platform to Joomla! Framework (CMS 1.5 and 1.6) vs Joomla! Platform: The name Framework has been reused for the new Joomla Framework project

#REDIRECT [[Joomla! Framework (CMS 1.5 and 1.6) vs Joomla! Platform]]

Joomla! Framework (CMS 1.5 and 1.6) vs Joomla! Platform

2013-06-14T16:24:16Z

{{review}}
== Framework ==
{{Chunk:Framework (CMS 1.5 and 1.6)}}
== Introduction to Platform ==
{{Chunk:Platform}}
== Differences ==
The Joomla! Platform can now be used to build other CMS Applications or Web and command line Applications specific to a developer's needs such as eCommerce, Social Media, and other stand alone Applications. The Platform is stored on GitHub, which allows developers to easily fork the Platform code for their own purposes, and then if they want, integrate it into the main code branch. This will encourage more developers and even attract larger corporations to contribute to the Joomla! Platform who might not have done so before.<ref>http://magazine.joomla.org/issues/Issue-Dec-2011/item/616-Write-your-own-App-using-Joomla-Platform?tmpl=component&print=1</ref>

Another good thing about the separation of the the Joomla! Platform it has a release schedule of every 3 months which allows for a faster integration of core features used by extension developers. The version number is determined by the the year of its release. For example, Joomla! Platform 11.1 was released in 2011 and 12.1 was released in 2012.<ref>http://magazine.joomla.org/issues/Issue-Dec-2011/item/616-Write-your-own-App-using-Joomla-Platform?tmpl=component&print=1</ref>
== See also and References ==
<references/>
<noinclude>[[Category:Platform]][[Category:Framework]][[Category:Frameworks and Platforms]]</noinclude>

Chunk:Framework

2013-06-14T16:14:48Z

Mvangeest: Added link

<noinclude>{{chunk}}</noinclude>__NOTOC__
The Joomla Framework is a platform for writing web and command line applications in PHP. It is free and open source software, distributed under the GNU General Public License version 2 or later.<ref>https://github.com/joomla/joomla-framework/</ref>

The Framework comprises code originally developed for the Joomla [[Content Management System]] and is a continuation of the [[Platform]] project. The Joomla Framework and the Joomla CMS are separate projects with separate development teams. Unlike the Platform, the Framework is not primarily intended as a platform for the Joomla CMS, and the Joomla CMS is not currently built on the Framework. More information about the differences between the Platform and the Framework can be found in [http://magazine.joomla.org/issues/issue-mar-2013/item/1136-differences-between-the-joomla-framework-and-joomla-platform the March 2013 edition of the Joomla Community Magazine].
<noinclude><references/></noinclude>

Chunk:Platform

2013-06-14T15:36:53Z

Mvangeest: Fixed layout, hopefully

<noinclude>{{chunk}}</noinclude>__NOTOC__
<blockquote style="width:auto; border:1px solid grey; background-color:cornsilk; padding:5px; font-style:italic;">The Joomla Platform is a platform for writing Web and command line applications in PHP. It is free and open source software, distributed under the GNU General Public License version 2 or later. The Joomla Content Management System (CMS) is built on top of the Joomla Platform.<ref>https://github.com/joomla/joomla-platform</ref></blockquote>

[[File:Architecture Joomla Platform.png|frame|400px|The Joomla! Platform]]

As of 24 April 2013, the Platform project has been retired. The Platform has been merged back into the [[CMS]] (see also http://github.com/joomla/joomla-cms), and the [[Framework]] (see also http://github.com/joomla/joomla-framework) has taken its place as the standalone application framework for Joomla! applications.<ref>[https://github.com/joomla/joomla-platform/blob/84014ad35b0d6294a43fcd2745aecb130849ed9e/CONTRIBUTING.markdown CONTRIBUTING.markdown]</ref><ref>https://groups.google.com/d/msg/joomla-dev-platform/zzNrsCUKCts/hsBntnONm9MJ</ref>

The release of the Joomla Platform on 5 July 2011<ref>http://developer.joomla.org/code/cms/history/2010/12/02.html</ref> marked an important change in the Joomla! CMS architecture. The Joomla! CMS was initially a monolithic application. One of the aims of the Joomla! project was to separate the codebase into the CMS and an underlying library, which could then be reused for other projects. In version 1.5 and 1.6, that separation was prepared by creating a division between the [[Framework (CMS 1.5 and 1.6)]] ''(which is unrelated to the new [[Framework]] project)'' and the Joomla! [[CMS]] Application. The Joomla! Platform project continued this effort by separating that framework into an independent project (both in terms of code and organization). The Joomla! Platform is an independent set of libraries which do not depend on the Joomla! CMS Application. These libraries are made up of libraries maintained by the Joomla! Project and libraries maintained by other 3rd party developers. The Platform could be used for web and command-line applications entirely independent of and unrelated to the CMS.

The home of the Joomla! Platform was [https://github.com/joomla/joomla-platform the ''joomla/joomla-platform'' GitHub repository] that contains the source and documentation. The Platform stopped accepting contributions on or before 24 April 2013.
<noinclude><references/></noinclude>

Main Page

2013-06-14T15:33:30Z

Mvangeest: The Platform has been retired - updated references to the Framework

__NOTOC__
{| cellspacing="0" cellpadding="0" style="margin:0em 0em 1em 0em; width:100%;"
| colspan="1" style="width:100%; vertical-align:top; border:1px solid #B356C1; background-color:#fff; -moz-border-radius:10px; border-radius:10px;" |
<div style="background-color:#fff; padding:0.8em 1.1em 0 1.1em; margin:0 7px;"><h1><span class="mw-headline">Joomla! Official Documentation</span></h1></div>
<div style="padding:1em 1em 1em 1em;"> 

{| cellspacing="0" cellpadding="0" style="margin:0em 0em 1em 0em; width:100%"
| style="width:50%; vertical-align:top; border:1px solid #abd5f5; background-color: #fff;-moz-border-radius:10px; border-radius:10px;" rowspan="1"|
<div style="border-bottom:1px solid abd5f5; background-color:#d0e5f5; padding:0.2em 0.5em 0.2em 0.5em; font-size:110%; font-weight:bold; -moz-border-radius:10px 10px 0 0; border-radius:10px 10px 0 0;">Reader profiles</div>
<div style="padding:0.4em 1em 0.3em 1em;">

Find the profile that most accurately describes your role and you will find the documentation that you need more quickly. These are the most frequent profiles...
* [[Beginners]]
* [[Developers]]
* [[Web designers]]
* [[Administrators]]
* [[Evaluators]]
* [[Joomla! Code Contributors]]
None of the above? Then look for [[Start here|more user profiles]].
</div>

| style="padding:0em 0.5em 0em 0.5em;" |

| style="width:30%; vertical-align:top; background-color: #fff;-moz-border-radius:10px; border-radius:10px;" rowspan="1"|
<div style="border-bottom:1px solid abd5f5; background-color:#fff; padding:0.2em 0.5em 0.2em 0.5em; font-size:110%; font-weight:bold;-moz-border-radius:10px 10px 0 0; border-radius:10px 10px 0 0;">Quick links</div>
<div style="padding:0.4em 1em 0.3em 1em;">

* [[:Category:FAQ|Frequently Asked Questions]]
* [[:Category:Tips and tricks|Tips and tricks]]
* [[Security Checklist|Joomla! Security Checklist]]
* [[Vulnerable Extensions List]]
* [[:Category:Top_Level|Browse all categories]]
* [[JDOC:Wiki policy|Wiki policy]]
* [[JEDL|Documentation license]]
* [[Framework:Home|Joomla! Framework]]
* [[Glossary]]
* [[References]]
</div>

| style="padding:0em 0.5em 0em 0.5em;" |

| style="vertical-align:top; border:none; background-color:#fff;" |

[[Image:documentation_all_together.jpg|border|right]]
|}

{| cellspacing="0" cellpadding="0" style="margin:0em 0em 1em 0em; width:100%"
| style="width:50%; vertical-align:top; border:1px solid #abd5f5; background-color: #f1f5fc;-moz-border-radius:10px; border-radius:10px;" rowspan="1"|
<div style="border-bottom:1px solid abd5f5; background-color:#d0e5f5; padding:0.2em 0.5em 0.2em 0.5em; font-size:110%; font-weight:bold;-moz-border-radius:10px 10px 0 0; border-radius:10px 10px 0 0;">Getting started</div>
<div style="padding:0.4em 1em 0.3em 1em;">

If you have only recently starting working with Joomla you will probably have experienced the pain of learning a new system. New terminology, new ways of doing things, perhaps even the web itself may be new to you. Then let these guides relieve some of that pain.

* [[J3.1:Getting Started with Joomla!|Getting Started with Joomla! 3.x]] {{JVer|3.x}}
* [[Getting Started with Joomla!|Getting Started with Joomla! 2.5]] {{JVer|2.5}}
* [[J1.5:Getting Started with Joomla!|Getting Started with Joomla! 1.5]] {{JVer|1.5}}
</div>

| style="padding:0em 0.5em 0em 0.5em;" |

| style="width:50%; vertical-align:top; border:1px solid Gold; background-color: LightYellow;-moz-border-radius:10px; border-radius:10px;" |
<div style="border-bottom:1px solid #Gold; background-color:#ffffaa; padding:0.2em 0.5em 0.2em 0.5em; font-size:110%; font-weight:bold;-moz-border-radius:10px 10px 0 0; border-radius:10px 10px 0 0;">Important</div>
<div style="padding:0.4em 1em 0.3em 1em;">

'''You don't need to register here if you just want to read the documentation.'''

You should only register if you want to make changes to the information contained here. Also note that registration on this wiki is entirely separate from registration on our other sites, such as the [http://forum.joomla.org forum].
</div>
|}

</div>
|}

{| cellspacing="0" cellpadding="0" style="margin:0em 0em 1em 0em; width:100%"
| style="width:50%; vertical-align:top; border:1px solid #abd5f5; background-color: #f1f5fc;-moz-border-radius:10px; border-radius:10px;" rowspan="1"|
<div style="border-bottom:1px solid abd5f5; background-color:#d0e5f5; padding:0.2em 0.5em 0.2em 0.5em; font-size:110%; font-weight:bold;-moz-border-radius:10px 10px 0 0; border-radius:10px 10px 0 0;">Coming soon</div>
<div style="padding:0.4em 1em 0.3em 1em;">

With Joomla 2.5 safely released the focus of development is shifting to 3. Joomla 3.1 was released in April 2013. This is the second of a new series (3.0/3.1/3.2/3.5) and maintaining backwards compatibility with 2.5 will not be required.

* [[:Category:Version 3.1 FAQ|Version 3.1 FAQs]]
</div>

| style="padding:0em 0.5em 0em 0.5em;" |

| style="width:50%; vertical-align:top; border:1px solid Gold; background-color: LightYellow;-moz-border-radius:10px; border-radius:10px;" |
<div style="border-bottom:1px solid #Gold; background-color:#ffffaa; padding:0.2em 0.5em 0.2em 0.5em; font-size:110%; font-weight:bold;-moz-border-radius:10px 10px 0 0; border-radius:10px 10px 0 0;">Joomla [[Framework]]</div>
<div style="padding:0.4em 1em 0.3em 1em;">

The Joomla Framework, a modern PHP application platform project independent of the CMS, is available.

* [https://github.com/joomla/joomla-framework Joomla Framework on Github]
* [http://joomla.github.io/joomla-framework/ API documentation]
* [[Platform|The Platform, predecessor of the Framework]]
</div>
|}

{| cellspacing="0" cellpadding="0" style="margin:0em 0em 1em 0em; width:100%"
| style="width:50%; vertical-align:top; border:1px solid #abd5f5; background-color: #f1f5fc;-moz-border-radius:10px; border-radius:10px;" rowspan="1"|
<div style="border-bottom:1px solid abd5f5; background-color:#d0e5f5; padding:0.2em 0.5em 0.2em 0.5em; font-size:110%; font-weight:bold;-moz-border-radius:10px 10px 0 0; border-radius:10px 10px 0 0;">Quick links for [[Administrators]]</div>
<div style="padding:0.4em 1em 0.3em 1em;">

* [[Joomla Installation|Installation]]
* [[Template Management]]
* [[Article Management]]
* [[User Management|User and Access Management]]
* [[Menu Management]]
* [[Security]]
* [[Module Management]]
* [[Component Management]]
* [[Category Management]]
* [[Plugin Management]]
* [[Global Configuration Management]]
</div>

| style="padding:0em 0.5em 0em 0.5em;" |

| style="width:50%; vertical-align:top; border:1px solid Gold; background-color: LightYellow;-moz-border-radius:10px; border-radius:10px;" |
<div style="border-bottom:1px solid #Gold; background-color:#ffffaa; padding:0.2em 0.5em 0.2em 0.5em; font-size:110%; font-weight:bold;-moz-border-radius:10px 10px 0 0; border-radius:10px 10px 0 0;">{{JVer|{{CurrentLTSVer|minor}}}} Joomla! {{CurrentLTSVer|minor}}</div>
<div style="padding:0.4em 1em 0.3em 1em;">

Joomla! {{CurrentLTSVer|minor}} is the current [[Release and support cycle|LTS version]]. The previous LTS version, Joomla 1.5, is still widely used and will be supported with security fixes only until September 2012.
* [[J2.5:Upgrading_from_an_existing_version|Upgrading your site from 1.6/1.7 to 2.5]]
* [[J2.5:Migrating_from_Joomla_1.5_to_Joomla_2.5|Migrating your site from 1.5 to 2.5]]
* [[:Category:Version {{CurrentLTSVer}} FAQ|Version {{CurrentLTSVer}} FAQ]]
* [http://www.joomla.org/about-joomla/technical-requirements.html Technical Requirements]
* [[Installing Joomla!]]

For more information see the [[:Category:Joomla! {{CurrentLTSVer|minor}}|Joomla {{CurrentLTSVer|minor}} category page]].
</div>
|}

{| cellspacing="0" cellpadding="0" style="margin:0em 0em 1em 0em; width:100%"
| style="width:50%; vertical-align:top; border:1px solid #abd5f5; background-color: #f1f5fc;-moz-border-radius:10px; border-radius:10px;" rowspan="1"|
<div style="border-bottom:1px solid abd5f5; background-color:#d0e5f5; padding:0.2em 0.5em 0.2em 0.5em; font-size:110%; font-weight:bold;-moz-border-radius:10px 10px 0 0; border-radius:10px 10px 0 0;">Quick links for [[Developers]]</div>
<div style="padding:0.4em 1em 0.3em 1em;">

* [http://api.joomla.org/ Platform API Documentation]
* [[Template Development|Templates]]
* [[Component Development|Components]]
* [[Module Development|Modules]]
* [[Language Development|Languages]]
* [[Plugin Development|Plugins]]
* [[CMS]] versus [[Platform]]
* [http://developer.joomla.org Joomla! Developer Portal]
* [[Portal:Bug_Squad|Joomal! Bug Squad members]]
</div>

| style="padding:0em 0.5em 0em 0.5em;" |

| style="width:50%; vertical-align:top; border:1px solid Gold; background-color: LightYellow;-moz-border-radius:10px; border-radius:10px;" |
<div style="border-bottom:1px solid #Gold; background-color:#ffffaa; padding:0.2em 0.5em 0.2em 0.5em; font-size:110%; font-weight:bold;-moz-border-radius:10px 10px 0 0; border-radius:10px 10px 0 0;">{{JVer|{{CurrentSTSVer|minor}}}} Joomla! {{CurrentSTSVer|minor}}</div>
<div style="padding:0.4em 1em 0.3em 1em;">

Joomla {{CurrentSTSVer|minor}} is the latest [[Release and support cycle|STS version]] after Joomla 2.5. Support for Joomla {{CurrentSTSVer|minor}} is still active.
* [[Technical requirements]]
* [[J{{CurrentSTSVer|minor}}:Installing Joomla!|Installing Joomla! {{CurrentSTSVer|major}}]]
* [[J{{CurrentSTSVer|minor}}:What's new in Joomla!|What's new]]
* [[J{{CurrentSTSVer|minor}}:Access_Control_List_Tutorial|Access control system]]


* [[:Category:Version {{CurrentSTSVer}} FAQ|Version {{CurrentSTSVer}} FAQ]]

For more information see the [[:Category:Joomla! {{CurrentSTSVer|minor}}|Joomla {{CurrentSTSVer|minor}} category page]].
</div>
|}

{| cellspacing="0" cellpadding="0" style="margin:0em 0em 1em 0em; width:100%"
| colspan="1" style="width:100%; vertical-align:top; border:1px solid Sienna; background-color:Cornsilk;-moz-border-radius:10px; border-radius:10px;" |
<div style="border-bottom:1px solid Sienna; background-color:Wheat; padding:0.2em 0.5em 0.2em 0.5em; font-size:130%; font-weight:bold;-moz-border-radius:10px 10px 0 0; border-radius:10px 10px 0 0;">Helping with the documentation effort</div>
<div style="padding:1em 1em 1em 1em;"> 

{| cellspacing="0" cellpadding="0" style="margin:0em 0em 1em 0em; width:100%"
| style="width:50%; vertical-align:top; border:1px solid #abd5f5; background-color: #f1f5fc;-moz-border-radius:10px; border-radius:10px;" rowspan="1"|
<div style="border-bottom:1px solid abd5f5; background-color:#d0e5f5; padding:0.2em 0.5em 0.2em 0.5em; font-size:110%; font-weight:bold;-moz-border-radius:10px 10px 0 0; border-radius:10px 10px 0 0;">Documentation Projects</div>
<div style="padding:0.4em 1em 0.3em 1em;">

You don't need to join the [[Documentation Working Group]] to help us improve the documentation. Just [[Special:UserLogin|register]] on this wiki and get started. Feel free to fix any errors you find; take a look in the [[JDOC:Cookie jar|Cookie jar]]; or consider helping out in one of our mini-projects...

{{:JDOC:Projects}}
</div>

| style="padding:0em 0.5em 0em 0.5em;background-color:CornSilk;" |

| style="width:50%; vertical-align:top; border:1px solid Gold; background-color: White;-moz-border-radius:10px; border-radius:10px;" |
<div style="border-bottom:1px solid #Gold; background-color:#ffffaa; padding:0.2em 0.5em 0.2em 0.5em; font-size:110%; font-weight:bold;-moz-border-radius:10px 10px 0 0; border-radius:10px 10px 0 0;">Most popular pages</div>
<div style="padding:0.4em 1em 0.3em 1em;">

{{Most popular pages}}
</div>
|}

</div>
|}
{{license}}

Chunk:Platform

2013-06-14T15:24:07Z

Mvangeest: Updated contents, adjusted layout

<noinclude>{{chunk}}</noinclude>__NOTOC__
<blockquote style="width:auto; border:1px solid grey; background-color:cornsilk; padding:5px; font-style:italic;">The Joomla Platform is a platform for writing Web and command line applications in PHP. It is free and open source software, distributed under the GNU General Public License version 2 or later. The Joomla Content Management System (CMS) is built on top of the Joomla Platform.<ref>https://github.com/joomla/joomla-platform</ref></blockquote>

[[File:Architecture Joomla Platform.png|frame|400px|The Joomla! Platform]]

As of 24 April 2013, the Platform project has been retired. The Platform has been merged back into the [[CMS]] (see also http://github.com/joomla/joomla-cms), and the [[Framework]] (see also http://github.com/joomla/joomla-framework) has taken its place as the standalone application framework for Joomla! applications.<ref>[https://github.com/joomla/joomla-platform/blob/84014ad35b0d6294a43fcd2745aecb130849ed9e/CONTRIBUTING.markdown CONTRIBUTING.markdown]</ref><ref>https://groups.google.com/d/msg/joomla-dev-platform/zzNrsCUKCts/hsBntnONm9MJ</ref>

The release of the Joomla Platform on 5 July 2011<ref>http://developer.joomla.org/code/cms/history/2010/12/02.html</ref> marked an important change in the Joomla! CMS architecture. The Joomla! CMS was initially a monolithic application. One of the aims of the Joomla! project was to separate the codebase into the CMS and an underlying library, which could then be reused for other projects. In version 1.5 and 1.6, that separation was prepared by creating a division between the [[Framework (CMS 1.5 and 1.6)]] ''(which is unrelated to the new [[Framework]] project)'' and the Joomla! [[CMS]] Application. The Joomla! Platform project continued this effort by separating that framework into an independent project (both in terms of code and organization). The Joomla! Platform is an independent set of libraries which do not depend on the Joomla! CMS Application. These libraries are made up of libraries maintained by the Joomla! Project and libraries maintained by other 3rd party developers. The Platform could be used for web and command-line applications entirely independent of and unrelated to the CMS.

The home of the Joomla! Platform was [https://github.com/joomla/joomla-platform the ''joomla/joomla-platform'' GitHub repository] that contains the source and documentation. The Platform stopped accepting contributions on or before 24 April 2013.

<noinclude><references/></noinclude>

Framework

2013-06-14T14:39:42Z

Mvangeest: Started page about the Framework project

{{Chunk:Framework}}
The home of the Joomla! Framework is [https://github.com/joomla/joomla-framework/ the joomla/joomla-framework GitHub repository] that contains the source, documentation and means to contribute (pull requests).

API documentation for the Framework can be found on http://joomla.github.io/joomla-framework/.

Framework development can be discussed on [http://groups.google.com/group/joomla-dev-framework the joomla-dev-framework Google Group].

== References ==
<references/>

Chunk:Framework

2013-06-14T14:32:21Z

Mvangeest: Started page about the Framework project

Talk:Framework (CMS 1.5 and 1.6)

2013-06-14T14:20:36Z

Mvangeest: Mvangeest moved page Talk:Framework to Talk:Framework (CMS 1.5 and 1.6): The name Framework has been reused for the new Joomla Framework project

== Wanted pages on the Framework ==

While emptying the Tutorial namespace, I deleted the Tutorial:Framework page. It only contained a sentence praising the exquisite flexibility of the "new, streamlined" framework, plus the following two links:
* [[framework:database_part1|Using the 1.5 Database Libraries]]
* [[framework:router_part1|Creating Custom URLs]]
These pages were probably requested by developers, so if anyone has the time to write them, please do.
[[User:Mvangeest|Mvangeest]] 18:29, 14 January 2011 (UTC)

Framework

2013-06-14T14:20:35Z

Mvangeest: Mvangeest moved page Framework to Framework (CMS 1.5 and 1.6): The name Framework has been reused for the new Joomla Framework project

#REDIRECT [[Framework (CMS 1.5 and 1.6)]]

Framework (CMS 1.5 and 1.6)

2013-06-14T14:20:34Z

Mvangeest: Mvangeest moved page Framework to Framework (CMS 1.5 and 1.6): The name Framework has been reused for the new Joomla Framework project

{{Chunk:Framework quote}}
{{Chunk:Framework}}
== API Reference ==

On this page we'd like to provide you a way to reference of all classes and respective methods. Use the links below to navigate to further information about framework versions or the version classes which include, where possible, examples of use.

If you would like to help us improve this resource, please read about the [[API Reference Project]].

{{Navbox
|state=off
|navbar=off
|title=API documentation is available in the following '''Joomla! Framework Versions'''
|titlestyle=font-weight:normal; padding:5px;
|image=[[File:Joomla vert logo.png|120px]]
|group1= Select a framework version
|group2= See also
|group1style=font-size:1.1em; width:18%;
|list1=
* [[API15:Framework|Framework]] {{JVer|1.5}}
* [[API16:Framework|Framework]] {{JVer|1.6}}
|list2=
* [[API17:Platform|Platform]] {{JVer|11.1}}
|list1style=padding-left:10px; font-size:1.2em;
|list2style=padding-left:10px; font-size:1.2em;
}}

=== See Also ===
<references/>
=== Further Reading ===
*[[Joomla! Framework vs Joomla! Platform]]
<noinclude>[[Category:Framework]][[Category:Subpackages]]</noinclude>

API16:Framework

2013-06-14T14:18:43Z

Mvangeest: Archive maintenance: a page move could have caused major confusion

{{Chunk:Framework (CMS 1.5 and 1.6)}}

{| class="wikitable"
|-
|-
|[[API16:JAccess|JAccess]]
|[[API16:JElementComponentLayouts|JElementComponentLayouts]]
|[[API16:JFormFieldSQL|JFormFieldSQL]]
|[[API16:JPane|JPane]]
|-
|[[API16:JAdapter|JAdapter]]
|[[API16:JElementContentLanguages|JElementContentLanguages]]
|[[API16:JFormFieldSessionHandler|JFormFieldSessionHandler]]
|[[API16:JPaneSliders|JPaneSliders]]
|-
|[[API16:JAdapterInstance|JAdapterInstance]]
|[[API16:JElementEditors|JElementEditors]]
|[[API16:JFormFieldSpacer|JFormFieldSpacer]]
|[[API16:JPaneTabs|JPaneTabs]]
|-
|[[API16:JApplication|JApplication]]
|[[API16:JElementFilelist|JElementFilelist]]
|[[API16:JFormFieldTemplateStyle|JFormFieldTemplateStyle]]
|[[API16:JParameter|JParameter]]
|-
|[[API16:JApplicationHelper|JApplicationHelper]]
|[[API16:JElementFolderlist|JElementFolderlist]]
|[[API16:JFormFieldText|JFormFieldText]]
|[[API16:JPath|JPath]]
|-
|[[API16:JArchive|JArchive]]
|[[API16:JElementHelpsites|JElementHelpsites]]
|[[API16:JFormFieldTextarea|JFormFieldTextarea]]
|[[API16:JPathway|JPathway]]
|-
|[[API16:JArchiveBzip2|JArchiveBzip2]]
|[[API16:JElementHidden|JElementHidden]]
|[[API16:JFormFieldTimezone|JFormFieldTimezone]]
|[[API16:JPlugin|JPlugin]]
|-
|[[API16:JArchiveGzip|JArchiveGzip]]
|[[API16:JElementImageList|JElementImageList]]
|[[API16:JFormFieldUser|JFormFieldUser]]
|[[API16:JPluginHelper|JPluginHelper]]
|-
|[[API16:JArchiveTar|JArchiveTar]]
|[[API16:JElementLanguages|JElementLanguages]]
|[[API16:JFormFieldUserGroup|JFormFieldUserGroup]]
|[[API16:JProfiler|JProfiler]]
|-
|[[API16:JArchiveZip|JArchiveZip]]
|[[API16:JElementList|JElementList]]
|[[API16:JFormRule|JFormRule]]
|[[API16:JRegistry|JRegistry]]
|-
|[[API16:JArrayHelper|JArrayHelper]]
|[[API16:JElementMenu|JElementMenu]]
|[[API16:JFormRuleBoolean|JFormRuleBoolean]]
|[[API16:JRegistryFormat|JRegistryFormat]]
|-
|[[API16:JAuthentication|JAuthentication]]
|[[API16:JElementMenuItem|JElementMenuItem]]
|[[API16:JFormRuleEmail|JFormRuleEmail]]
|[[API16:JRegistryFormatINI|JRegistryFormatINI]]
|-
|[[API16:JAuthenticationResponse|JAuthenticationResponse]]
|[[API16:JElementModuleLayouts|JElementModuleLayouts]]
|[[API16:JFormRuleEquals|JFormRuleEquals]]
|[[API16:JRegistryFormatJSON|JRegistryFormatJSON]]
|-
|[[API16:JBrowser|JBrowser]]
|[[API16:JElementPassword|JElementPassword]]
|[[API16:JFormRuleRules|JFormRuleRules]]
|[[API16:JRegistryFormatPHP|JRegistryFormatPHP]]
|-
|[[API16:JBuffer|JBuffer]]
|[[API16:JElementRadio|JElementRadio]]
|[[API16:JFormRuleUsername|JFormRuleUsername]]
|[[API16:JRegistryFormatXML|JRegistryFormatXML]]
|-
|[[API16:JButton|JButton]]
|[[API16:JElementSQL|JElementSQL]]
|[[API16:JFormValidator|JFormValidator]]
|[[API16:JRequest|JRequest]]
|-
|[[API16:JButtonConfirm|JButtonConfirm]]
|[[API16:JElementSpacer|JElementSpacer]]
|[[API16:JFrameworkConfig|JFrameworkConfig]]
|[[API16:JResponse|JResponse]]
|-
|[[API16:JButtonCustom|JButtonCustom]]
|[[API16:JElementTemplateStyle|JElementTemplateStyle]]
|[[API16:JHelp|JHelp]]
|[[API16:JRoute|JRoute]]
|-
|[[API16:JButtonHelp|JButtonHelp]]
|[[API16:JElementText|JElementText]]
|[[API16:JHtml|JHtml]]
|[[API16:JRouter|JRouter]]
|-
|[[API16:JButtonLink|JButtonLink]]
|[[API16:JElementTextarea|JElementTextarea]]
|[[API16:JHtmlAccess|JHtmlAccess]]
|[[API16:JRule|JRule]]
|-
|[[API16:JButtonPopup|JButtonPopup]]
|[[API16:JElementTimezones|JElementTimezones]]
|[[API16:JHtmlBehavior|JHtmlBehavior]]
|[[API16:JRules|JRules]]
|-
|[[API16:JButtonSeparator|JButtonSeparator]]
|[[API16:JElementUserGroup|JElementUserGroup]]
|[[API16:JHtmlCategory|JHtmlCategory]]
|[[API16:JSession|JSession]]
|-
|[[API16:JButtonStandard|JButtonStandard]]
|[[API16:JError|JError]]
|[[API16:JHtmlContent|JHtmlContent]]
|[[API16:JSessionStorage|JSessionStorage]]
|-
|[[API16:JCache|JCache]]
|[[API16:JEvent|JEvent]]
|[[API16:JHtmlEmail|JHtmlEmail]]
|[[API16:JSessionStorageApc|JSessionStorageApc]]
|-
|[[API16:JCacheCallback|JCacheCallback]]
|[[API16:JException|JException]]
|[[API16:JHtmlForm|JHtmlForm]]
|[[API16:JSessionStorageDatabase|JSessionStorageDatabase]]
|-
|[[API16:JCacheOutput|JCacheOutput]]
|[[API16:JExtension|JExtension]]
|[[API16:JHtmlGrid|JHtmlGrid]]
|[[API16:JSessionStorageEaccelerator|JSessionStorageEaccelerator]]
|-
|[[API16:JCachePage|JCachePage]]
|[[API16:JFTP|JFTP]]
|[[API16:JHtmlImage|JHtmlImage]]
|[[API16:JSessionStorageMemcache|JSessionStorageMemcache]]
|-
|[[API16:JCacheStorage|JCacheStorage]]
|[[API16:JFactory|JFactory]]
|[[API16:JHtmlJGrid|JHtmlJGrid]]
|[[API16:JSessionStorageNone|JSessionStorageNone]]
|-
|[[API16:JCacheStorageApc|JCacheStorageApc]]
|[[API16:JFeedEnclosure|JFeedEnclosure]]
|[[API16:JHtmlList|JHtmlList]]
|[[API16:JSessionStorageXcache|JSessionStorageXcache]]
|-
|[[API16:JCacheStorageEaccelerator|JCacheStorageEaccelerator]]
|[[API16:JFeedImage|JFeedImage]]
|[[API16:JHtmlMenu|JHtmlMenu]]
|[[API16:JSimpleCrypt|JSimpleCrypt]]
|-
|[[API16:JCacheStorageFile|JCacheStorageFile]]
|[[API16:JFeedItem|JFeedItem]]
|[[API16:JHtmlRules|JHtmlRules]]
|[[API16:JSimpleXML|JSimpleXML]]
|-
|[[API16:JCacheStorageMemcache|JCacheStorageMemcache]]
|[[API16:JFile|JFile]]
|[[API16:JHtmlSelect|JHtmlSelect]]
|[[API16:JSimpleXMLElement|JSimpleXMLElement]]
|-
|[[API16:JCacheStorageXCache|JCacheStorageXCache]]
|[[API16:JFilesystemHelper|JFilesystemHelper]]
|[[API16:JHtmlSliders|JHtmlSliders]]
|[[API16:JStream|JStream]]
|-
|[[API16:JCacheView|JCacheView]]
|[[API16:JFilterInput|JFilterInput]]
|[[API16:JHtmlString|JHtmlString]]
|[[API16:JStreamString|JStreamString]]
|-
|[[API16:JCategories|JCategories]]
|[[API16:JFilterOutput|JFilterOutput]]
|[[API16:JHtmlTabs|JHtmlTabs]]
|[[API16:JString|JString]]
|-
|[[API16:JCategoryNode|JCategoryNode]]
|[[API16:JFolder|JFolder]]
|[[API16:JInstaller|JInstaller]]
|[[API16:JStringController|JStringController]]
|-
|[[API16:JClientHelper|JClientHelper]]
|[[API16:JForm|JForm]]
|[[API16:JInstallerComponent|JInstallerComponent]]
|[[API16:JTable|JTable]]
|-
|[[API16:JComponentHelper|JComponentHelper]]
|[[API16:JFormField|JFormField]]
|[[API16:JInstallerFile|JInstallerFile]]
|[[API16:JTableAsset|JTableAsset]]
|-
|[[API16:JController|JController]]
|[[API16:JFormFieldAccessLevel|JFormFieldAccessLevel]]
|[[API16:JInstallerHelper|JInstallerHelper]]
|[[API16:JTableCategory|JTableCategory]]
|-
|[[API16:JControllerForm|JControllerForm]]
|[[API16:JFormFieldCacheHandler|JFormFieldCacheHandler]]
|[[API16:JInstallerLanguage|JInstallerLanguage]]
|[[API16:JTableContent|JTableContent]]
|-
|[[API16:JDatabase|JDatabase]]
|[[API16:JFormFieldCalendar|JFormFieldCalendar]]
|[[API16:JInstallerLibrary|JInstallerLibrary]]
|[[API16:JTableExtension|JTableExtension]]
|-
|[[API16:JDatabaseMySQL|JDatabaseMySQL]]
|[[API16:JFormFieldCategory|JFormFieldCategory]]
|[[API16:JInstallerModule|JInstallerModule]]
|[[API16:JTableMenu|JTableMenu]]
|-
|[[API16:JDatabaseMySQLi|JDatabaseMySQLi]]
|[[API16:JFormFieldCheckbox|JFormFieldCheckbox]]
|[[API16:JInstallerPackage|JInstallerPackage]]
|[[API16:JTableMenuType|JTableMenuType]]
|-
|[[API16:JDatabaseQuery|JDatabaseQuery]]
|[[API16:JFormFieldCombo|JFormFieldCombo]]
|[[API16:JInstallerPlugin|JInstallerPlugin]]
|[[API16:JTableModule|JTableModule]]
|-
|[[API16:JDatabaseQueryElement|JDatabaseQueryElement]]
|[[API16:JFormFieldComponentLayout|JFormFieldComponentLayout]]
|[[API16:JInstallerTemplate|JInstallerTemplate]]
|[[API16:JTableNested|JTableNested]]
|-
|[[API16:JDate|JDate]]
|[[API16:JFormFieldContentLanguage|JFormFieldContentLanguage]]
|[[API16:JLDAP|JLDAP]]
|[[API16:JTableSession|JTableSession]]
|-
|[[API16:JDispatcher|JDispatcher]]
|[[API16:JFormFieldEditor|JFormFieldEditor]]
|[[API16:JLanguage|JLanguage]]
|[[API16:JTableUpdate|JTableUpdate]]
|-
|[[API16:JDocument|JDocument]]
|[[API16:JFormFieldEditors|JFormFieldEditors]]
|[[API16:JLanguageHelper|JLanguageHelper]]
|[[API16:JTableUser|JTableUser]]
|-
|[[API16:JDocumentError|JDocumentError]]
|[[API16:JFormFieldFile|JFormFieldFile]]
|[[API16:JLanguageTransliterate|JLanguageTransliterate]]
|[[API16:JTableUsergroup|JTableUsergroup]]
|-
|[[API16:JDocumentFeed|JDocumentFeed]]
|[[API16:JFormFieldFileList|JFormFieldFileList]]
|[[API16:JLibraryManifest|JLibraryManifest]]
|[[API16:JTableViewlevel|JTableViewlevel]]
|-
|[[API16:JDocumentHTML|JDocumentHTML]]
|[[API16:JFormFieldFolderList|JFormFieldFolderList]]
|[[API16:JLog|JLog]]
|[[API16:JText|JText]]
|-
|[[API16:JDocumentJSON|JDocumentJSON]]
|[[API16:JFormFieldGroupedList|JFormFieldGroupedList]]
|[[API16:JMail|JMail]]
|[[API16:JToolBar|JToolBar]]
|-
|[[API16:JDocumentRAW|JDocumentRAW]]
|[[API16:JFormFieldHelpsite|JFormFieldHelpsite]]
|[[API16:JMailHelper|JMailHelper]]
|[[API16:JTree|JTree]]
|-
|[[API16:JDocumentRenderer|JDocumentRenderer]]
|[[API16:JFormFieldHidden|JFormFieldHidden]]
|[[API16:JMenu|JMenu]]
|[[API16:JURI|JURI]]
|-
|[[API16:JDocumentRendererAtom|JDocumentRendererAtom]]
|[[API16:JFormFieldImageList|JFormFieldImageList]]
|[[API16:JModel|JModel]]
|[[API16:JUpdate|JUpdate]]
|-
|[[API16:JDocumentRendererComponent|JDocumentRendererComponent]]
|[[API16:JFormFieldInteger|JFormFieldInteger]]
|[[API16:JModelForm|JModelForm]]
|[[API16:JUpdateAdapter|JUpdateAdapter]]
|-
|[[API16:JDocumentRendererHead|JDocumentRendererHead]]
|[[API16:JFormFieldLanguage|JFormFieldLanguage]]
|[[API16:JModelItem|JModelItem]]
|[[API16:JUpdater|JUpdater]]
|-
|[[API16:JDocumentRendererMessage|JDocumentRendererMessage]]
|[[API16:JFormFieldList|JFormFieldList]]
|[[API16:JModelList|JModelList]]
|[[API16:JUpdaterCollection|JUpdaterCollection]]
|-
|[[API16:JDocumentRendererModule|JDocumentRendererModule]]
|[[API16:JFormFieldMedia|JFormFieldMedia]]
|[[API16:JModuleHelper|JModuleHelper]]
|[[API16:JUpdaterExtension|JUpdaterExtension]]
|-
|[[API16:JDocumentRendererModules|JDocumentRendererModules]]
|[[API16:JFormFieldMediamanager|JFormFieldMediamanager]]
|[[API16:JNode|JNode]]
|[[API16:JUser|JUser]]
|-
|[[API16:JDocumentRendererRSS|JDocumentRendererRSS]]
|[[API16:JFormFieldMenu|JFormFieldMenu]]
|[[API16:JObject|JObject]]
|[[API16:JUserHelper|JUserHelper]]
|-
|[[API16:JDocumentXML|JDocumentXML]]
|[[API16:JFormFieldMenuItem|JFormFieldMenuItem]]
|[[API16:JObservable|JObservable]]
|[[API16:JUtility|JUtility]]
|-
|[[API16:JEditor|JEditor]]
|[[API16:JFormFieldModuleLayout|JFormFieldModuleLayout]]
|[[API16:JObserver|JObserver]]
|[[API16:JVersion|JVersion]]
|-
|[[API16:JElement|JElement]]
|[[API16:JFormFieldPassword|JFormFieldPassword]]
|[[API16:JPackageManifest|JPackageManifest]]
|[[API16:JView|JView]]
|-
|[[API16:JElementCalendar|JElementCalendar]]
|[[API16:JFormFieldRadio|JFormFieldRadio]]
|[[API16:JPagination|JPagination]]
|[[API16:JXMLElement|JXMLElement]]
|-
|[[API16:JElementCategory|JElementCategory]]
|[[API16:JFormFieldRules|JFormFieldRules]]
|[[API16:JPaginationObject|JPaginationObject]]
|
|}
==References==
<references/>

API15:Framework

2013-06-14T14:18:16Z

Mvangeest: Archive maintenance: a page move could have caused major confusion

<span class="editsection" style="font-size:76%;">
<nowiki>[</nowiki>[[Chunk:Framework (CMS 1.5 and 1.6)|Edit Descripton]]<nowiki>]</nowiki>
</span>
{{Chunk:Framework (CMS 1.5 and 1.6)}}

{| class="wikitable"
|-
|-
|[[API15:JApplication|JApplication]]
|[[API15:JDocumentRenderer|JDocumentRenderer]]
|[[API15:JHTMLContent|JHTMLContent]]
|[[API15:JRegistryFormatPHP|JRegistryFormatPHP]]
|-
|[[API15:JApplicationHelper|JApplicationHelper]]
|[[API15:JDocumentRendererAtom|JDocumentRendererAtom]]
|[[API15:JHTMLEmail|JHTMLEmail]]
|[[API15:JRegistryFormatXML|JRegistryFormatXML]]
|-
|[[API15:JArchive|JArchive]]
|[[API15:JDocumentRendererComponent|JDocumentRendererComponent]]
|[[API15:JHTMLForm|JHTMLForm]]
|[[API15:JRequest|JRequest]]
|-
|[[API15:JArchiveBzip2|JArchiveBzip2]]
|[[API15:JDocumentRendererHead|JDocumentRendererHead]]
|[[API15:JHTMLGrid|JHTMLGrid]]
|[[API15:JResponse|JResponse]]
|-
|[[API15:JArchiveGzip|JArchiveGzip]]
|[[API15:JDocumentRendererMessage|JDocumentRendererMessage]]
|[[API15:JHTMLImage|JHTMLImage]]
|[[API15:JRoute|JRoute]]
|-
|[[API15:JArchiveTar|JArchiveTar]]
|[[API15:JDocumentRendererModule|JDocumentRendererModule]]
|[[API15:JHTMLList|JHTMLList]]
|[[API15:JRouter|JRouter]]
|-
|[[API15:JArchiveZip|JArchiveZip]]
|[[API15:JDocumentRendererModules|JDocumentRendererModules]]
|[[API15:JHTMLMenu|JHTMLMenu]]
|[[API15:JSession|JSession]]
|-
|[[API15:JArrayHelper|JArrayHelper]]
|[[API15:JDocumentRendererRSS|JDocumentRendererRSS]]
|[[API15:JHTMLSelect|JHTMLSelect]]
|[[API15:JSessionStorage|JSessionStorage]]
|-
|[[API15:JAuthentication|JAuthentication]]
|[[API15:JEditor|JEditor]]
|[[API15:JHelp|JHelp]]
|[[API15:JSessionStorageApc|JSessionStorageApc]]
|-
|[[API15:JAuthenticationResponse|JAuthenticationResponse]]
|[[API15:JElement|JElement]]
|[[API15:JInstaller|JInstaller]]
|[[API15:JSessionStorageDatabase|JSessionStorageDatabase]]
|-
|[[API15:JAuthorization|JAuthorization]]
|[[API15:JElementCalendar|JElementCalendar]]
|[[API15:JInstallerComponent|JInstallerComponent]]
|[[API15:JSessionStorageEaccelerator|JSessionStorageEaccelerator]]
|-
|[[API15:JBrowser|JBrowser]]
|[[API15:JElementCategory|JElementCategory]]
|[[API15:JInstallerHelper|JInstallerHelper]]
|[[API15:JSessionStorageMemcache|JSessionStorageMemcache]]
|-
|[[API15:JBuffer|JBuffer]]
|[[API15:JElementEditors|JElementEditors]]
|[[API15:JInstallerLanguage|JInstallerLanguage]]
|[[API15:JSessionStorageNone|JSessionStorageNone]]
|-
|[[API15:JButton|JButton]]
|[[API15:JElementFilelist|JElementFilelist]]
|[[API15:JInstallerModule|JInstallerModule]]
|[[API15:JSessionStorageXcache|JSessionStorageXcache]]
|-
|[[API15:JButtonConfirm|JButtonConfirm]]
|[[API15:JElementFolderlist|JElementFolderlist]]
|[[API15:JInstallerPlugin|JInstallerPlugin]]
|[[API15:JSimpleCrypt|JSimpleCrypt]]
|-
|[[API15:JButtonCustom|JButtonCustom]]
|[[API15:JElementHelpsites|JElementHelpsites]]
|[[API15:JInstallerTemplate|JInstallerTemplate]]
|[[API15:JSimpleXML|JSimpleXML]]
|-
|[[API15:JButtonHelp|JButtonHelp]]
|[[API15:JElementHidden|JElementHidden]]
|[[API15:JLDAP|JLDAP]]
|[[API15:JSimpleXMLElement|JSimpleXMLElement]]
|-
|[[API15:JButtonLink|JButtonLink]]
|[[API15:JElementImageList|JElementImageList]]
|[[API15:JLanguage|JLanguage]]
|[[API15:JString|JString]]
|-
|[[API15:JButtonPopup|JButtonPopup]]
|[[API15:JElementLanguages|JElementLanguages]]
|[[API15:JLanguageHelper|JLanguageHelper]]
|[[API15:JTable|JTable]]
|-
|[[API15:JButtonSeparator|JButtonSeparator]]
|[[API15:JElementList|JElementList]]
|[[API15:JLog|JLog]]
|[[API15:JTableARO|JTableARO]]
|-
|[[API15:JButtonStandard|JButtonStandard]]
|[[API15:JElementMenu|JElementMenu]]
|[[API15:JMail|JMail]]
|[[API15:JTableAROGroup|JTableAROGroup]]
|-
|[[API15:JCache|JCache]]
|[[API15:JElementMenuItem|JElementMenuItem]]
|[[API15:JMailHelper|JMailHelper]]
|[[API15:JTableCategory|JTableCategory]]
|-
|[[API15:JCacheCallback|JCacheCallback]]
|[[API15:JElementPassword|JElementPassword]]
|[[API15:JMenu|JMenu]]
|[[API15:JTableComponent|JTableComponent]]
|-
|[[API15:JCacheOutput|JCacheOutput]]
|[[API15:JElementRadio|JElementRadio]]
|[[API15:JModel|JModel]]
|[[API15:JTableContent|JTableContent]]
|-
|[[API15:JCachePage|JCachePage]]
|[[API15:JElementSQL|JElementSQL]]
|[[API15:JModuleHelper|JModuleHelper]]
|[[API15:JTableMenu|JTableMenu]]
|-
|[[API15:JCacheStorage|JCacheStorage]]
|[[API15:JElementSection|JElementSection]]
|[[API15:JNode|JNode]]
|[[API15:JTableMenuTypes|JTableMenuTypes]]
|-
|[[API15:JCacheStorageApc|JCacheStorageApc]]
|[[API15:JElementSpacer|JElementSpacer]]
|[[API15:JObject|JObject]]
|[[API15:JTableModule|JTableModule]]
|-
|[[API15:JCacheStorageEaccelerator|JCacheStorageEaccelerator]]
|[[API15:JElementText|JElementText]]
|[[API15:JObservable|JObservable]]
|[[API15:JTablePlugin|JTablePlugin]]
|-
|[[API15:JCacheStorageFile|JCacheStorageFile]]
|[[API15:JElementTextarea|JElementTextarea]]
|[[API15:JObserver|JObserver]]
|[[API15:JTableSection|JTableSection]]
|-
|[[API15:JCacheStorageMemcache|JCacheStorageMemcache]]
|[[API15:JElementTimezones|JElementTimezones]]
|[[API15:JPagination|JPagination]]
|[[API15:JTableSession|JTableSession]]
|-
|[[API15:JCacheStorageXCache|JCacheStorageXCache]]
|[[API15:JElementUserGroup|JElementUserGroup]]
|[[API15:JPaginationObject|JPaginationObject]]
|[[API15:JTableUser|JTableUser]]
|-
|[[API15:JCacheView|JCacheView]]
|[[API15:JError|JError]]
|[[API15:JPane|JPane]]
|[[API15:JTemplate|JTemplate]]
|-
|[[API15:JClientHelper|JClientHelper]]
|[[API15:JEvent|JEvent]]
|[[API15:JPaneSliders|JPaneSliders]]
|[[API15:JText|JText]]
|-
|[[API15:JComponentHelper|JComponentHelper]]
|[[API15:JException|JException]]
|[[API15:JPaneTabs|JPaneTabs]]
|[[API15:JToolBar|JToolBar]]
|-
|[[API15:JController|JController]]
|[[API15:JFTP|JFTP]]
|[[API15:JParameter|JParameter]]
|[[API15:JTree|JTree]]
|-
|[[API15:JDatabase|JDatabase]]
|[[API15:JFactory|JFactory]]
|[[API15:JPath|JPath]]
|[[API15:JURI|JURI]]
|-
|[[API15:JDatabaseMySQL|JDatabaseMySQL]]
|[[API15:JFeedEnclosure|JFeedEnclosure]]
|[[API15:JPathway|JPathway]]
|[[API15:JUser|JUser]]
|-
|[[API15:JDatabaseMySQLi|JDatabaseMySQLi]]
|[[API15:JFeedImage|JFeedImage]]
|[[API15:JPlugin|JPlugin]]
|[[API15:JUserHelper|JUserHelper]]
|-
|[[API15:JDate|JDate]]
|[[API15:JFeedItem|JFeedItem]]
|[[API15:JPluginHelper|JPluginHelper]]
|[[API15:JUtility|JUtility]]
|-
|[[API15:JDispatcher|JDispatcher]]
|[[API15:JFile|JFile]]
|[[API15:JProfiler|JProfiler]]
|[[API15:JVersion|JVersion]]
|-
|[[API15:JDocument|JDocument]]
|[[API15:JFilterInput|JFilterInput]]
|[[API15:JQuery|JQuery]]
|[[API15:JView|JView]]
|-
|[[API15:JDocumentError|JDocumentError]]
|[[API15:JFilterOutput|JFilterOutput]]
|[[API15:JQueryElement|JQueryElement]]
|[[API15:patTemplate_Function_Sef|patTemplate_Function_Sef]]
|-
|[[API15:JDocumentFeed|JDocumentFeed]]
|[[API15:JFolder|JFolder]]
|[[API15:JRecordSet|JRecordSet]]
|[[API15:patTemplate_Function_Translate|patTemplate_Function_Translate]]
|-
|[[API15:JDocumentHTML|JDocumentHTML]]
|[[API15:JFrameworkConfig|JFrameworkConfig]]
|[[API15:JRegistry|JRegistry]]
|[[API15:patTemplate_Modifier_SEF|patTemplate_Modifier_SEF]]
|-
|[[API15:JDocumentPDF|JDocumentPDF]]
|[[API15:JHTML|JHTML]]
|[[API15:JRegistryFormat|JRegistryFormat]]
|[[API15:patTemplate_Modifier_Translate|patTemplate_Modifier_Translate]]
|-
|[[API15:JDocumentRAW|JDocumentRAW]]
|[[API15:JHTMLBehavior|JHTMLBehavior]]
|[[API15:JRegistryFormatINI|JRegistryFormatINI]]
|
|}
==Reference==
<references/>

Joomla! Framework (CMS 1.5 and 1.6) vs Joomla! Platform

2013-06-14T14:15:46Z

Mvangeest: Adjusted link after page move

Chunk:Framework

2013-06-14T14:14:19Z

Mvangeest: Mvangeest moved page Chunk:Framework to Chunk:Framework (CMS 1.5 and 1.6): The name Framework has been reused for the new Joomla Framework project

#REDIRECT [[Chunk:Framework (CMS 1.5 and 1.6)]]

Chunk:Framework (CMS 1.5 and 1.6)

2013-06-14T14:14:19Z

Mvangeest: Mvangeest moved page Chunk:Framework to Chunk:Framework (CMS 1.5 and 1.6): The name Framework has been reused for the new Joomla Framework project

<noinclude>{{chunk}}</noinclude>__NOTOC__
{|
|-
|The Joomla! Framework<ref>See also [[Subpackages]]</ref> was an important part of the [[CMS Architecture in 1.5 and 1.6|Joomla! CMS architecture in the versions 1.5 and 1.6]]. It was based on modern object-oriented design patterns that make the Joomla core highly maintainable and easily extendable. Between April and July 2011, the Framework was rebranded as the Joomla! [[Platform]] and is now being developed separately from the Joomla! [[CMS]]. The first version of the CMS to ship with the Platform was version [[:Category:Joomla! 1.7|1.7]].

Third party developers benefit from the rich, and easily accessible functionality that the Joomla Framework provides.
|[[Image:JoomlaArchitecture0.png|thumb|425px|The Joomla Architecture]]
|}
<noinclude><references/></noinclude>

Enav/Beginners

2013-03-17T21:00:51Z

Mvangeest: Mvangeest moved page Enav/Beginners to User:Enav/Beginners: Moved page to the User namespace after user request

#REDIRECT [[User:Enav/Beginners]]

User:Enav/Beginners

2013-03-17T21:00:51Z

Mvangeest: Mvangeest moved page Enav/Beginners to User:Enav/Beginners: Moved page to the User namespace after user request

Welcome to Joomla!, a leading open source Content Management System (CMS) platform. Joomla! is a well-tested, extensible and effective tool supported by a very active and friendly community of developers and users.

This page contain several articles to quickly help you understand the basics of Joomla, and be able to create basic Joomla sites in a short time.

== What is Joomla? ==

If you are a boy from the old school (1990 ish) you may think that web sites still work with a bunch of linked HTML files, Not anymore buddy!, Welcome to century XXI! modern websites runs over Content Management Systems (CMS), this systems runs using dynamic languages like PHP and databases like MySQL databases, this way a CMS can store and manage huge amount of data like thousand of news articles articles.

So in short Joomla is a very flexible CMS that runs on PHP that uses MySQL databases to store the data and let you create websites with dynamic content that will change and adjust to the context or the configuration parameters you provide.

== Play with it ==

Do you want to get started with Joomla!, but you have no idea where to begin? If so, you have come to the right place. The fastest way to learn about Joomla is to start paying with it right now. Visit the demo page and take few minutes to see the demo content and play with the configurations.

Yes right here---> [http://demo.joomla.org/ Joomla demo page]

The first 2 term you need to learn are "Frontend" and "Backend", the Frontent is the part that shows your site content and all the funny stuff and the Backend is the part that contains the configuration views and it is also the place where you normally manage (create, edit, update) your content. To access to your Joomla site Backend you just need to add the "/administrators" to your Joomla site path in the browser address bar i.e.:

www.example.com/adminisrator

Now that you know how Joomla looks and feel in the frontend and backend is time to you to learn what kind of magic you can do with this new tool of yours.

Note: On the demo page you can chose to use a free trial hosting account, when the trial period expired if you chose to contract a paid hosting account with them, the Joomla! Project will receive a royalty for the transaction, consider this option if you would like to support the project.

== What can i do with it? ==

Joomla is a CMS, a system to manage content, To make a small analogy you can compare Joomla with a computer operative system, for example, on your computer the operative system manages the resources of your computer, also you can install applications to do more things on your computer, in this order of ideas Joomla is the one who is in charge to manage the data and you can install "extensions" to extend and enhance the functions of Joomla.

Joomla comes by default with a bunch of extensions pre-installed and pre-configured to make Joomla works as a News website, but you can manually configure your Joomla site to easily make it works as a:

* Blog site
* Company or Government site
* Contact directory
* Simple product Catalog

Now if your interest is to create more complex sites like:

* eCommerce sites with shopping cart
* Support sites with forums and ticket systems
* News sites with paid subscription system and comment systems
* e-learning sites with paid subscription systems

Then you need to install more Joomla extensions to make your vanilla Joomla site work the way you need. Lots and lots of extensions are for free with no cost at all, and others are extensions commercial, this means that you need to pay a fee to have the right to use them but the normally commercial extensions comes with a tech support deals that will help you save precious time and money, and everybody knows time is gold.

Here at [http://extensions.joomla.org/ The Joomla Extension Directory] you have thousands of extensions to chose from, take some time to visit the directory and do few searches for the sake to get familiarized with it, you may need to use some more extensions in the future if you decide to [http://www.youtube.com/watch?v=HYtbEmO_JC4 pimp up] your Joomla site.

Maybe a client or your boss is asking you for a web solution with a very specific set of requirements and the information so far does not help you to determine if Joomla is suitable for the job, in order to help you to save some time feel free to visit the Joomla community people and make your questions to humans at:

* The official [http://forum.joomla.org/ Joomla Forums]
* The official [http://webchat.freenode.net/?channels=joomla ##Joomla] IRC channel (aka chat room)
* The official [http://www.facebook.com/groups/joomlanospam/ Facebook group]

== Installing Joomla! ==

Now that you had enough fun playing with the Joomla demo site you may want to go the next level and start messing around with extensions and templates to see how they do in your very own local test server or your rented web server.

Follow one of this tutorials that suits you better.

* [[Installing Joomla on a rented web server]]
* [[Installing Joomla on a local web server]]

Note: This tutorials are targeted for non-expert audience, if you need more detailed and advanced information go to the [[developers | Developers page]].

== Understanding How Joomla Works ==

To keep this introductory article as short and friendly as possible we can say that Joomla have tow main parts, the Frontend and the Backend, as explained before the Frontend shows the site content that any visitor can see and the Backend is the administrative part that is normally restricted for users with privileges such as administrators.

Taking a quick look at the average website we can conclude that most of them have this basic layout:

* Header
* Main menu
* Main content
* Side content (left or right of main content)
* Footer

In Joomla a template is the one in charge to determine the layout and disposition of those chunks of data described in the previous list, also a template is the one used to determine the font types, colors, styles and the presentation in general.

Now you may wonder what is used to render each of those chunks of data, and the answer is modules and components. Joomla depends on extensions (components, modules, plugins) to render chunks of information that have certain characteristics, for example, for small and compact chunks of data like header, main menu, side content and footer Joomla uses Modules who are meant to be use for that kind of data, but for the main content of the page that tend to be a very large and dynamic chunk of data, the element in use is the component.

There are several kinds of plugins and they are categorized depending on the job they do, For example, A content plugin can be used to manipulate data before it is rendered on the page, an authentication plugin is a plugin that can give you the ability to login in a Joomla site using Google accounts or Facebook accounts.

In resume:

* Templates: Defines the site layout and visual styles.
* Component: Used to render large chucks of dynamic data.
* Modules: Used to render compact and normally static chunks of data.
* Plugins: They are used to extend the Joomla functions and manipulate data.

Both the frontend and the backend uses templates and extensions. Is a normal thing that many Joomla sites uses different templates on the frontend and leave the backend with the default template but you can always install a custom 3rd party template for the backend to have a different look and feel.

Note: Since most developers creates extensions based on how the default administrative template looks and work you may experience bugs and visual glitches with 3rd party administrative templates, so we recommend the use of the default Joomla template, most tutorials and documentation screenshots in general are based on the default Joomla administrative template.

Manifest files

2013-01-22T23:00:42Z

Mvangeest: /* Root element */ Corrected and (partly) updated information

{{incomplete}}
{{RightTOC}}
==Introduction==
Within Joomla there are manifest files for all of the extensions. These files include the general installation information as well as parameters for the configuration of the [[extension]] itself. Since Joomla! 1.6 {{JVer|1.6}}, there are very few differences between the manifest file formats for the different [[Extension types (technical definitions)|types of extensions]], allowing each type to access the full power of the Joomla! installer.

==Naming conventions==
The file must be named <tt>manifest.xml</tt> or <tt><extension_name>.xml</tt> and located in the root directory of the installation package.

==Syntax==

=== Root element ===
The primary tag of the installation file is:
<source lang=xml><extension></extension></source>

This starting and closing tags are now valid for all extensions. The new tag <code><extension></code> replaces the old <code><install></install></code> from Joomla {{JVer|1.5}}. The following attributes are allowed within the tag:

{|class="wikitable"
|-
! style="width: 150px" | Attribute || style="width: 150px" | Values || Applicable to || Description
|-
| type || <code>component</code><br /><code>file</code><br /><code>language</code><br /><code>library</code><br /><code>module</code><br /><code>package</code><br /><code>plugin</code><br /><code>template</code> || All extensions
| This attribute describes the type of the extension for the installer. Based on this type further requirements to sub-tags apply.
|-
| version
| <code>2.5</code> || All extensions
| String that identifies the version of Joomla for which this extension is developed.
|-
| method
| <code>install</code><br /><code>upgrade</code> || All extensions
| The default value <code>install</code> will be also used if the method attribute is not used. The <code>install</code> value means the installer will gracefully stop if it finds any existing file/folder of the new extension.
|-
| client
| <code>site</code><br /><code>administrator</code> || Modules
| The client attribute allows you to specify for which application client the new module is available.
|-
| group
| ''string'' || Plugins
| The group name specifies for which group of plugins the new plugin is available. The existing groups are the folder names within the directory <tt>/plugins</tt>. The installer will create new folder names for group names that do not exist yet.
|}

=== Metadata ===

The following elements can be used to insert metadata. None of these elements are required; if they are present, they must be a child of the root element.

* <code><name></code> – raw component name (e.g. <code>com_banners</code>)
* <code><author></code> – author's name (e.g. <code>Joomla! Project</code>)
* <code><creationDate></code> – date of creation or release (e.g. <code>April 2006</code>)
* <code><copyright></code> – a copyright statement (e.g. <code>(C) 2005 - 2011 Open Source Matters. All rights reserved.</code>)
* <code><license></code> – a license statement (e.g. <code>NU General Public License version 2 or later; see LICENSE.txt</code>)
* <code><authorEmail></code> – author's email address (e.g. <code><nowiki>admin@joomla.org</nowiki></code>)
* <code><authorUrl></code> – URL to the author's website (e.g. <code><nowiki>www.joomla.org</nowiki></code>)
* <code><version></code> – the version number of the extension (e.g. <code>1.6.0</code>)
* <code><description></code> – the description of the component. This is a translatable field. (e.g. <code>COM_BANNERS_XML_DESCRIPTION</code>)

=== Front-end files ===

<source lang="xml">
<files folder="from-folder">
<filename>example.php</filename>
<folder>examples</folder>
</files>
</source>

Files to copy to the front-end directory should be placed in the <code><files></code> element. You can use the optional <code>folder</code> attribute to specify a directory '''in the ZIP package''' to copy '''from'''. Each file to copy must be represented by a <code><filename></code> element. If you want to copy an entire folder at once, you can define it as a <code><folder></code>.

=== Media files ===

<source lang="xml>
<media folder="media" destination="com_example">
<filename>com_example_logo.png</filename>
<folder>css</folder>
<folder>js</folder>
</media>
</source>

This example will copy the file(s) (<tt>/media/com_example_logo.png</tt>) and folders ( <tt>/media/css/</tt> and <tt>/media/js/</tt> ) listed to <tt>/media/com_example/</tt>, creating the <tt>com_example</tt> folder if required. You can use the optional <code>folder</code> attribute to specify a directory '''in the ZIP package''' to copy '''from''' (in this case, <tt>media</tt>).

Extensions should be storing assets they need to be web accessible (JS, CSS, images etc) in <code>media</code>. Amongst other things this feature was added as step in the progression to multi-site support and the eventual move of code files (PHP) out of the web accessible areas of the server.

Ref:
* [https://groups.google.com/forum/#!msg/joomla-dev-cms/4CAASJqFY-k/PvPj14gP29EJ Google Groups - joomla-dev-cms thread]
* [https://groups.google.com/forum/#!msg/joomla-dev-cms/uNmhX98sKbE/p8p68Jke680J Google Groups - joomla-dev-cms thread]

=== Administration section ===

<source lang="xml">
<administration>

</administration>
</source>

The administration section is defined in the <code><administration></code> element. Since only [[Component|components]] apply to both the [[Site (Application)|site]] and the [[Administrator (Application)|administrator]], '''only component manifests can include this element'''.

==== Back-end files ====

Files to copy to the back-end directory should be placed in the <code><files></code> element under the <code><administration></code>. You can use the optional <code>folder</code> attribute to specify a directory '''in the ZIP package''' to copy '''from'''. See ''Front-end files'' for further rules.

==== Menu links and submenus ====

<source lang="xml">
<menu>COM_EXAMPLE</menu>
<submenu>
<menu link="anoption=avalue">COM_EXAMPLE_SUBMENU_ANOPTION</menu>
<menu view="viewname">COM_EXAMPLE_SUBMENU_VIEWNAME</menu>
</submenu>
</source>

The text for the main menu item for the component is defined in the <code><menu></code> item, a child of <code><administration></code>. A <code><submenu></code> element may also be present (also a child of <code><administration></code>), which may contain more menu items defined by <code><menu></code>.

Additionally, each <code><menu></code> item can define the following attributes:

{| class="wikitable"
! style="width: 150px" | Attribute || Description
|-
| link || A link to send the user to when the menu item is clicked
|-
| img || The (relative) path to an image (16x16 pixels) to appear beside the menu item.
<u>Must be an url compatible as a file too (e.g. no spaces) !</u>
| alt ||
|-
| ''string'' || An URL parameter to add to the link. For example, <code><menu view="cpanel">COM_EXAMPLE</menu></code> in com_example's XML manifest would cause the URL of the menu item to be <tt>index.php?option=com_example&view=cpanel</tt>.
|-
|}

The value inside the tag is the menu's label. Unlike Joomla! 1.5, you can not use a natural language string. For example, if you would enter "Example Component" instead of COM_EXAMPLE, it would result in your component name appearing as example-component in the menu and you would be unable to provide a translation. In order to provide a translation you need to create a file named en-GB.com_example.sys.ini in administrator/languages/en-GB (you can use the manifest's <code><languages></code> tag to copy it during installation) or in administrator/components/com_example/language/en-GB. In the latter case, you must not include the translation file in the <code><languages></code> tag. As long as you have placed the language directory in your <code><files></code> tag, it will be copied along when the component is being installed.

The contents of that file should be:
<source>
COM_EXAMPLE="Example Component"
COM_EXAMPLE_SUBMENU_ANOPTION="Another Option"
COM_EXAMPLE_SUBMENU_VIEWNAME="Another View"

</source>

Please note that the language string must be enclosed in double quotes, as per Joomla!'s translation standards. Important note: Joomla! 1.6 and later sorts the Component menu items based on the actual translation of the key you supply in your XML manifest. This means that the sorting order is correct no matter what you call your translation key and no matter which language the site is being displayed in. Essentially, Joomla! 1.6 fixed the wrong sorting of the Components menu for the majority (non-English speaking!) of Joomla! users experienced under Joomla! 1.5.

{{Needsinfo|In Platform 11.1 no alt attribute processed and if link provide in menu tag other provided attributes were ignore. The other tags are task, view, controller, act, layout, sub. Please confirm this, please.}}

=== Configuration ===
{{warning|Components '''do not support''' configuration definitions '''in the manifest'''. This is a way implemented in Joomla! 1.5. They can define configuration options for multiple levels using [[Component configuration metadata]].}}
The <code><config></code> element, a child of the root, describes the configuration options for the extension. If applicable, the options will be shown by the appropriate Manager (Plugin Manager, Module Manager or Template Manager). '''Configuration options can also be defined in a separate file named <code>config.xml</code>. Its root element should be <code><config></code>.'''

{{:XML JForm form definitions}}

=== SQL ===

<source lang="xml">
<install folder="admin">
<sql>
<file driver="mysql" charset="utf8">sql/example.install.sql</file>
</sql>
</install>
<uninstall folder="admin">
<sql>
<file driver="mysql" charset="utf8">sql/example.uninstall.sql</file>
</sql>
</uninstall>
</source>

In above example, we put sql files in "admin/sql" folder of installation package. You have to include "sql" folder in administration files.

You can execute SQL during installation and/or uninstallation using the <code><install></code> and <code><uninstall></code> elements, respectively. An <code><sql></code> element should appear as a child of these elements. <code><sql></code> can contain any number of <code><file></code> elements, each defining a single SQL file to execute. Their database driver types are described by the <code>driver</code> attribute, their character sets by the <code>charset</code> attribute.

==== Update of the SQL schema ====

<source lang="xml">
<update>
<schemas>
<schemapath type="mysql">sql/updates/mysql</schemapath>
<schemapath type="sqlsrv">sql/updates/sqlsrv</schemapath>
</schemas>
</update>
</source>

Since 1.6, there is also an <code><update></code> tag, which allows to provide a series of SQL files to update the current schema.

=== Language files ===
In Joomla! 1.5, we put extension language files in Joomla! main language file, using <languages>..</languages> tag as shown below. '''This tag considered to be deprecated since Joomla! 1.6.''' We encourage you to put extension 's language files in extension folder and Joomla! is responsible for loading of required language files.

<source lang="xml">

<languages folder="langfiles">
<language tag="en-GB">en-GB.com_example.ini</language>
</languages>
</source>

Storing extension language files in extension folder, you gain benefit when removing some language from Joomla! installation. As your language files were not removed, when reinstall the language again you can use that files without install them again.

The structure of language folder for frontend and backend is the same. You put them in <language> tag of your folder e.g. language/en-GB/. You have to specify these folders in front-end and back-end files too.

During development you can turn on language debuggin in Joomla! global configuration. So you can investigate if the problems exists.

=== Script file ===

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

An optional '''script file''' (PHP code that is run before, during and/or after installation, uninstallation and upgrading) can be defined using a <code><scriptfile></code> element. This file should contain a class named "<element_name>IntallerScript" where <element_name> is the name of your extension (e.g. com_componentname, mod_modulename, etc.). Plugins requires to state the group (e.g. plgsystempluginname). The structure of the class is as follows:

<source lang="php">

class com_componentnameInstallerScript
{
/**
* Constructor
*
* @param JAdapterInstance $adapter The object responsible for running this script
*/
public function __constructor(JAdapterInstance $adapter);

/**
* Called before any type of action
*
* @param string $route Which action is happening (install|uninstall|discover_install)
* @param JAdapterInstance $adapter The object responsible for running this script
*
* @return boolean True on success
*/
public function preflight($route, JAdapterInstance $adapter);

/**
* Called after any type of action
*
* @param string $route Which action is happening (install|uninstall|discover_install)
* @param JAdapterInstance $adapter The object responsible for running this script
*
* @return boolean True on success
*/
public function postflight($route, JAdapterInstance $adapter);

/**
* Called on installation
*
* @param JAdapterInstance $adapter The object responsible for running this script
*
* @return boolean True on success
*/
public function install(JAdapterInstance $adapter);

/**
* Called on update
*
* @param JAdapterInstance $adapter The object responsible for running this script
*
* @return boolean True on success
*/
public function update(JAdapterInstance $adapter);

/**
* Called on uninstallation
*
* @param JAdapterInstance $adapter The object responsible for running this script
*/
public function uninstall(JAdapterInstance $adapter);
}

</source>

=== Update servers ===

<source lang="xml">
<updateservers>
<server type="extension" priority="1" name="Extension Update Site">http://example.com/extension.xml</server>
<server type="collection" priority="2" name="Collection Update Site">http://example.com/collection.xml</server>
</updateservers>
</source>

Update servers can be defined in the <code><updateservers></code> element, a child of the root. This element may contain one or more <code><server></code> element, each describing a location to fetch updates from. Each <code><server></code> item can define the following attributes:

{| class="wikitable"
! style="width: 150px" | Attribute || style="width: 150px" | Values || Description
|-
| type || <code>extension</code><br /><code>collection</code> || The update server type
|-
| priority || ''integer'' || The priority of the update server
|-
| name || ''string'' || The name of the update server
|}

== Examples ==
For a real-life example, see [http://joomlacode.org/gf/project/joomla/scmsvn/?action=browse&path=%2Fdevelopment%2Ftags%2F1.6.x%2F1.6.5%2Fadministrator%2Fcomponents%2Fcom_banners%2Fbanners.xml&view=markup the manifest of the Banner component in version 1.6.5].

The Joomla testing process uses several extensions to test whether the installer works correctly. The latest versions of the manifests of these extensions are:

* [http://svn.joomla.org/project/cms/development/trunk/tests/_data/installer_packages/com_alpha/alpha.xml com_alpha manifest]
* [http://svn.joomla.org/project/cms/development/trunk/tests/_data/installer_packages/mod_alpha/mod_alpha.xml mod_alpha manifest]
* [http://svn.joomla.org/project/cms/development/trunk/tests/_data/installer_packages/plg_system_alpha/alpha.xml plg_system_alpha manifest]
* [http://svn.joomla.org/project/cms/development/trunk/tests/_data/installer_packages/tpl_simple/templateDetails.xml tpl_simple manifest]
* [http://svn.joomla.org/project/cms/development/trunk/tests/_data/installer_packages/lng_xx-XX/xx-XX.xml lng_xx-XX manifest]

== Contributors ==
*[[User:akede|Alex Kempkens]]
*[[User:dperaza|Daniel Peraza]]
*[[User:nikosdion|Nicholas K. Dionysopoulos]]
*[[User:mrs.siam|Prasit Gebsaap]]
*[[User:cppl|Craig Phillips]]

[[Category:Extension development]]
[[Category:Specifications]]

Release and support cycle

2013-01-20T20:55:35Z

Mvangeest: Fixed numbering inconsistencies - please be careful when editing

Joomla! is developed using a fixed release cycle. '''Every six months''', the Joomla! Project releases a new ''minor'' or ''major'' version of Joomla!. Joomla!'s version format is:
:{{dablink|<tt>[major].[minor].[maintenance]</tt>}}

Each version of Joomla! is supported by the Joomla! Project for a limited amount of time. There are two classifications for support: short term support (STS) and long term support (LTS). Every '''fourth''' release will be assigned long term support.

:*'''STS (short term support)''' releases are supported for '''seven months'''. Their support ends one month after the next release of Joomla is released. They are one click upgrades to the next STS or LTS version.

:*'''LTS (long term support)''' releases are supported for '''twenty-seven months'''.

Please note that both STS and LTS releases, once they have reached the ''GA (General Availability)'' status, are fully functional and ready to be used in production environment. The disadvantage of using STS releases is that you will need to update your installation of Joomla! every six months, while the advantage is that you will have access to new features and extensions earlier.

Generally, the first STS release after an LTS release indicates the beginning of a new ''major release cycle''. This STS release introduces fundamentally new features and changes that break compatibility with the previous LTS. Two more STS releases follow (usually compatible with the first STS release), and the release cycle is finished by the release of an LTS release which finalizes the work of the three STS releases. The four releases in one cycle will usually be numbered <tt>[major].0</tt>,<tt>[major].1</tt> and <tt>[major].2</tt> (STS) and <tt>[major].5</tt> (LTS). For example, the STS release 3.0 will include breaking changes from 2.5, and 3.5 will include matured versions of the changes in 3.0, 3.1 and 3.2.

Usually, there will be a migration path (an officially supported way of migrating to the next version) between two LTS releases (from <tt>[major].5</tt> to <tt>[next major].5</tt>) and between an LTS release and the STS releases in its major release cycle (from <tt>[major].2</tt> to <tt>[major].5</tt>, for example), but not necessarily to the '''following''' STS releases (from <tt>[major].5</tt> to <tt>[next major].0</tt>). In the case of 1.5 to 2.5 (LTS to LTS), for example, there is a migration path. Note that in the case of 2.5 to 3.0 (LTS to STS), there is also built-in migration path, since the changes aren't too incompatible.

For more information, see [http://developer.joomla.org/strategy.html the official Development Strategy].

The latest STS version documented on this Wiki is {{CurrentSTSVer}} (see [[:Category:Joomla! {{CurrentSTSVer|minor}}]]). The latest LTS version documented on this Wiki is {{CurrentLTSVer}} (see [[:Category:Joomla! {{CurrentLTSVer|minor}}]]).

[[Category:Development]]

J1.5:Upgrading 1.5 from an existing 1.5x version

2013-01-19T23:10:41Z

Mvangeest: /* Step 1: Download the upgrade file */ Updated download link and added link to package list

__NOTOC__
{{upgrade-intro}}

For some basic information on patching and migrating, see [[Upgrading and Migrating FAQs]] and [[Upgrade Instructions]].

You can also use a Joomla! extension to automate the process of loading version updates. See [http://extensions.joomla.org/extensions/core-enhancements/installers/9332 Update Manager for Joomla!] for more information.

Review the release notes for the new version.

When upgrading from a version that is not the most recent, review [http://www.joomla.org/announcements/release-news release notes for the prior releases.]

==Step 1: Download the upgrade file==

To download the most recent patch package and to obtain the MD5 hash:

* Visit the [http://joomlacode.org/gf/project/joomla/frs/?action=index release download index].
* Find the correct update file. The Joomla 1.5 downloads are located at the bottom of the page.
** If you are on the version ''prior to the current one'', use the file that updates from the prior version to the current version (for example, [http://joomlacode.org/gf/download/frsrelease/16891/73387/Joomla_1.5.25_to_1.5.26-Stable-Patch_Package.zip Joomla_1.5.25_to_1.5.26-Stable-Patch_Package]).
** If you are on an ''older'' version, use the 1.5.0 to current version file (for example, [http://joomlacode.org/gf/download/frsrelease/16891/73384/Joomla_1.5.0_to_1.5.26-Stable-Patch_Package.zip Joomla_1.5.0_to_1.5.26-Stable-Patch_Package]).
** Select the archive format (zip, tar.gz or tar.bz2) that is most convenient for you.
* Verify the download using the MD5 hash listed in the right column on the same line as the package you selected.

If you have questions about these instructions, read the ''Additional Information'' below this table.

'''Additional information:'''

{{Ambox|image=notice|text=[[Chunk:patch|What is a patch?]]|style=width:400px}}

{{Ambox|image=notice|text=[[Unpacking a package file|Which package format should I use?]]|style=width:400px}}

{{Ambox|image=notice|text=[[How to determine a package checksum|How do I use the MD5 hash to check the package?]]|style=width:400px}}

==Step 2: Backup your site==
Before you actually upgrade, you really should make a backup of your site. Backup your existing Joomla site files and store all the files and database in case something gets messed up, you wont have any problem reverting back.

All upgrades should be first tested on a copy of your site before being applied to a live site.

==Step 3: Install the upgrade file==
{{installing a package file}}

==Step 4: Check your live site to make sure it is working correctly==
Don't assume that the upgrade will work flawlessly just because the test upgrade worked. Check to make sure that nothing untoward has happened. It could be that differences between the live site and test site platforms will bring out a problem that you did not notice during testing. If you find a problem and it cannot be resolved quickly you might have to rollback the upgrade using the backup copy you created in step 2.

Hopefully all will be well and you can relax. If you have any questions before, during, or after the upgrade then please ask them on the [http://forum.joomla.org/index.php/board,430.0.html Joomla! 1.5 Migrating and Upgrading Forum].

Return to [[Upgrade Instructions]]

[[Category:Upgrading]]

J2.5:Supporting SEF URLs in your component

2012-11-25T18:17:47Z

Mvangeest: Added information and removed Incomplete template - this page is not complete, but contains enough information to be useful

{{:Search Engine Friendly URLs}}
In Joomla!, each [[component]] is responsible for handling its own SEF URLs. Therefore, as the [[Developers|developer]] of a component, you will have to create your own '''router''' to allow your component to use SEF URLs.

== The Concept ==

Assuming you are following standard development practices, your component is probably using "system URLs" that look a lot like <tt><nowiki>http://www.example.com/index.php?option=com_yourcomponent&view=article&id=1&catid=20&Itemid=50</nowiki></tt>, and your goal is to transform this into <tt><nowiki>http://www.example.com/example-menu-item/20/1</nowiki></tt>. As the developer, you have two tasks: signalling the system that certain pieces of text are URLs and need to be transformed, and explaining the system how to transform URLs.

=== Applying <code>JRoute::_</code> ===

It is difficult and inefficient for Joomla! to figure out which parts of your component's output are URLs. To support SEF URLs, you will need to change URL-generating code so that it applies <code>JRoute::_</code> before outputting the URL:

<source lang="php">
echo JRoute::_('index.php?view=article&id=1&catid=20');
</source>

Notice that it is possible to leave out the parameters <code>option</code> and <code>Itemid</code>. <code>option</code> defaults to the name of the component currently being executed, and <code>Itemid</code> defaults to the current menu item's ID.

In general, you should only apply this to URLs that users and/or search engines are able to see. For example, there is no need to transform URLs used in redirects that immediately result in other redirects.

If the user turns off SEF URLs in the site's settings, <code>JRoute::_</code> will produce working non-SEF URLs without any changes to the code.

=== Writing a router ===

You'll also need to write a router, which is a single file with two functions that convert system URLs to and from SEF URLs. This file needs to be placed at <tt>/components/com_yourcomponent/router.php</tt>.

The first function, <code>[componentname]BuildRoute(&$query)</code>, must transform an array of URL parameters into an array of segments that will form the SEF URL. Schematically, the transformation works as follows:

:<tt><nowiki>http://www.example.com/index.php?option=com_yourcomponent&view=article&id=1&catid=20&Itemid=50</nowiki></tt>

::<span style="font-size: xx-large">↓</span> <code>JRoute::_</code>, called by your component or any other extension

:<code>$query = array('view' => 'article', 'id' => 1, 'catid' => 20)</code>

::<span style="font-size: xx-large">↓</span> Your router's <code>com_yourcomponentBuildRoute</code>

:<code>$segments = array(20, 1);</code>

::<span style="font-size: xx-large">↓</span> Joomla's internal route building (for display)

:<tt><nowiki>http://www.example.com/example-menu-item/20/1</nowiki></tt>

The second function, <code>[componentname]ParseRoute($segments)</code>, must transform an array of segments back into an array of URL parameters. Schematically:

:<tt><nowiki>http://www.example.com/example-menu-item/20/1</nowiki></tt>

::<span style="font-size: xx-large">↓</span> Joomla's internal route parsing

:<code>$segments = array(20, 1);</code>

::<span style="font-size: xx-large">↓</span> Your router's <code>com_yourcomponentParseRoute</code>

:<code>$query = array('view' => 'article', 'id' => 1, 'catid' => 20)</code>

The two functions must cooperate in such a way that the original URL can be reconstructed. You can think of <code>BuildRoute</code> as a form of [[wikipedia:Encoding|encoding]] and <code>ParseRoute</code> as the corresponding decoding. When the original URL isn't properly reproduced, your component will stop working.

== Preparing Your Data for Routing ==

=== The Alias ===

The first step is the generation of the so called alias. The alias is used in the URL instead of the title (the alias is the text you want to have in the URL). The alias has to be URI safe, which means accented UTF8 characters are replaced by their ASCII7 equivalents, white spaces by hyphens, etc.

The alias can be defined by the user, but you should ensure that the above requirements for a URL safe alias are met. A good way to do so is to use the JTable::check() method during the save process. Have a look at this example code:

<source lang="php">

function check()
{
jimport( 'joomla.filter.output' );
if(empty($this->alias)) {
$this->alias = $this->title;
}
$this->alias = JFilterOutput::stringURLSafe($this->alias);

/* All your other checks */
return true;
}
</source>

If the alias field is empty the title will be used as alias. Then the alias will be made URLSafe using the <code>JFilterOutput::stringURLSafe()</code> method.

=== The Slug ===

Continuing with the same example, the "slug" - "1:welcome-to-joomla" has two parts. The first part is the article identifier (id) and the second is the alias. They are separated by a colon. These two elements were combined during the database query in the model:

<source lang="php">$query = 'SELECT a.*, '.
'CASE WHEN CHAR_LENGTH(a.alias) THEN CONCAT_WS(":", a.id, a.alias) ELSE a.id END as slug,'
/*...*/;</source>

After this step the slug is used instead of the id.

== Routing URLs ==

The <code>JRoute::_</code> method translates the internal Joomla! URL to a custom URL. <tt>JRoute</tt> has three parameters and its prototype is:

<source lang="php">JRoute::_( $url, $xhtml = true, $ssl=null );</source>

Where:

* <code>$url</code> is a string containing the absolute or relative internal Joomla! URL.
* <code>$xhtml</code> is a boolean value that specifies whether or not the output should be in XHTML. This parameter is optional and if omitted defaults to true.
* <code>$ssl</code> is an integer value that specifies whether the URI should be secure. It should be set to 1 to force the URI to be secure using the global secure site URI, 0 to leave it in the same state as when it was passed, and -1 to force the URI to be unsecure using the global unsecure site URI.

The most important parameter is <code>$url</code>. A call to this method might look like:

<source lang="php">JRoute::_( 'index.php?view=article&id='.$row->slug );</source>

<code>$row->slug</code> is the value that was generated in step 2 from a combination of id and title alias.

Another advantage of using JRoute is that the router now handles $option (the component name) and the $Itemid (the menu item ID). The component itself doesn’t have to know its name ($option) or the active menu item ($Itemid) like it did in previous version of Joomla!.

It is important that you think about the sequence of the URL parameter in this stage. This will be more clear when we have a deeper look at the router.php in the next section.

The building process of JRouter is divided into two steps:

* Create the application route. The application route is fully handled by JRouter and the component developer doesn’t have to do anything to make it work.
* Create the component route. To create the component route, JRouter looks for the <tt>router.php</tt> in the component directory which is responsible for building the route for the component.

== The Component Router ==

We will have two functions in the <tt>router.php</tt>. One is responsible for building the URL and the other is responsible for parsing it. In the next examples, a very basic and a more advanced one, we assume that we have three views that links can point to. The first is a categories overview (<code>view=categories</code>), the second is a single category (<code>view=category</code>) and the third is a single article (<code>view=article</code>).

The file <tt>router.php</tt> should be in the site area of your component. It is not used on admin/backend pages. Don't forget to add it to your XML [[Manifest files|manifest file]] in the site folder.

=== A Simple Example ===

This simple example will illustrate the basics of implementing a router for your component.

<source lang="php">
function [componentname]BuildRoute( &$query )
{
$segments = array();
if(isset($query['view']))
{
$segments[] = $query['view'];
unset( $query['view'] );
}
if(isset($query['id']))
{
$segments[] = $query['id'];
unset( $query['id'] );
};
return $segments;
}

</source>

<code>JRouter</code> passes a $query array to the <code>[''componentname'']BuildRoute</code> function. This function will add the relevant parts of the array to the $segments array in the right order and will return the properly ordered array. The content of the <code>$query</code> array needs to be unset, otherwise <code>JRouter</code> will add it to the URL in the form of a query string (i.e. any variables that are not handled by the router will be passed in the query string).

The prefix ''componentname'' is the name for your component, as found in the directory holding the component's files. For instance, a component "Magic" in directory <tt>/components/com_magic/...</tt> would use a prefix <code>magic</code> (all lower case).

The next function in the <tt>router.php</tt> parses the URL:

<source lang="php">
function [componentname]ParseRoute( $segments )
{
$vars = array();
switch($segments[0])
{
case 'categories':
$vars['view'] = 'categories';
break;
case 'category':
$vars['view'] = 'category';
$id = explode( ':', $segments[1] );
$vars['id'] = (int) $id[0];
break;
case 'article':
$vars['view'] = 'article';
$id = explode( ':', $segments[1] );
$vars['id'] = (int) $id[0];
break;
}
return $vars;
}
</source>

What happens here? In the function <code>[''componentname'']BuildRoute</code> we arranged the items in the <code>$query</code> array in a specific sequence. This means that in this example the view is first and the id is second in the array.

By reading <code>$segments[0]</code>, we access the name of the view. We set the right view and/or identifier depending on its value and we return the <code>$vars</code> array to <code>JRouter</code>. $vars should be an associative array similar to the array that was passed to the BuildRoute method.

The above example of the <tt>router.php</tt> is a very simple way to generate sef URL's but should show how this works quite clearly.

The generated URL in this example contains the name of the view and doesn't reflect the content hierarchy:

<tt><nowiki>http://www.example.com/[menualias]/[view]/[slug]</nowiki></tt>

=== A More Advanced Example ===

In the next example we will try to get rid of the need for the view and we will try to reflect the current hierarchy level in the URL.

The goal is URL's that look like:

* When viewing an article: <tt><nowiki>http://www.example.com/[menualias]/[category]/[article]</nowiki></tt>
* When viewing a category: <tt><nowiki>http://www.example.com/[menualias]/[category]</nowiki></tt>
* When viewing the categories overview: <tt><nowiki>http://www.example.com/[menualias]</nowiki></tt>

Let's assume we have done step 1 and 2 also for the category.

The link to the article would look like this:

<source lang="php">
JRoute::_( 'index.php?view=article&catid='.$row->catslug .'&id='.$row->slug );
</source>

And the Link to the category would look like this:

<source lang="php">
JRoute::_( 'index.php?view=category&id='.$row->catslug );
</source>

The corresponding <tt>router.php</tt>:

<source lang="php">

function [''Componentname'']BuildRoute(&$query)
{
$segments = array();
if(isset( $query['catid'] ))
{
$segments[] = $query['catid'];
unset( $query['catid'] );
};
if( isset($query['id']) )
{
$segments[] = $query['id'];
unset( $query['id'] );
};
unset( $query['view'] );
return $segments;
}
</source>

The difference now is that we don’t add the name of the view to the <code>$segments</code> array. We still unset the view key since otherwise, <code>JRouter</code> would add it to the URL as part of the query string. Another new thing here is the additional parameter catid that we push into the <code>$segments</code> array.

<source lang="php">
function [''Componentname'']ParseRoute($segments)
{
$vars = array();
$app =& JFactory::getApplication();
$menu =& $app->getMenu();
$item =& $menu->getActive();
// Count segments
$count = count( $segments );
//Handle View and Identifier
switch( $item->query['view'] )
{
case 'categories':
if($count == 1) {
$vars['view'] = 'category';
}
if($count == 2) {
$vars['view'] = 'article';
}
$id = explode( ':', $segments[$count-1] );
$vars['id'] = (int) $id[0];
break;
case 'category':
$id = explode( ':', $segments[$count-1] );
$vars['id'] = (int) $id[0];
$vars['view'] = 'article';
break;
}
return $vars;
}
</source>

You can see that this ParseRoute function has a lot of different code parts in comparison to the previous. The reason for this is simple. We don’t have the name of the view in the <code>$segments</code> array and we need to find another way to determine it.

We need to find out which level of hierarchy we are in by receiving the root element. We do this by looking to the view name of the active menu item:

<source lang="php">
$item->query['view']
</source>

Also we need to know the number of items in the <code>$segments</code> array:

<source lang="php">
$count = count( $segments );
</source>

With this information we can correctly set the view for all possible three cases:

* The menu item is a link to the categories view and the <code>$segments</code> array has two items (<code>$catid</code> and <code>$id</code>). In this case we know that we need to parse a link to an article.
* The menu item is a link to the categories view and the <code>$segments</code> array has one item (<code>$id</code>). In this case we know that we need to parse a link to a category.
* The menu item is a link to a category. In this case, we know that any item in the <code>$segments</code> array is the identifier for an article.

The result of all this code is clean and human-readable component URLs.

== Routers and Menu Items ==

A last important part of creating a router is considering what to do with menu items. As explained on [[Search Engine Friendly URLs]], the output of the component router is used ''after'' the first segment of a route, the first segment being the menu item's alias. This creates a difficult question: how is your router and/or other code to know which menu item to route through?

Suppose, for example, that your component is currently producing output for the page <tt>/dogs</tt>, which lists all dogs in the system. Of course, the items in the list need to be links to pages that display more details about one dog. What should the URL to the dog with ID 21 and name Fido become? Using a router that works according to the principles we've seen so far, the route that is produced is <tt>dogs/21-fido</tt>, or with some additional work <tt>/dogs/fido</tt>. But perhaps the user has created a menu item with the alias <tt>mydoggy</tt> which displays exactly that dog's details. Then it is probably the user's intention to route this URL through that menu item, and the item in the list should link to the page <tt>/mydoggy</tt>.

More generally, whenever you are building a route, you will need to find the menu item that is most suitable as a ''starting point'' for building your route. The term ''starting point'' is emphasized because the rest of the route depends on the configuration of the menu item. In our example above, <tt>/dogs/21-fido</tt> is an acceptable route, <tt>/mydoggy</tt> is arguably even better, but <tt>/mydoggy/21-fido</tt> is simply wrong, since <tt>/mydoggy</tt> is in itself a menu item that is set up to display <tt>fido</tt>'s information.

Several approaches are available to tackle this problem. Joomla!'s core components take a mixed approach, separating responsibilities in two units of code: the router itself and the so-called <code>[componentname]RouteHelper</code>. The <code>[componentname]RouteHelper</code> provides methods that find the most suitable menu item for a given piece of data to be displayed, while the router analyzes the menu item and puts any information that is not determined by the menu item's configuration into the route. This does mean that the ''calling code'' must explicitly call the helper's method before routing (<code>echo JRoute::_(DogsRouteHelper::getDogRoute(21));</code>).

== See Also ==

There is a useful thread on this subject here: [[jtopic:148632]] (note, may be out of date)

For details on the internals of routing, see [[Routing implementation details]].
<noinclude>[[Category:Tutorials]][[Category:Component Development]][[Category:Search Engine Friendly URLs]]</noinclude>

Search Engine Friendly URLs

2012-11-25T17:03:57Z

Mvangeest: Improved wording

<onlyinclude>
'''Search engine friendly (SEF)''', '''human-readable''' or [[wikipedia:Clean_URL|clean URLs]] are URLs that make sense to both humans and search engines because they explain the path to the particular page they point to. Since version 1.5, Joomla! is capable of creating and parsing URLs in any format, including SEF URLs. This does not depend on URL rewriting executed by the web server, so it works even if Joomla! runs a server other than Apache with the mod_rewrite module. The SEF URLs follow a certain fixed pattern, but the user can define a [[Alias|short descriptive text (alias)]] for each segment of the URL.

Internally, the local part of a SEF URL (the part after the domain name) is called a '''route'''. Creating and processing SEF URLs is therefore referred to as '''routing''', and the relevant code is called a '''router'''.
</onlyinclude>
A good example of routing is the URL to "Welcome to Joomla!" article in the sample data.

* Without SEF URLs turned on, the URL is <tt><nowiki>http://www.example.com/index.php?option=com_content&view=article&id=1:welcome-to-joomla&catid=1:latest-news&Itemid=50</nowiki></tt>
* With SEF URLs on and mod_rewrite off, it's <tt><nowiki>http://www.example.com/index.php/the-news/1-latest-news/1-welcome-to-joomla</nowiki></tt>
* With both SEF URLs and mod_rewrite on, it's <tt><nowiki>http://www.example.com/the-news/1-latest-news/1-welcome-to-joomla</nowiki></tt>

Search engine friendly URLs can be activated by turning on the '''Search Engine Friendly URLs''' option in the ''Global Configuration''. This option is on by default since Joomla! 1.6. See [[Enabling Search Engine Friendly (SEF) URLs]] for more information.

== Frequently Asked Questions ==

=== What do the numbers in the URL mean? ===
By comparing the old and the new URL we can see numbers in the old URL,

<tt><nowiki>http://www.example.com/index.php?option=com_content&view=article&id=1:welcome-to-joomla&catid=1:latest-news&Itemid=50</nowiki></tt>

but also in the new URL:

<tt><nowiki>http://www.example.com/the-news/1-latest-news/1-welcome-to-joomla</nowiki></tt>

These numbers are the parameters that are needed by Joomla! to get the internal URL and show the page you want to see. (In this case, the first numeral one is the ID of the category, the second numeral one is the ID of the article.)

=== There is no <tt>index.php</tt> in the URL anymore. Can I delete the file now? ===
No! The URL may doesn't contain the <tt>index.php</tt> anymore, but internally the mod_rewrite will only redirect to the original path without showing it to you.

=== What is the [[Alias]] value? And how does it get created? ===
Alias is listed beneath the Title field in Articles, Categories, Sections and Menu Items. Joomla! can automatically create the alias for you. An automatic alias begins with the title. All upper case letters are changed to lower case. Spaces and special characters not allowed in a URL; they are changed to dashes.

=== I want to specify my own value for Alias. ===
If you do not like the alias provided by Joomla!, you can enter a value of your choosing into that field. Many believe using good keywords in your URL helps search engine optimization. You can do so by including those keywords in your title, and allowing Joomla! to create the alias, or by creating the alias yourself.

=== How is Alias used in a URL? ===
For a menu item, Joomla! uses the alias as the URL plug. Assume that you use the first two SEF URL options and you create a menu item called Products. Your URL would be example.com/products.

Joomla! also uses the primary key values of data within the URL to help the router navigate to the correct page. Continuing with the previous example, if your products menu item was for an Article/Category Blog, the link for the Article Title and/or Read More link would have three parts:

* The menu item URL - example.com/products;

* Plus, the primary key for the Category and the Category alias - 32-fruit;

* Plus, the primary key for the Article and the Article alias - 1-apple;

The complete URL is: <tt><nowiki>http://example.com/products/32-fruit/1-apple</nowiki></tt>

=== How can I get rid of the numbers in the SEF URLs? ===
The numbers in the SEF URL are needed by Joomla!'s router to know how to direct site traffic. Once the router logic stabilizes, simple third party system plugins can be developed to augment the router capabilities by allowing more choice. At that time, numbers will likely be removed from the URL.

== Route Formats and the Routing Mechanism ==

''This section describes Joomla!'s core (built-in) routing mechanism. Routing extensions may change the way routes are created on your system.''

=== Route Formats ===

To describe the Joomla! routing mechanism in more detail, we first need to pin down what we refer to as a '''route'''. Suppose that Joomla! has been installed in <tt><nowiki>http://example.com/sites/first/</nowiki></tt>. The installation path is generally referred to as the '''base URL'''. A possible example URL is <tt><nowiki>http://example.com/sites/first/products/32-fruit/1-apple</nowiki></tt>. The first part of this URL is the aforementioned base URL, and neither Joomla! nor any component router can create URLs with a different first part. The second part, <tt>products/32-fruit/1-apple</tt>, is a '''route''', consisting of three '''segment'''s.

The first segment of a route is, for regular URLs, the alias of a menu item. The SEF URL is said to be '''routed through''' that menu item. The other segments are determined entirely by the router of the component that provides the type of the menu item. The ''Category - Blog'' menu item type, for example, is provided by the [[Content]] component, and therefore that component's router is responsible for building and parsing the remaining segments.

It is also possible (for extensions) to ask the system to create a route without supplying a menu item to route through. In that case, the system will usually decide to create a special route that has the word <tt>component</tt> as the first segment. These routes are created using a fixed format: the name of the component (without the leading <tt>com_</tt>) is selected as the second segment and any parameters as the other segments.

=== Limitations ===

It is important to note creating a menu item is the ''only'' way for a Joomla! user to define a route that leads to a specific component. It is, however, possible to create a route without showing it on the site (in a menu). An often-applied method is to create a menu item in a menu that isn't displayed anywhere. Such a menu is usually called a [[Menu|hidden menu]].

The previous paragraph implies that it is not possible to make one component responsible for handling all routes. For example, it is not possible to specify that the URL <tt><nowiki>http://example.com/thealias</nowiki></tt> should display the Content item with the alias <tt>thealias</tt>, where <tt>thealias</tt> could be any word. If this needs to be done for a small number of articles, menu items can be created manually for these. Else a routing extension is necessary.

This routing mechanism is therefore not as flexible as users sometimes require. On the other hand, it has one large advantage: it reduces the chance of ambiguous routes (routes that could lead to two different pages). Since the first segment of a route is always a menu item alias, the system immediately knows which component's router must be used to parse it.

== Implementation Details ==
=== Handling Routes ===

''This section describes the routing implementation. If you are a component developer, see [[Supporting SEF URLs in your component]].''

Joomla routes are created and resolved by [[JRouter|the JRouter class]]. This class looks in the component root of the currently active component (specified in the <code>option</code> parameter in the query string) and includes the <tt>router.php</tt> file in that component's root directory. It then calls one of two functions: one for creating the SEF URL and one for interpreting the SEF URL.

The JRouter class is overridden by the Joomla CMS in <tt>/includes/router.php</tt>. In this file the build and parse functions are overridden to properly build and parse the URLs for the Joomla CMS.

The <tt>router.php</tt> file in each component (for example, <tt>/components/com_content/router.php</tt>) should contain the following two functions:
* ContentBuildRoute - this builds the SEF URL
** Parameters
*** $query - this is a named array containing the querystring variables
** Returns: an array of segments where each segment is separated by a '/' when later combined to create the actual URL (the items in the array should not contain '/' characters)
* ContentParseRoute - this interprets an SEF URL
** Parameters
*** $segments - this is an array that contains the segments of the URL requested.
** Returns: a name => value array of the querystring variables that the link maps to

=== The SEF Plugin ===
The Joomla ''System - SEF'' plugin inherits <code>JPlugin</code> and implements the <code>onAfterRender()</code> function. In this function the body of the response that will be sent to the browser is retrieved using <code>JResponse::getBody()</code>. The body of the response is then searched for links containing <tt>/index.php...</tt> and replaces them with a correct SEF URL by calling <code>JRoute::_(''url'')</code>.

JRoute builds SEF URLs by instantiating a <code>JRouter</code> object and requesting that it build the correct link from the passed in URL.

=== Handling SEF URLs ===
By default the SEF URLs are handled by the <code>JRouterSite</code> object (from <tt>/includes/router.php</tt>) and is called by a call to <code>JApplication::route()</code> in index.php. This call is made on the <code>$app</code> variable which is actually an instance of <code>JSite</code> (from <tt>/includes/application.php</tt>).

<code>JApplication::route()</code> has a non-destructive result on the <code>$_GET</code> array. That is, <code>JApplication::route()</code> sets variables in <code>$_GET</code> by calling <code>JRequest::set()</code> with the overwrite flag set to false. Thus if a variable name is returned from <code>JRouter::route()</code> that is already in <code>$_GET</code>, it will not put that value into <code>$_GET</code>. This allows for custom routing.

=== Custom Routing ===
Joomla allows you to create your own routing mechanism. In order to create this mechanism you must have a plugin that overrides the <code>JPlugin::onAfterInitialise()</code> function. This function then parses the URL and creates the needed variables in <code>$_GET</code> before the standard Joomla routing is done.

''See [[Creating a System Plugin to augment JRouter]] for an example.''

[[Category:Search Engine Friendly URLs| ]]

Search Engine Friendly URLs

2012-11-25T16:11:58Z

Mvangeest: Adjusted layout

<onlyinclude>
'''Search engine friendly (SEF)''', '''human-readable''' or [[wikipedia:Clean_URL|clean URLs]] are URLs that make sense to both humans and search engines because they explain the path to the particular page they point to. Since version 1.5, Joomla! is capable of creating and parsing URLs in any format, including SEF URLs. This does not depend on URL rewriting executed by the web server, so it works even if Joomla! runs a server other than Apache with the mod_rewrite module. The SEF URLs follow a certain fixed pattern, but the user can define a [[Alias|short descriptive text (alias)]] for each segment of the URL.

Internally, the local part of a SEF URL (the part after the domain name) is called a '''route'''. Creating and processing SEF URLs is therefore referred to as '''routing''', and the relevant code is called a '''router'''.
</onlyinclude>
A good example of routing is the URL to "Welcome to Joomla!" article in the sample data.

* Without SEF URLs turned on, the URL is <tt><nowiki>http://www.example.com/index.php?option=com_content&view=article&id=1:welcome-to-joomla&catid=1:latest-news&Itemid=50</nowiki></tt>
* With SEF URLs on and mod_rewrite off, it's <tt><nowiki>http://www.example.com/index.php/the-news/1-latest-news/1-welcome-to-joomla</nowiki></tt>
* With both SEF URLs and mod_rewrite on, it's <tt><nowiki>http://www.example.com/the-news/1-latest-news/1-welcome-to-joomla</nowiki></tt>

Search engine friendly URLs can be activated by turning on the '''Search Engine Friendly URLs''' option in the ''Global Configuration''. This option is on by default since Joomla! 1.6. See [[Enabling Search Engine Friendly (SEF) URLs]] for more information.

== Frequently Asked Questions ==

=== What do the numbers in the URL mean? ===
By comparing the old and the new URL we can see numbers in the old URL,

<tt><nowiki>http://www.example.com/index.php?option=com_content&view=article&id=1:welcome-to-joomla&catid=1:latest-news&Itemid=50</nowiki></tt>

but also in the new URL:

<tt><nowiki>http://www.example.com/the-news/1-latest-news/1-welcome-to-joomla</nowiki></tt>

These numbers are the parameters that are needed by Joomla! to get the internal URL and show the page you want to see. (In this case, the first numeral one is the ID of the category, the second numeral one is the ID of the article.)

=== There is no <tt>index.php</tt> in the URL anymore. Can I delete the file now? ===
No! The URL may doesn't contain the <tt>index.php</tt> anymore, but internally the mod_rewrite will only redirect to the original path without showing it to you.

=== What is the [[Alias]] value? And how does it get created? ===
Alias is listed beneath the Title field in Articles, Categories, Sections and Menu Items. Joomla! can automatically create the alias for you. An automatic alias begins with the title. All upper case letters are changed to lower case. Spaces and special characters not allowed in a URL; they are changed to dashes.

=== I want to specify my own value for Alias. ===
If you do not like the alias provided by Joomla!, you can enter a value of your choosing into that field. Many believe using good keywords in your URL helps search engine optimization. You can do so by including those keywords in your title, and allowing Joomla! to create the alias, or by creating the alias yourself.

=== How is Alias used in a URL? ===
For a menu item, Joomla! uses the alias as the URL plug. Assume that you use the first two SEF URL options and you create a menu item called Products. Your URL would be example.com/products.

Joomla! also uses the primary key values of data within the URL to help the router navigate to the correct page. Continuing with the previous example, if your products menu item was for an Article/Category Blog, the link for the Article Title and/or Read More link would have three parts:

* The menu item URL - example.com/products;

* Plus, the primary key for the Category and the Category alias - 32-fruit;

* Plus, the primary key for the Article and the Article alias - 1-apple;

The complete URL is: <tt><nowiki>http://example.com/products/32-fruit/1-apple</nowiki></tt>

=== How can I get rid of the numbers in the SEF URLs? ===
The numbers in the SEF URL are needed by Joomla!'s router to know how to direct site traffic. Once the router logic stabilizes, simple third party system plugins can be developed to augment the router capabilities by allowing more choice. At that time, numbers will likely be removed from the URL.

== Route Formats and the Routing Mechanism ==

''This section describes Joomla!'s core (built-in) routing mechanism. Routing extensions may change the way routes are created on your system.''

=== Route Formats ===

To describe the Joomla! routing mechanism in more detail, we first need to pin down what we refer to as a '''route'''. In our example URL, <tt><nowiki>http://example.com/sites/first/products/32-fruit/1-apple</nowiki></tt>, <tt><nowiki>http://example.com/sites/first/</nowiki></tt> is the part of the URL that is the same for all URLs managed by a Joomla! installation. It is generally referred to as the '''base URL'''. Neither Joomla! nor any component router can create URLs with a different first part. The second part, <tt>products/32-fruit/1-apple</tt>, is a '''route''', consisting of three '''segment'''s.

The first segment of a route is, for regular URLs, the alias of a menu item. The SEF URL is said to be '''routed through''' that menu item. The other segments are determined entirely by the router of the component that provides the type of the menu item. The ''Category - Blog'' menu item type, for example, is provided by the [[Content]] component, and therefore that component's router is responsible for building and parsing the remaining segments.

It is also possible (for extensions) to ask the system to create a route without supplying a menu item to route through. In that case, the system will usually decide to create a special route that has the word <tt>component</tt> as the first segment. These routes are created using a fixed format: the name of the component (without the leading <tt>com_</tt>) is selected as the second segment and any parameters as the other segments.

=== Limitations ===

It is important to note creating a menu item is the ''only'' way for a Joomla! user to define a route that leads to a specific component. It is, however, possible to create a route without showing it on the site (in a menu). An often-applied method is to create a menu item in a menu that isn't displayed anywhere. Such a menu is usually called a [[Menu|hidden menu]].

The previous paragraph implies that it is not possible to make one component responsible for handling all routes. For example, it is not possible to specify that the URL <tt><nowiki>http://example.com/thealias</nowiki></tt> should display the Content item with the alias <tt>thealias</tt>, where <tt>thealias</tt> could be any word. If this needs to be done for a small number of articles, menu items can be created manually for these. Else a routing extension is necessary.

This routing mechanism is therefore not as flexible as users sometimes require. On the other hand, it has one large advantage: it reduces the chance of ambiguous routes (routes that could lead to two different pages). Since the first segment of a route is always a menu item alias, the system immediately knows which component's router must be used to parse it.

== Implementation Details ==
=== Handling Routes ===

''This section describes the routing implementation. If you are a component developer, see [[Supporting SEF URLs in your component]].''

Joomla routes are created and resolved by [[JRouter|the JRouter class]]. This class looks in the component root of the currently active component (specified in the <code>option</code> parameter in the query string) and includes the <tt>router.php</tt> file in that component's root directory. It then calls one of two functions: one for creating the SEF URL and one for interpreting the SEF URL.

The JRouter class is overridden by the Joomla CMS in <tt>/includes/router.php</tt>. In this file the build and parse functions are overridden to properly build and parse the URLs for the Joomla CMS.

The <tt>router.php</tt> file in each component (for example, <tt>/components/com_content/router.php</tt>) should contain the following two functions:
* ContentBuildRoute - this builds the SEF URL
** Parameters
*** $query - this is a named array containing the querystring variables
** Returns: an array of segments where each segment is separated by a '/' when later combined to create the actual URL (the items in the array should not contain '/' characters)
* ContentParseRoute - this interprets an SEF URL
** Parameters
*** $segments - this is an array that contains the segments of the URL requested.
** Returns: a name => value array of the querystring variables that the link maps to

=== The SEF Plugin ===
The Joomla ''System - SEF'' plugin inherits <code>JPlugin</code> and implements the <code>onAfterRender()</code> function. In this function the body of the response that will be sent to the browser is retrieved using <code>JResponse::getBody()</code>. The body of the response is then searched for links containing <tt>/index.php...</tt> and replaces them with a correct SEF URL by calling <code>JRoute::_(''url'')</code>.

JRoute builds SEF URLs by instantiating a <code>JRouter</code> object and requesting that it build the correct link from the passed in URL.

=== Handling SEF URLs ===
By default the SEF URLs are handled by the <code>JRouterSite</code> object (from <tt>/includes/router.php</tt>) and is called by a call to <code>JApplication::route()</code> in index.php. This call is made on the <code>$app</code> variable which is actually an instance of <code>JSite</code> (from <tt>/includes/application.php</tt>).

<code>JApplication::route()</code> has a non-destructive result on the <code>$_GET</code> array. That is, <code>JApplication::route()</code> sets variables in <code>$_GET</code> by calling <code>JRequest::set()</code> with the overwrite flag set to false. Thus if a variable name is returned from <code>JRouter::route()</code> that is already in <code>$_GET</code>, it will not put that value into <code>$_GET</code>. This allows for custom routing.

=== Custom Routing ===
Joomla allows you to create your own routing mechanism. In order to create this mechanism you must have a plugin that overrides the <code>JPlugin::onAfterInitialise()</code> function. This function then parses the URL and creates the needed variables in <code>$_GET</code> before the standard Joomla routing is done.

''See [[Creating a System Plugin to augment JRouter]] for an example.''

[[Category:Search Engine Friendly URLs| ]]

Search Engine Friendly URLs

2012-11-25T15:43:25Z

Mvangeest: Added information - second attempt

<onlyinclude>
'''Search engine friendly (SEF)''', '''human-readable''' or [[wikipedia:Clean_URL|clean URLs]] are URLs that make sense to both humans and search engines because they explain the path to the particular page they point to. Since version 1.5, Joomla! is capable of creating and parsing URLs in any format, including SEF URLs. This does not depend on URL rewriting executed by the web server, so it works even if Joomla! runs a server other than Apache with the mod_rewrite module. The SEF URLs follow a certain fixed pattern, but the user can define a [[Alias|short descriptive text (alias)]] for each segment of the URL.

Internally, the local part of a SEF URL (the part after the domain name) is called a '''route'''. Creating and processing SEF URLs is therefore referred to as '''routing''', and the relevant code is called a '''router'''.
</onlyinclude>
A good example of routing is the URL to "Welcome to Joomla!" article in the sample data.

* Without SEF URLs turned on, the URL is <tt><nowiki>http://www.example.com/index.php?option=com_content&view=article&id=1:welcome-to-joomla&catid=1:latest-news&Itemid=50</nowiki></tt>
* With SEF URLs on and mod_rewrite off, it's <tt><nowiki>http://www.example.com/index.php/the-news/1-latest-news/1-welcome-to-joomla</nowiki></tt>
* With both SEF URLs and mod_rewrite on, it's <tt><nowiki>http://www.example.com/the-news/1-latest-news/1-welcome-to-joomla</nowiki></tt>

Search engine friendly URLs can be activated by turning on the '''Search Engine Friendly URLs''' option in the ''Global Configuration''. This option is on by default since Joomla! 1.6. See [[Enabling Search Engine Friendly (SEF) URLs]] for more information.

== Frequently Asked Questions ==

=== What do the numbers in the URL mean? ===
By comparing the old and the new URL we can see numbers in the old URL,

<tt><nowiki>http://www.example.com/index.php?option=com_content&view=article&id=1:welcome-to-joomla&catid=1:latest-news&Itemid=50</nowiki></tt>

but also in the new URL:

<tt><nowiki>http://www.example.com/the-news/1-latest-news/1-welcome-to-joomla</nowiki></tt>

These numbers are the parameters that are needed by Joomla! to get the internal URL and show the page you want to see. (In this case, the first numeral one is the ID of the category, the second numeral one is the ID of the article.)

=== There is no <tt>index.php</tt> in the URL anymore. Can I delete the file now? ===
No! The URL may doesn't contain the <tt>index.php</tt> anymore, but internally the mod_rewrite will only redirect to the original path without showing it to you.

=== What is the [[Alias]] value? And how does it get created? ===
Alias is listed beneath the Title field in Articles, Categories, Sections and Menu Items. Joomla! can automatically create the alias for you. An automatic alias begins with the title. All upper case letters are changed to lower case. Spaces and special characters not allowed in a URL; they are changed to dashes.

=== I want to specify my own value for Alias. ===
If you do not like the alias provided by Joomla!, you can enter a value of your choosing into that field. Many believe using good keywords in your URL helps search engine optimization. You can do so by including those keywords in your title, and allowing Joomla! to create the alias, or by creating the alias yourself.

=== How is Alias used in a URL? ===
For a menu item, Joomla! uses the alias as the URL plug. Assume that you use the first two SEF URL options and you create a menu item called Products. Your URL would be example.com/products.

Joomla! also uses the primary key values of data within the URL to help the router navigate to the correct page. Continuing with the previous example, if your products menu item was for an Article/Category Blog, the link for the Article Title and/or Read More link would have three parts:

* The menu item URL - example.com/products;

* Plus, the primary key for the Category and the Category alias - 32-fruit;

* Plus, the primary key for the Article and the Article alias - 1-apple;

The complete URL is: <tt><nowiki>http://example.com/products/32-fruit/1-apple</nowiki></tt>

=== How can I get rid of the numbers in the SEF URLs? ===
The numbers in the SEF URL are needed by Joomla!'s router to know how to direct site traffic. Once the router logic stabilizes, simple third party system plugins can be developed to augment the router capabilities by allowing more choice. At that time, numbers will likely be removed from the URL.

== Route Formats and the Routing Mechanism ==

''This section describes Joomla!'s core (built-in) routing mechanism. Routing extensions may change the way routes are created on your system.''

To describe the Joomla! routing mechanism in more detail, we first need to pin down what we refer to as a '''route'''. In our example URL, <tt><nowiki>http://example.com/sites/first/products/32-fruit/1-apple</nowiki></tt>, <tt><nowiki>http://example.com/sites/first/</nowiki></tt> is the part of the URL that is the same for all URLs managed by a Joomla! installation. It is generally referred to as the '''base URL'''. Neither Joomla! nor any component router can create URLs with a different first part. The second part, <tt>products/32-fruit/1-apple</tt>, is a '''route''', consisting of three '''segment'''s.

The first segment of a route is, for regular URLs, the alias of a menu item. The SEF URL is said to be '''routed through''' that menu item. The other segments are determined entirely by the router of the component that provides the type of the menu item. The ''Category - Blog'' menu item type, for example, is provided by the [[Content]] component, and therefore that component's router is responsible for building and parsing the remaining segments.

It is also possible (for extensions) to ask the system to create a route without supplying a menu item to route through. In that case, the system will usually decide to create a special route that has the word <tt>component</tt> as the first segment. These routes are created using a fixed format: the name of the component (without the leading <tt>com_</tt>) is selected as the second segment and any parameters as the other segments.

It is important to note creating a menu item is the ''only'' way for a Joomla! user to define a route that leads to a specific component. It is, however, possible to create a route without showing it on the site (in a menu). An often-applied method is to create a menu item in a menu that isn't displayed anywhere. Such a menu is usually called a [[Menu|hidden menu]].

The previous paragraph implies that it is not possible to make one component responsible for handling all routes. For example, it is not possible to specify that the URL <tt><nowiki>http://example.com/thealias</nowiki></tt> should display the Content item with the alias <tt>thealias</tt>, where <tt>thealias</tt> could be any word. If this needs to be done for a small number of articles, menu items can be created manually for these. Else a routing extension is necessary.

This routing mechanism is therefore not as flexible as users sometimes require. On the other hand, it has one large advantage: it reduces the chance of ambiguous routes (routes that could lead to two different pages). Since the first segment of a route is always a menu item alias, the system immediately knows which component's router must be used to parse it.

== Implementation Details ==
=== Joomla Routes ===

''This section describes the routing implementation. If you are a component developer, see [[Supporting SEF URLs in your component]].''

Joomla routes are created and resolved by [[JRouter|the JRouter class]]. This class looks in the component root of the currently active component (specified in the <code>option</code> parameter in the query string) and includes the <tt>router.php</tt> file in that component's root directory. It then calls one of two functions: one for creating the SEF URL and one for interpreting the SEF URL.

The JRouter class is overridden by the Joomla CMS in <tt>/includes/router.php</tt>. In this file the build and parse functions are overridden to properly build and parse the URLs for the Joomla CMS.

The <tt>router.php</tt> file in each component (for example, <tt>/components/com_content/router.php</tt>) should contain the following two functions:
* ContentBuildRoute - this builds the SEF URL
** Parameters
*** $query - this is a named array containing the querystring variables
** Returns: an array of segments where each segment is separated by a '/' when later combined to create the actual URL (the items in the array should not contain '/' characters)
* ContentParseRoute - this interprets an SEF URL
** Parameters
*** $segments - this is an array that contains the segments of the URL requested.
** Returns: a name => value array of the querystring variables that the link maps to

=== The SEF Plugin ===
The Joomla ''System - SEF'' plugin inherits <code>JPlugin</code> and implements the <code>onAfterRender()</code> function. In this function the body of the response that will be sent to the browser is retrieved using <code>JResponse::getBody()</code>. The body of the response is then searched for links containing <tt>/index.php...</tt> and replaces them with a correct SEF URL by calling <code>JRoute::_(''url'')</code>.

JRoute builds SEF URLs by instantiating a <code>JRouter</code> object and requesting that it build the correct link from the passed in URL.

=== Handling SEF URLs ===
By default the SEF URLs are handled by the <code>JRouterSite</code> object (from <tt>/includes/router.php</tt>) and is called by a call to <code>JApplication::route()</code> in index.php. This call is made on the <code>$app</code> variable which is actually an instance of <code>JSite</code> (from <tt>/includes/application.php</tt>).

<code>JApplication::route()</code> has a non-destructive result on the <code>$_GET</code> array. That is, <code>JApplication::route()</code> sets variables in <code>$_GET</code> by calling <code>JRequest::set()</code> with the overwrite flag set to false. Thus if a variable name is returned from <code>JRouter::route()</code> that is already in <code>$_GET</code>, it will not put that value into <code>$_GET</code>. This allows for custom routing.

=== Custom Routing ===
Joomla allows you to create your own routing mechanism. In order to create this mechanism you must have a plugin that overrides the <code>JPlugin::onAfterInitialise()</code> function. This function then parses the URL and creates the needed variables in <code>$_GET</code> before the standard Joomla routing is done.

''See [[Creating a System Plugin to augment JRouter]] for an example.''

[[Category:Search Engine Friendly URLs| ]]

J2.5:Supporting SEF URLs in your component

2012-11-25T00:55:35Z

Mvangeest: Split off parts to Routing implementation details

{{incomplete}}
{{:Search Engine Friendly URLs}}
In Joomla!, each [[component]] is responsible for handling its own SEF URLs. Therefore, as the [[Developers|developer]] of a component, you will have to create your own '''router''' to allow your component to use SEF URLs.

== The Concept ==

Assuming you are following standard development practices, your component is probably using "system URLs" that look a lot like <tt><nowiki>http://www.example.com/index.php?option=com_yourcomponent&view=article&id=1&catid=20&Itemid=50</nowiki></tt>, and your goal is to transform this into <tt><nowiki>http://www.example.com/example-menu-item/20/1</nowiki></tt>. As the developer, you have two tasks: signalling the system that certain pieces of text are URLs and need to be transformed, and explaining the system how to transform URLs.

=== Applying <code>JRoute::_</code> ===

It is difficult and inefficient for Joomla! to figure out which parts of your component's output are URLs. To support SEF URLs, you will need to change URL-generating code so that it applies <code>JRoute::_</code> before outputting the URL:

<source lang="php">
echo JRoute::_('index.php?view=article&id=1&catid=20');
</source>

Notice that it is possible to leave out the parameters <code>option</code> and <code>Itemid</code>. <code>option</code> defaults to the name of the component currently being executed, and <code>Itemid</code> defaults to the current menu item's ID.

In general, you should only apply this to URLs that users and/or search engines are able to see. For example, there is no need to transform URLs used in redirects that immediately result in other redirects.

If the user turns off SEF URLs in the site's settings, <code>JRoute::_</code> will produce working non-SEF URLs without any changes to the code.

=== Writing a router ===

You'll also need to write a router, which is a single file with two functions that convert system URLs to and from SEF URLs. This file needs to be placed at <tt>/components/com_yourcomponent/router.php</tt>.

The first function, <code>[componentname]BuildRoute(&$query)</code>, must transform an array of URL parameters into an array of segments that will form the SEF URL. Schematically, the transformation works as follows:

:<tt><nowiki>http://www.example.com/index.php?option=com_yourcomponent&view=article&id=1&catid=20&Itemid=50</nowiki></tt>

::<span style="font-size: xx-large">↓</span> <code>JRoute::_</code>, called by your component or any other extension

:<code>$query = array('view' => 'article', 'id' => 1, 'catid' => 20)</code>

::<span style="font-size: xx-large">↓</span> Your router's <code>com_yourcomponentBuildRoute</code>

:<code>$segments = array(20, 1);</code>

::<span style="font-size: xx-large">↓</span> Joomla's internal routing (for display)

:<tt><nowiki>http://www.example.com/example-menu-item/20/1</nowiki></tt>

The second function, <code>[componentname]ParseRoute($segments)</code>, must transform an array of segments back into an array of URL parameters. Schematically:

:<tt><nowiki>http://www.example.com/example-menu-item/20/1</nowiki></tt>

::<span style="font-size: xx-large">↓</span> Joomla's internal routing

:<code>$segments = array(20, 1);</code>

::<span style="font-size: xx-large">↓</span> Your router's <code>com_yourcomponentParseRoute</code>

:<code>$query = array('view' => 'article', 'id' => 1, 'catid' => 20)</code>

The two functions must cooperate in such a way that the original URL can be reconstructed. You can think of <code>BuildRoute</code> as a form of [[wikipedia:Encoding|encoding]] and <code>ParseRoute</code> as the corresponding decoding. When the original URL isn't properly reproduced, your component will stop working.

== Preparing Your Data for Routing ==

=== The Alias ===

The first step is the generation of the so called alias. The alias is used in the URL instead of the title (the alias is the text you want to have in the URL). The alias has to be URI safe, which means accented UTF8 characters are replaced by their ASCII7 equivalents, white spaces by hyphens, etc.

The alias can be defined by the user, but you should ensure that the above requirements for a URL safe alias are met. A good way to do so is to use the JTable::check() method during the save process. Have a look at this example code:

<source lang="php">

function check()
{
jimport( 'joomla.filter.output' );
if(empty($this->alias)) {
$this->alias = $this->title;
}
$this->alias = JFilterOutput::stringURLSafe($this->alias);

/* All your other checks */
return true;
}
</source>

If the alias field is empty the title will be used as alias. Then the alias will be made URLSafe using the <code>JFilterOutput::stringURLSafe()</code> method.

=== The Slug ===

Continuing with the same example, the "slug" - "1:welcome-to-joomla" has two parts. The first part is the article identifier (id) and the second is the alias. They are separated by a colon. These two elements were combined during the database query in the model:

<source lang="php">$query = 'SELECT a.*, '.
'CASE WHEN CHAR_LENGTH(a.alias) THEN CONCAT_WS(":", a.id, a.alias) ELSE a.id END as slug,'
/*...*/;</source>

After this step the slug is used instead of the id.

== Routing URLs ==

The <code>JRoute::_</code> method translates the internal Joomla! URL to a custom URL. <tt>JRoute</tt> has three parameters and its prototype is:

<source lang="php">JRoute::_( $url, $xhtml = true, $ssl=null );</source>

Where:

* <code>$url</code> is a string containing the absolute or relative internal Joomla! URL.
* <code>$xhtml</code> is a boolean value that specifies whether or not the output should be in XHTML. This parameter is optional and if omitted defaults to true.
* <code>$ssl</code> is an integer value that specifies whether the URI should be secure. It should be set to 1 to force the URI to be secure using the global secure site URI, 0 to leave it in the same state as when it was passed, and -1 to force the URI to be unsecure using the global unsecure site URI.

The most important parameter is <code>$url</code>. A call to this method might look like:

<source lang="php">JRoute::_( 'index.php?view=article&id='.$row->slug );</source>

<code>$row->slug</code> is the value that was generated in step 2 from a combination of id and title alias.

Another advantage of using JRoute is that the router now handles $option (the component name) and the $Itemid (the menu item ID). The component itself doesn’t have to know its name ($option) or the active menu item ($Itemid) like it did in previous version of Joomla!.

It is important that you think about the sequence of the URL parameter in this stage. This will be more clear when we have a deeper look at the router.php in the next section.

The building process of JRouter is divided into two steps:

* Create the application route. The application route is fully handled by JRouter and the component developer doesn’t have to do anything to make it work.
* Create the component route. To create the component route, JRouter looks for the <tt>router.php</tt> in the component directory which is responsible for building the route for the component.

== The Component Router ==

We will have two functions in the <tt>router.php</tt>. One is responsible for building the URL and the other is responsible for parsing it. In the next examples, a very basic and a more advanced one, we assume that we have three views that links can point to. The first is a categories overview (<code>view=categories</code>), the second is a single category (<code>view=category</code>) and the third is a single article (<code>view=article</code>).

The file <tt>router.php</tt> should be in the site area of your component. It is not used on admin/backend pages. Don't forget to add it to your XML [[Manifest files|manifest file]] in the site folder.

=== A Simple Example ===

This simple example will illustrate the basics of implementing a router for your component.

<source lang="php">
function [componentname]BuildRoute( &$query )
{
$segments = array();
if(isset($query['view']))
{
$segments[] = $query['view'];
unset( $query['view'] );
}
if(isset($query['id']))
{
$segments[] = $query['id'];
unset( $query['id'] );
};
return $segments;
}

</source>

<code>JRouter</code> passes a $query array to the <code>[''componentname'']BuildRoute</code> function. This function will add the relevant parts of the array to the $segments array in the right order and will return the properly ordered array. The content of the <code>$query</code> array needs to be unset, otherwise <code>JRouter</code> will add it to the URL in the form of a query string (i.e. any variables that are not handled by the router will be passed in the query string).

The prefix ''componentname'' is the name for your component, as found in the directory holding the component's files. For instance, a component "Magic" in directory <tt>/components/com_magic/...</tt> would use a prefix <code>magic</code> (all lower case).

The next function in the <tt>router.php</tt> parses the URL:

<source lang="php">
function [componentname]ParseRoute( $segments )
{
$vars = array();
switch($segments[0])
{
case 'categories':
$vars['view'] = 'categories';
break;
case 'category':
$vars['view'] = 'category';
$id = explode( ':', $segments[1] );
$vars['id'] = (int) $id[0];
break;
case 'article':
$vars['view'] = 'article';
$id = explode( ':', $segments[1] );
$vars['id'] = (int) $id[0];
break;
}
return $vars;
}
</source>

What happens here? In the function <code>[''componentname'']BuildRoute</code> we arranged the items in the <code>$query</code> array in a specific sequence. This means that in this example the view is first and the id is second in the array.

By reading <code>$segments[0]</code>, we access the name of the view. We set the right view and/or identifier depending on its value and we return the <code>$vars</code> array to <code>JRouter</code>. $vars should be an associative array similar to the array that was passed to the BuildRoute method.

The above example of the <tt>router.php</tt> is a very simple way to generate sef URL's but should show how this works quite clearly.

The generated URL in this example contains the name of the view and doesn't reflect the content hierarchy:

<tt><nowiki>http://www.example.com/[menualias]/[view]/[slug]</nowiki></tt>

=== A More Advanced Example ===

In the next example we will try to get rid of the need for the view and we will try to reflect the current hierarchy level in the URL.

The goal is URL's that look like:

* When viewing an article: <tt><nowiki>http://www.example.com/[menualias]/[category]/[article]</nowiki></tt>
* When viewing a category: <tt><nowiki>http://www.example.com/[menualias]/[category]</nowiki></tt>
* When viewing the categories overview: <tt><nowiki>http://www.example.com/[menualias]</nowiki></tt>

Let's assume we have done step 1 and 2 also for the category.

The link to the article would look like this:

<source lang="php">
JRoute::_( 'index.php?view=article&catid='.$row->catslug .'&id='.$row->slug );
</source>

And the Link to the category would look like this:

<source lang="php">
JRoute::_( 'index.php?view=category&id='.$row->catslug );
</source>

The corresponding <tt>router.php</tt>:

<source lang="php">

function [''Componentname'']BuildRoute(&$query)
{
$segments = array();
if(isset( $query['catid'] ))
{
$segments[] = $query['catid'];
unset( $query['catid'] );
};
if( isset($query['id']) )
{
$segments[] = $query['id'];
unset( $query['id'] );
};
unset( $query['view'] );
return $segments;
}
</source>

The difference now is that we don’t add the name of the view to the <code>$segments</code> array. We still unset the view key since otherwise, <code>JRouter</code> would add it to the URL as part of the query string. Another new thing here is the additional parameter catid that we push into the <code>$segments</code> array.

<source lang="php">
function [''Componentname'']ParseRoute($segments)
{
$vars = array();
$app =& JFactory::getApplication();
$menu =& $app->getMenu();
$item =& $menu->getActive();
// Count segments
$count = count( $segments );
//Handle View and Identifier
switch( $item->query['view'] )
{
case 'categories':
if($count == 1) {
$vars['view'] = 'category';
}
if($count == 2) {
$vars['view'] = 'article';
}
$id = explode( ':', $segments[$count-1] );
$vars['id'] = (int) $id[0];
break;
case 'category':
$id = explode( ':', $segments[$count-1] );
$vars['id'] = (int) $id[0];
$vars['view'] = 'article';
break;
}
return $vars;
}
</source>

You can see that this ParseRoute function has a lot of different code parts in comparison to the previous. The reason for this is simple. We don’t have the name of the view in the <code>$segments</code> array and we need to find another way to determine it.

We need to find out which level of hierarchy we are in by receiving the root element. We do this by looking to the view name of the active menu item:

<source lang="php">
$item->query['view']
</source>

Also we need to know the number of items in the <code>$segments</code> array:

<source lang="php">
$count = count( $segments );
</source>

With this information we can correctly set the view for all possible three cases:

* The menu item is a link to the categories view and the <code>$segments</code> array has two items (<code>$catid</code> and <code>$id</code>). In this case we know that we need to parse a link to an article.
* The menu item is a link to the categories view and the <code>$segments</code> array has one item (<code>$id</code>). In this case we know that we need to parse a link to a category.
* The menu item is a link to a category. In this case, we know that any item in the <code>$segments</code> array is the identifier for an article.

The result of all this code is clean and human-readable component URLs.

== See Also ==

There is a useful thread on this subject here: [[jtopic:148632]] (note, may be out of date)

For details on the internals of routing, see [[Routing implementation details]].
<noinclude>[[Category:Tutorials]][[Category:Component Development]][[Category:Search Engine Friendly URLs]]</noinclude>

J2.5:Routing implementation details

2012-11-25T00:53:43Z

Mvangeest: Split off page from http://docs.joomla.org/index.php?title=Supporting_SEF_URLs_in_your_component&oldid=9893 (5 August 2008)

{{incomplete}}

== Application Route Parsing ==

The [[Application execution order]] outlines that the route (URL) is parsed immediately after initialisation is complete. Since fancy URL's are not treated (yet) in the Administrator, we will follow the route parsing process in detail when <code>JSite::route</code> in the <tt>index.php</tt> file.

* Call to <code>JApplication::route</code>
** Clone the URI
** Call to <code>JApplication::getRouter</code>
*** Call to <code>JRouter::getInstance</code> passing the type ("site")
** Call to <code>JRouterSite::parse</code> passing the URI
*** Strip the suffix if applicable (added to $vars['format'])
*** Re-set the route (URI)
*** Call to <code>JRouter::parse</code> passing the URI
**** Call to <code>JRouterSite::_processParseRules</code> passing the URI (this will call custom route rules)
***** Call to <code>JRouter::_processParseRules</code> passing the URI
****** Call any custom routing rules (probably added via a system plugin using the <code>onAfterInitialise</code> event trigger) passing the URI
****** Returns an array of vars
***** If SEF mode, replace <code>start</code> variable with </code>limitstart</code>
**** If raw mode, call to <code>JRouterSite::_parseRawRoute</code> passing the URI
**** If SEF mode, call to <code>JRouterSite::_parseSefRoute</code> passing the URI
***** If the route (the URI path) is empty, load it from the default menu item; set the active menu item as the default
***** If first part is <code>/component/com_content</code>, set the <code>option</code> as the second segement. Null the <code>Itemid</code>.
***** Else, loop through menu alias values and take off segments that match as the menu tree is traversed. Set <code>option</code> and <code>Itemid</code> based on the last menu item found.
***** If the <code>Itemid</code> is set in the URL, set the active menu item based on this value.
***** Push the vars collected so far (eg, <code>option</code>, <code>Itemid</code>, etc) into the router object (<code>$this</code>).
***** If the route and <code>option</code> is set, load the component router;
***** Else, get the active menu item and get the route vars from it

== Application Route Building ==

TODO

== Custom Router Rules ==

TODO

J2.5:Supporting SEF URLs in your component

2012-11-24T17:51:30Z

Mvangeest: Adjusted layout

{{incomplete}}
{{:Search Engine Friendly URLs}}
In Joomla!, each [[component]] is responsible for handling its own SEF URLs. Therefore, as the [[Developers|developer]] of a component, you will have to create your own '''router''' to allow your component to use SEF URLs.

== The Concept ==

Assuming you are following standard development practices, your component is probably using "system URLs" that look a lot like <tt><nowiki>http://www.example.com/index.php?option=com_yourcomponent&view=article&id=1&catid=20&Itemid=50</nowiki></tt>, and your goal is to transform this into <tt><nowiki>http://www.example.com/example-menu-item/20/1</nowiki></tt>. As the developer, you have two tasks: signalling the system that certain pieces of text are URLs and need to be transformed, and explaining the system how to transform URLs.

=== Applying <code>JRoute::_</code> ===

It is difficult and inefficient for Joomla! to figure out which parts of your component's output are URLs. To support SEF URLs, you will need to change URL-generating code so that it applies <code>JRoute::_</code> before outputting the URL:

<source lang="php">
echo JRoute::_('index.php?view=article&id=1&catid=20');
</source>

Notice that it is possible to leave out the parameters <code>option</code> and <code>Itemid</code>. <code>option</code> defaults to the name of the component currently being executed, and <code>Itemid</code> defaults to the current menu item's ID.

In general, you should only apply this to URLs that users and/or search engines are able to see. For example, there is no need to transform URLs used in redirects that immediately result in other redirects.

If the user turns off SEF URLs in the site's settings, <code>JRoute::_</code> will produce working non-SEF URLs without any changes to the code.

=== Writing a router ===

You'll also need to write a router, which is a single file with two functions that convert system URLs to and from SEF URLs. This file needs to be placed at <tt>/components/com_yourcomponent/router.php</tt>.

The first function, <code>[componentname]BuildRoute(&$query)</code>, must transform an array of URL parameters into an array of segments that will form the SEF URL. Schematically, the transformation works as follows:

:<tt><nowiki>http://www.example.com/index.php?option=com_yourcomponent&view=article&id=1&catid=20&Itemid=50</nowiki></tt>

::<span style="font-size: xx-large">↓</span> <code>JRoute::_</code>, called by your component or any other extension

:<code>$query = array('view' => 'article', 'id' => 1, 'catid' => 20)</code>

::<span style="font-size: xx-large">↓</span> Your router's <code>com_yourcomponentBuildRoute</code>

:<code>$segments = array(20, 1);</code>

::<span style="font-size: xx-large">↓</span> Joomla's internal routing (for display)

:<tt><nowiki>http://www.example.com/example-menu-item/20/1</nowiki></tt>

The second function, <code>[componentname]ParseRoute($segments)</code>, must transform an array of segments back into an array of URL parameters. Schematically:

:<tt><nowiki>http://www.example.com/example-menu-item/20/1</nowiki></tt>

::<span style="font-size: xx-large">↓</span> Joomla's internal routing

:<code>$segments = array(20, 1);</code>

::<span style="font-size: xx-large">↓</span> Your router's <code>com_yourcomponentParseRoute</code>

:<code>$query = array('view' => 'article', 'id' => 1, 'catid' => 20)</code>

The two functions must cooperate in such a way that the original URL can be reconstructed. You can think of <code>BuildRoute</code> as a form of [[wikipedia:Encoding|encoding]] and <code>ParseRoute</code> as the corresponding decoding. When the original URL isn't properly reproduced, your component will stop working.

== Preparing Your Data for Routing ==

=== The Alias ===

The first step is the generation of the so called alias. The alias is used in the URL instead of the title (the alias is the text you want to have in the URL). The alias has to be URI safe, which means accented UTF8 characters are replaced by their ASCII7 equivalents, white spaces by hyphens, etc.

The alias can be defined by the user, but you should ensure that the above requirements for a URL safe alias are met. A good way to do so is to use the JTable::check() method during the save process. Have a look at this example code:

<source lang="php">

function check()
{
jimport( 'joomla.filter.output' );
if(empty($this->alias)) {
$this->alias = $this->title;
}
$this->alias = JFilterOutput::stringURLSafe($this->alias);

/* All your other checks */
return true;
}
</source>

If the alias field is empty the title will be used as alias. Then the alias will be made URLSafe using the <code>JFilterOutput::stringURLSafe()</code> method.

=== The Slug ===

Continuing with the same example, the "slug" - "1:welcome-to-joomla" has two parts. The first part is the article identifier (id) and the second is the alias. They are separated by a colon. These two elements were combined during the database query in the model:

<source lang="php">$query = 'SELECT a.*, '.
'CASE WHEN CHAR_LENGTH(a.alias) THEN CONCAT_WS(":", a.id, a.alias) ELSE a.id END as slug,'
/*...*/;</source>

After this step the slug is used instead of the id.

== Routing URLs ==

The <code>JRoute::_</code> method translates the internal Joomla! URL to a custom URL. <tt>JRoute</tt> has three parameters and its prototype is:

<source lang="php">JRoute::_( $url, $xhtml = true, $ssl=null );</source>

Where:

* <code>$url</code> is a string containing the absolute or relative internal Joomla! URL.
* <code>$xhtml</code> is a boolean value that specifies whether or not the output should be in XHTML. This parameter is optional and if omitted defaults to true.
* <code>$ssl</code> is an integer value that specifies whether the URI should be secure. It should be set to 1 to force the URI to be secure using the global secure site URI, 0 to leave it in the same state as when it was passed, and -1 to force the URI to be unsecure using the global unsecure site URI.

The most important parameter is <code>$url</code>. A call to this method might look like:

<source lang="php">JRoute::_( 'index.php?view=article&id='.$row->slug );</source>

<code>$row->slug</code> is the value that was generated in step 2 from a combination of id and title alias.

Another advantage of using JRoute is that the router now handles $option (the component name) and the $Itemid (the menu item ID). The component itself doesn’t have to know its name ($option) or the active menu item ($Itemid) like it did in previous version of Joomla!.

It is important that you think about the sequence of the URL parameter in this stage. This will be more clear when we have a deeper look at the router.php in the next section.

The building process of JRouter is divided into two steps:

* Create the application route. The application route is fully handled by JRouter and the component developer doesn’t have to do anything to make it work.
* Create the component route. To create the component route, JRouter looks for the <tt>router.php</tt> in the component directory which is responsible for building the route for the component.

== The Component Router ==

We will have two functions in the <tt>router.php</tt>. One is responsible for building the URL and the other is responsible for parsing it. In the next examples, a very basic and a more advanced one, we assume that we have three views that links can point to. The first is a categories overview (<code>view=categories</code>), the second is a single category (<code>view=category</code>) and the third is a single article (<code>view=article</code>).

The file <tt>router.php</tt> should be in the site area of your component. It is not used on admin/backend pages. Don't forget to add it to your XML [[Manifest files|manifest file]] in the site folder.

=== A Simple Example ===

This simple example will illustrate the basics of implementing a router for your component.

<source lang="php">
function [componentname]BuildRoute( &$query )
{
$segments = array();
if(isset($query['view']))
{
$segments[] = $query['view'];
unset( $query['view'] );
}
if(isset($query['id']))
{
$segments[] = $query['id'];
unset( $query['id'] );
};
return $segments;
}

</source>

<code>JRouter</code> passes a $query array to the <code>[''componentname'']BuildRoute</code> function. This function will add the relevant parts of the array to the $segments array in the right order and will return the properly ordered array. The content of the <code>$query</code> array needs to be unset, otherwise <code>JRouter</code> will add it to the URL in the form of a query string (i.e. any variables that are not handled by the router will be passed in the query string).

The prefix ''componentname'' is the name for your component, as found in the directory holding the component's files. For instance, a component "Magic" in directory <tt>/components/com_magic/...</tt> would use a prefix <code>magic</code> (all lower case).

The next function in the <tt>router.php</tt> parses the URL:

<source lang="php">
function [componentname]ParseRoute( $segments )
{
$vars = array();
switch($segments[0])
{
case 'categories':
$vars['view'] = 'categories';
break;
case 'category':
$vars['view'] = 'category';
$id = explode( ':', $segments[1] );
$vars['id'] = (int) $id[0];
break;
case 'article':
$vars['view'] = 'article';
$id = explode( ':', $segments[1] );
$vars['id'] = (int) $id[0];
break;
}
return $vars;
}
</source>

What happens here? In the function <code>[''componentname'']BuildRoute</code> we arranged the items in the <code>$query</code> array in a specific sequence. This means that in this example the view is first and the id is second in the array.

By reading <code>$segments[0]</code>, we access the name of the view. We set the right view and/or identifier depending on its value and we return the <code>$vars</code> array to <code>JRouter</code>. $vars should be an associative array similar to the array that was passed to the BuildRoute method.

The above example of the <tt>router.php</tt> is a very simple way to generate sef URL's but should show how this works quite clearly.

The generated URL in this example contains the name of the view and doesn't reflect the content hierarchy:

<tt><nowiki>http://www.example.com/[menualias]/[view]/[slug]</nowiki></tt>

=== A More Advanced Example ===

In the next example we will try to get rid of the need for the view and we will try to reflect the current hierarchy level in the URL.

The goal is URL's that look like:

* When viewing an article: <tt><nowiki>http://www.example.com/[menualias]/[category]/[article]</nowiki></tt>
* When viewing a category: <tt><nowiki>http://www.example.com/[menualias]/[category]</nowiki></tt>
* When viewing the categories overview: <tt><nowiki>http://www.example.com/[menualias]</nowiki></tt>

Let's assume we have done step 1 and 2 also for the category.

The link to the article would look like this:

<source lang="php">
JRoute::_( 'index.php?view=article&catid='.$row->catslug .'&id='.$row->slug );
</source>

And the Link to the category would look like this:

<source lang="php">
JRoute::_( 'index.php?view=category&id='.$row->catslug );
</source>

The corresponding <tt>router.php</tt>:

<source lang="php">

function [''Componentname'']BuildRoute(&$query)
{
$segments = array();
if(isset( $query['catid'] ))
{
$segments[] = $query['catid'];
unset( $query['catid'] );
};
if( isset($query['id']) )
{
$segments[] = $query['id'];
unset( $query['id'] );
};
unset( $query['view'] );
return $segments;
}
</source>

The difference now is that we don’t add the name of the view to the <code>$segments</code> array. We still unset the view key since otherwise, <code>JRouter</code> would add it to the URL as part of the query string. Another new thing here is the additional parameter catid that we push into the <code>$segments</code> array.

<source lang="php">
function [''Componentname'']ParseRoute($segments)
{
$vars = array();
$app =& JFactory::getApplication();
$menu =& $app->getMenu();
$item =& $menu->getActive();
// Count segments
$count = count( $segments );
//Handle View and Identifier
switch( $item->query['view'] )
{
case 'categories':
if($count == 1) {
$vars['view'] = 'category';
}
if($count == 2) {
$vars['view'] = 'article';
}
$id = explode( ':', $segments[$count-1] );
$vars['id'] = (int) $id[0];
break;
case 'category':
$id = explode( ':', $segments[$count-1] );
$vars['id'] = (int) $id[0];
$vars['view'] = 'article';
break;
}
return $vars;
}
</source>

You can see that this ParseRoute function has a lot of different code parts in comparison to the previous. The reason for this is simple. We don’t have the name of the view in the <code>$segments</code> array and we need to find another way to determine it.

We need to find out which level of hierarchy we are in by receiving the root element. We do this by looking to the view name of the active menu item:

<source lang="php">
$item->query['view']
</source>

Also we need to know the number of items in the <code>$segments</code> array:

<source lang="php">
$count = count( $segments );
</source>

With this information we can correctly set the view for all possible three cases:

* The menu item is a link to the categories view and the <code>$segments</code> array has two items (<code>$catid</code> and <code>$id</code>). In this case we know that we need to parse a link to an article.
* The menu item is a link to the categories view and the <code>$segments</code> array has one item (<code>$id</code>). In this case we know that we need to parse a link to a category.
* The menu item is a link to a category. In this case, we know that any item in the <code>$segments</code> array is the identifier for an article.

The result of all this code is clean and human-readable component URLs.

== Application Route Parsing ==

The [[Application execution order]] outlines that the route (URL) is parsed immediately after initialisation is complete. Since fancy URL's are not treated (yet) in the Administrator, we will follow the route parsing process in detail when <code>JSite::route</code> in the <tt>index.php</tt> file.

* Call to <code>JApplication::route</code>
** Clone the URI
** Call to <code>JApplication::getRouter</code>
*** Call to <code>JRouter::getInstance</code> passing the type ("site")
** Call to <code>JRouterSite::parse</code> passing the URI
*** Strip the suffix if applicable (added to $vars['format'])
*** Re-set the route (URI)
*** Call to <code>JRouter::parse</code> passing the URI
**** Call to <code>JRouterSite::_processParseRules</code> passing the URI (this will call custom route rules)
***** Call to <code>JRouter::_processParseRules</code> passing the URI
****** Call any custom routing rules (probably added via a system plugin using the <code>onAfterInitialise</code> event trigger) passing the URI
****** Returns an array of vars
***** If SEF mode, replace <code>start</code> variable with </code>limitstart</code>
**** If raw mode, call to <code>JRouterSite::_parseRawRoute</code> passing the URI
**** If SEF mode, call to <code>JRouterSite::_parseSefRoute</code> passing the URI
***** If the route (the URI path) is empty, load it from the default menu item; set the active menu item as the default
***** If first part is <code>/component/com_content</code>, set the <code>option</code> as the second segement. Null the <code>Itemid</code>.
***** Else, loop through menu alias values and take off segments that match as the menu tree is traversed. Set <code>option</code> and <code>Itemid</code> based on the last menu item found.
***** If the <code>Itemid</code> is set in the URL, set the active menu item based on this value.
***** Push the vars collected so far (eg, <code>option</code>, <code>Itemid</code>, etc) into the router object (<code>$this</code>).
***** If the route and <code>option</code> is set, load the component router;
***** Else, get the active menu item and get the route vars from it

== Application Route Building ==

TODO

== Custom Router Rules ==

TODO

== Additional References ==

There is a useful thread on this subject here: [[jtopic:148632]] (note, may be out of date)
<noinclude>[[Category:Tutorials]][[Category:Component Development]][[Category:Search Engine Friendly URLs]]</noinclude>

J2.5:Supporting SEF URLs in your component

2012-11-24T17:33:38Z

Mvangeest: Added information

{{incomplete}}
{{:Search Engine Friendly URLs}}
In Joomla!, each [[component]] is responsible for handling its own SEF URLs. Therefore, as the [[Developers|developer]] of a component, you will have to create your own '''router''' to allow your component to use SEF URLs.

== The Concept ==

Assuming you are following standard development practices, your component is probably using "system URLs" that look a lot like <tt><nowiki>http://www.example.com/index.php?option=com_yourcomponent&view=article&id=1&catid=20&Itemid=50</nowiki></tt>, and your goal is to transform this into <tt><nowiki>http://www.example.com/example-menu-item/20/1</nowiki></tt>. As the developer, you have two tasks: signalling the system that certain pieces of text are URLs and need to be transformed, and explaining the system how to transform URLs.

=== Applying <code>JRoute::_</code> ===

It is difficult and inefficient for Joomla! to figure out which parts of your component's output are URLs. To support SEF URLs, you will need to change URL-generating code so that it applies <code>JRoute::_</code> before outputting the URL:

<source lang="php">
echo JRoute::_('index.php?view=article&id=1&catid=20');
</source>

Notice that it is possible to leave out the parameters <code>option</code> and <code>Itemid</code>. <code>option</code> defaults to the name of the component currently being executed, and <code>Itemid</code> defaults to the current menu item's ID.

In general, you should only apply this to URLs that users and/or search engines are able to see. For example, there is no need to transform URLs used in redirects that immediately result in other redirects.

If the user turns off SEF URLs in the site's settings, <code>JRoute::_</code> will produce working non-SEF URLs without any changes to the code.

=== Writing a router ===

You'll also need to write a router, which is a single file with two functions that convert system URLs to and from SEF URLs. This file needs to be placed at <tt>/components/com_yourcomponent/router.php</tt>.

The first function, <code>[componentname]BuildRoute(&$query)</code>, must transform an array of URL parameters into an array of segments that will form the SEF URL. Schematically, the transformation works as follows:

:<tt><nowiki>http://www.example.com/index.php?option=com_yourcomponent&view=article&id=1&catid=20&Itemid=50</nowiki></tt>

::<span style="font-size: xx-large">↓</span> <code>JRoute::_</code>, called by your component or any other extension

:<code>$query = array('view' => 'article', 'id' => 1, 'catid' => 20)</code>

::<span style="font-size: xx-large">↓</span> Your router's <code>com_yourcomponentBuildRoute</code>

:<code>$segments = array(20, 1);</code>

::<span style="font-size: xx-large">↓</span> Joomla's internal routing (for display)

:<tt><nowiki>http://www.example.com/example-menu-item/20/1</nowiki></tt>

The second function, <code>[componentname]ParseRoute($segments)</code>, must transform an array of segments back into an array of URL parameters. Schematically:

:<tt><nowiki>http://www.example.com/example-menu-item/20/1</nowiki></tt>

::<span style="font-size: xx-large">↓</span> Joomla's internal routing

:<code>$segments = array(20, 1);</code>

::<span style="font-size: xx-large">↓</span> Your router's <code>com_yourcomponentParseRoute</code>

:<code>$query = array('view' => 'article', 'id' => 1, 'catid' => 20)</code>

The two functions must cooperate in such a way that the original URL can be reconstructed. You can think of <code>BuildRoute</code> as a form of [[wikipedia:Encoding|encoding]] and <code>ParseRoute</code> as the corresponding decoding. When the original URL isn't properly reproduced, your component will stop working.

== Preparing Your Data for Routing ==

=== The Alias ===

The first step is the generation of the so called alias. The alias is used in the URL instead of the title (the alias is the text you want to have in the URL). The alias has to be URI safe, which means accented UTF8 characters are replaced by their ASCII7 equivalents, white spaces by hyphens, etc.

The alias can be defined by the user, but you should ensure that the above requirements for a URL safe alias are met. A good way to do so is to use the JTable::check() method during the save process. Have a look at this example code:

<source lang="php">

function check()
{
jimport( 'joomla.filter.output' );
if(empty($this->alias)) {
$this->alias = $this->title;
}
$this->alias = JFilterOutput::stringURLSafe($this->alias);

/* All your other checks */
return true;
}
</source>

If the alias field is empty the title will be used as alias. Then the alias will be made URLSafe using the JFilterOutput::stringURLSafe() method.

=== The Slug ===

Continuing with the same example, the "slug" - "1:welcome-to-joomla" has two parts. The first part is the article identifier (id) and the second is the alias. They are separated by a colon. These two elements were combined during the database query in the model:

<source lang="php">$query = 'SELECT a.*, '.
'CASE WHEN CHAR_LENGTH(a.alias) THEN CONCAT_WS(":", a.id, a.alias) ELSE a.id END as slug,'
/*...*/;</source>

After this step the slug is used instead of the id.

== Routing URLs ==

The <code>JRoute::_</code> method translates the internal Joomla! URL to a custom URL. <code>JRoute</code> has three parameters and its prototype is:

<source lang="php">JRoute::_( $url, $xhtml = true, $ssl=null );</source>

Where:

* <code>$url</code> is a string containing the absolute or relative internal Joomla! URL.
* <code>$xhtml</code> is a boolean value that specifies whether or not the output should be in XHTML. This parameter is optional and if omitted defaults to true.
* <code>$ssl</code> is an integer value that specifies whether the URI should be secure. It should be set to 1 to force the URI to be secure using the global secure site URI, 0 to leave it in the same state as when it was passed, and -1 to force the URI to be unsecure using the global unsecure site URI.

The most important parameter is <code>$url</code>. A call to this method might look like:

<source lang="php">JRoute::_( 'index.php?view=article&id='.$row->slug );</source>

<code>$row->slug</code> is the value that was generated in step 2 from a combination of id and title alias.

Another advantage of using JRoute is that the router now handles $option (the component name) and the $Itemid (the menu item ID). The component itself doesn’t have to know its name ($option) or the active menu item ($Itemid) like it did in previous version of Joomla!.

It is important that you think about the sequence of the URL parameter in this stage. This will be more clear when we have a deeper look at the router.php in the next section.

The building process of JRouter is divided into two steps:

* Create the application route. The application route is fully handled by JRouter and the component developer doesn’t have to do anything to make it work.
* Create the component route. To create the component route, JRouter looks for the router.php in the component directory which is responsible for building the route for the component.

== The Component Router ==

We will have two functions in the router.php. One is responsible for building the URL and the other is responsible for parsing it. In the next examples, a very basic and a more advanced one, we assume that we have three views that links can point to. The first is a categories overview (view=categories), the second is a single category (view=category) and the third is a single article (view=article).

The file router.php should be in the site area of your component. It is not used on admin/backend pages. Don't forget to add it to your installation XML in the site folder.

=== A Simple Example ===

This simple example will illustrate the basics of implementing a router for your component.

<source lang="php">
function [componentname]BuildRoute( &$query )
{
$segments = array();
if(isset($query['view']))
{
$segments[] = $query['view'];
unset( $query['view'] );
}
if(isset($query['id']))
{
$segments[] = $query['id'];
unset( $query['id'] );
};
return $segments;
}

</source>

<code>JRouter</code> passes a $query array to the <code>[''componentname'']BuildRoute</code> function. This function will add the relevant parts of the array to the $segments array in the right order and will return the properly ordered array. The content of the <code>$query</code> array needs to be unset, otherwise <code>JRouter</code> will add it to the URL in the form of a query string (i.e. any variables that are not handled by the router will be passed in the query string).

The prefix ''componentname'' is the name for your component, as found in the directory holding the component's files. For instance, a component "Magic" in directory <code>/components/com_magic/...</code> would use a prefix <code>magic</code> (all lower case).

The next function in the <code>router.php</code> parses the URL:

<source lang="php">
function [componentname]ParseRoute( $segments )
{
$vars = array();
switch($segments[0])
{
case 'categories':
$vars['view'] = 'categories';
break;
case 'category':
$vars['view'] = 'category';
$id = explode( ':', $segments[1] );
$vars['id'] = (int) $id[0];
break;
case 'article':
$vars['view'] = 'article';
$id = explode( ':', $segments[1] );
$vars['id'] = (int) $id[0];
break;
}
return $vars;
}
</source>

What happens here? In the function <code>[''componentname'']BuildRoute</code> we arranged the items in the <code>$query</code> array in a specific sequence. This means that in this example the view is first and the id is second in the array.

By reading <code>$segments[0]</code>, we access the name of the view. We set the right view and/or identifier depending on its value and we return the <code>$vars</code> array to <code>JRouter</code>. $vars should be an associative array similar to the array that was passed to the BuildRoute method.

The above example of the <code>router.php</code> is a very simple way to generate sef URL's but should show how this works quite clearly.

The generated URL in this example contains the name of the view and doesn't reflect the content hierarchy:

<code><nowiki>http://www.example.com/[menualias]/[view]/[slug]</nowiki></code>

=== A More Advanced Example ===

In the next example we will try to get rid of the need for the view and we will try to reflect the current hierarchy level in the URL.

The goal is URL's that look like:

* When viewing an article: <code><nowiki>http://www.example.com/[menualias]/[category]/[article]</nowiki></code>
* When viewing a category: <code><nowiki>http://www.example.com/[menualias]/[category]</nowiki></code>
* When viewing the categories overview: <code><nowiki>http://www.example.com/[menualias]</nowiki></code>

Let's assume we have done step 1 and 2 also for the category.

The link to the article would look like this:

<source lang="php">
JRoute::_( 'index.php?view=article&catid='.$row->catslug .'&id='.$row->slug );
</source>

And the Link to the category would look like this:

<source lang="php">
JRoute::_( 'index.php?view=category&id='.$row->catslug );
</source>

The corresponding <code>router.php</code>:

<source lang="php">

function [''Componentname'']BuildRoute(&$query)
{
$segments = array();
if(isset( $query['catid'] ))
{
$segments[] = $query['catid'];
unset( $query['catid'] );
};
if( isset($query['id']) )
{
$segments[] = $query['id'];
unset( $query['id'] );
};
unset( $query['view'] );
return $segments;
}
</source>

The difference now is that we don’t add the name of the view to the <code>$segments</code> array. We still unset the view key since otherwise, <code>JRouter</code> would add it to the URL as part of the query string. Another new thing here is the additional parameter catid that we push into the <code>$segments</code> array.

<source lang="php">
function [''Componentname'']ParseRoute($segments)
{
$vars = array();
$app =& JFactory::getApplication();
$menu =& $app->getMenu();
$item =& $menu->getActive();
// Count segments
$count = count( $segments );
//Handle View and Identifier
switch( $item->query['view'] )
{
case 'categories':
if($count == 1) {
$vars['view'] = 'category';
}
if($count == 2) {
$vars['view'] = 'article';
}
$id = explode( ':', $segments[$count-1] );
$vars['id'] = (int) $id[0];
break;
case 'category':
$id = explode( ':', $segments[$count-1] );
$vars['id'] = (int) $id[0];
$vars['view'] = 'article';
break;
}
return $vars;
}
</source>

You can see that this ParseRoute function has a lot of different code parts in comparison to the previous. The reason for this is simple. We don’t have the name of the view in the <code>$segments</code> array and we need to find another way to determine it.

We need to find out which level of hierarchy we are in by receiving the root element. We do this by looking to the view name of the active menu item:

<source lang="php">
$item->query['view']
</source>

Also we need to know the number of items in the <code>$segments</code> array:

<source lang="php">
$count = count( $segments );
</source>

With this information we can correctly set the view for all possible three cases:

* The menu item is a link to the categories view and the <code>$segments</code> array has two items (<code>$catid</code> and <code>$id</code>). In this case we know that we need to parse a link to an article.
* The menu item is a link to the categories view and the $segments array has one item ($id). In this case we know that we need to parse a link to a category.
* The menu item is a link to a category. In this case, we know that any item in the $segments array is the identifier for an article.

The result of all this code is clean and human-readable component URLs.

== Application Route Parsing ==

The [[Application execution order]] outlines that the route (URL) is parsed immediately after initialisation is complete. Since fancy URL's are not treated (yet) in the Administrator, we will follow the route parsing process in detail when <code>JSite::route</code> in the <code>index.php</code> file.

* Call to <code>JApplication::route</code>
** Clone the URI
** Call to <code>JApplication::getRouter</code>
*** Call to <code>JRouter::getInstance</code> passing the type ("site")
** Call to <code>JRouterSite::parse</code> passing the URI
*** Strip the suffix if applicable (added to $vars['format'])
*** Re-set the route (URI)
*** Call to <code>JRouter::parse</code> passing the URI
**** Call to <code>JRouterSite::_processParseRules</code> passing the URI (this will call custom route rules)
***** Call to <code>JRouter::_processParseRules</code> passing the URI
****** Call any custom routing rules (probably added via a system plugin using the <code>onAfterInitialise</code> event trigger) passing the URI
****** Returns an array of vars
***** If SEF mode, replace <code>start</code> variable with </code>limitstart</code>
**** If raw mode, call to <code>JRouterSite::_parseRawRoute</code> passing the URI
**** If SEF mode, call to <code>JRouterSite::_parseSefRoute</code> passing the URI
***** If the route (the URI path) is empty, load it from the default menu item; set the active menu item as the default
***** If first part is <code>/component/com_content</code>, set the <code>option</code> as the second segement. Null the <code>Itemid</code>.
***** Else, loop through menu alias values and take off segments that match as the menu tree is traversed. Set <code>option</code> and <code>Itemid</code> based on the last menu item found.
***** If the <code>Itemid</code> is set in the URL, set the active menu item based on this value.
***** Push the vars collected so far (eg, <code>option</code>, <code>Itemid</code>, etc) into the router object (<code>$this</code>).
***** If the route and <code>option</code> is set, load the component router;
***** Else, get the active menu item and get the route vars from it

== Application Route Building ==

TODO

== Custom Router Rules ==

TODO

== Additional References ==

There is a useful thread on this subject here: [[jtopic:148632]] (note, may be out of date)
<noinclude>[[Category:Tutorials]][[Category:Component Development]][[Category:Search Engine Friendly URLs]]</noinclude>

Search Engine Friendly URLs

2012-11-21T01:26:05Z

Mvangeest: Added information - first attempt

<onlyinclude>
'''Search engine friendly (SEF)''', '''human-readable''' or [[wikipedia:Clean_URL|clean URLs]] are URLs that make sense to both humans and search engines because they explain the path to the particular page they point to. Since version 1.5, Joomla! is capable of creating and parsing URLs in any format, including SEF URLs. This does not depend on URL rewriting executed by the web server, so it works even if Joomla! runs a server other than Apache with the mod_rewrite module. The SEF URLs follow a certain fixed pattern, but the user can define a [[Alias|short descriptive text (alias)]] for each segment of the URL.

Internally, the local part of a SEF URL (the part after the domain name) is called a '''route'''. Creating and processing SEF URLs is therefore referred to as '''routing''', and the relevant code is called a '''router'''.
</onlyinclude>
A good example of routing is the URL to "Welcome to Joomla!" article in the sample data.

* Without SEF URLs turned on, the URL is <tt><nowiki>http://www.example.com/index.php?option=com_content&view=article&id=1:welcome-to-joomla&catid=1:latest-news&Itemid=50</nowiki></tt>
* With SEF URLs on and mod_rewrite off, it's <tt><nowiki>http://www.example.com/index.php/the-news/1-latest-news/1-welcome-to-joomla</nowiki></tt>
* With both SEF URLs and mod_rewrite on, it's <tt><nowiki>http://www.example.com/the-news/1-latest-news/1-welcome-to-joomla</nowiki></tt>

Search engine friendly URLs can be activated by turning on the '''Search Engine Friendly URLs''' option in the ''Global Configuration''. This option is on by default since Joomla! 1.6. See [[Enabling Search Engine Friendly (SEF) URLs]] for more information.

== Frequently Asked Questions ==

=== What do the numbers in the URL mean? ===
By comparing the old and the new URL we can see numbers in the old URL,

<tt><nowiki>http://www.example.com/index.php?option=com_content&view=article&id=1:welcome-to-joomla&catid=1:latest-news&Itemid=50</nowiki></tt>

but also in the new URL:

<tt><nowiki>http://www.example.com/the-news/1-latest-news/1-welcome-to-joomla</nowiki></tt>

These numbers are the parameters that are needed by Joomla! to get the internal URL and show the page you want to see. (In this case, the first numeral one is the ID of the category, the second numeral one is the ID of the article.)

=== There is no <tt>index.php</tt> in the URL anymore. Can I delete the file now? ===
No! The URL may doesn't contain the <tt>index.php</tt> anymore, but internally the mod_rewrite will only redirect to the original path without showing it to you.

=== What is the [[Alias]] value? And how does it get created? ===
Alias is listed beneath the Title field in Articles, Categories, Sections and Menu Items. Joomla! can automatically create the alias for you. An automatic alias begins with the title. All upper case letters are changed to lower case. Spaces and special characters not allowed in a URL; they are changed to dashes.

=== I want to specify my own value for Alias. ===
If you do not like the alias provided by Joomla!, you can enter a value of your choosing into that field. Many believe using good keywords in your URL helps search engine optimization. You can do so by including those keywords in your title, and allowing Joomla! to create the alias, or by creating the alias yourself.

=== How is Alias used in a URL? ===
For a menu item, Joomla! uses the alias as the URL plug. Assume that you use the first two SEF URL options and you create a menu item called Products. Your URL would be example.com/products.

Joomla! also uses the primary key values of data within the URL to help the router navigate to the correct page. Continuing with the previous example, if your products menu item was for an Article/Category Blog, the link for the Article Title and/or Read More link would have three parts:

* The menu item URL - example.com/products;

* Plus, the primary key for the Category and the Category alias - 32-fruit;

* Plus, the primary key for the Article and the Article alias - 1-apple;

The complete URL is: <tt><nowiki>http://example.com/products/32-fruit/1-apple</nowiki></tt>

=== How can I get rid of the numbers in the SEF URLs? ===
The numbers in the SEF URL are needed by Joomla!'s router to know how to direct site traffic. Once the router logic stabilizes, simple third party system plugins can be developed to augment the router capabilities by allowing more choice. At that time, numbers will likely be removed from the URL.

== Route Formats and Routing Mechanism ==

''This section describes Joomla!'s core (built-in) routing mechanism. Routing extensions may change the way routes are created on your system.''

To describe the Joomla! routing mechanism in more detail, we first need to pin down what we refer to as a '''route'''. In our example URL, <tt><nowiki>http://example.com/sites/first/products/32-fruit/1-apple</nowiki></tt>, <tt><nowiki>http://example.com/sites/first/</nowiki></tt> is the part of the URL that is the same for all URLs managed by a Joomla! installation. It is generally referred to as the '''base URL'''. Neither Joomla! nor any component router can create URLs with a different first part. The second part, <tt>products/32-fruit/1-apple</tt>, is a '''route''', consisting of three '''segment'''s.

The first segment of a route is, for regular URLs, the alias of a menu item. This means that only routes that use menu items will function entirely correctly. The SEF URL is said to be '''routed through''' that menu item. The other segments are determined entirely by the router of the component that provides the type of the menu item. The ''Category - Blog'' menu item type, for example, is provided by the [[Content]] component, and therefore that component's router is responsible for building and parsing the remaining segements.

It is also possible (for extensions) to ask the system to create a route without supplying a menu item to route through. In that case, the system will usually decide to create a ''component route'', meaning the first segment of the route will be the word <tt>component</tt>. The component router follows a fixed format, choosing the name of the component (without the leading <tt>com_</tt>) as the second segment and any parameters as the other segments.

It is important to note that it is not possible for a Joomla! user to define a route that leads to a specific component without making a menu item. (Systems that do have this possibility usually call it a ''global route''.) This reduces the chance of ambiguous routes, i.e. routes that could lead to two different pages, since the menu item alias directly specifies which component's router is allowed to parse a certain route. Also, creating a route that behaves as a global route is not difficult. An often-applied method is to create a menu item in a menu that isn't displayed anywhere. Such a menu is usually called a [[Menu|hidden menu]].

== Implementation Details ==
=== Joomla Routes ===

''This section describes the routing implementation. If you are a component developer, see [[Supporting SEF URLs in your component]].''

Joomla routes are created and resolved by [[JRouter|the JRouter class]]. This class looks in the component root of the currently active component (specified in the <code>option</code> parameter in the query string) and includes the <tt>router.php</tt> file in that component's root directory. It then calls one of two functions: one for creating the SEF URL and one for interpreting the SEF URL.

The JRouter class is overridden by the Joomla CMS in <tt>/includes/router.php</tt>. In this file the build and parse functions are overridden to properly build and parse the URLs for the Joomla CMS.

The <tt>router.php</tt> file in each component (for example, <tt>/components/com_content/router.php</tt>) should contain the following two functions:
* ContentBuildRoute - this builds the SEF URL
** Parameters
*** $query - this is a named array containing the querystring variables
** Returns: an array of segments where each segment is separated by a '/' when later combined to create the actual URL (the items in the array should not contain '/' characters)
* ContentParseRoute - this interprets an SEF URL
** Parameters
*** $segments - this is an array that contains the segments of the URL requested.
** Returns: a name => value array of the querystring variables that the link maps to

=== The SEF Plugin ===
The Joomla ''System - SEF'' plugin inherits <code>JPlugin</code> and implements the <code>onAfterRender()</code> function. In this function the body of the response that will be sent to the browser is retrieved using <code>JResponse::getBody()</code>. The body of the response is then searched for links containing <tt>/index.php...</tt> and replaces them with a correct SEF URL by calling <code>JRoute::_(''url'')</code>.

JRoute builds SEF URLs by instantiating a <code>JRouter</code> object and requesting that it build the correct link from the passed in URL.

=== Handling SEF URLs ===
By default the SEF URLs are handled by the <code>JRouterSite</code> object (from <tt>/includes/router.php</tt>) and is called by a call to <code>JApplication::route()</code> in index.php. This call is made on the <code>$app</code> variable which is actually an instance of <code>JSite</code> (from <tt>/includes/application.php</tt>).

<code>JApplication::route()</code> has a non-destructive result on the <code>$_GET</code> array. That is, <code>JApplication::route()</code> sets variables in <code>$_GET</code> by calling <code>JRequest::set()</code> with the overwrite flag set to false. Thus if a variable name is returned from <code>JRouter::route()</code> that is already in <code>$_GET</code>, it will not put that value into <code>$_GET</code>. This allows for custom routing.

=== Custom Routing ===
Joomla allows you to create your own routing mechanism. In order to create this mechanism you must have a plugin that overrides the <code>JPlugin::onAfterInitialise()</code> function. This function then parses the URL and creates the needed variables in <code>$_GET</code> before the standard Joomla routing is done.

''See [[Creating a System Plugin to augment JRouter]] for an example.''

[[Category:Search Engine Friendly URLs| ]]