Joomla! Documentation - User contributions [en]

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

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

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>

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

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>

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

Search Engine Friendly URLs

2012-11-20T22:25:09Z

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, creating and processing SEF URLs is called '''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.

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

[[Category:Search Engine Friendly URLs| ]]

J2.5:Developing a MVC Component/Example of a frontend update function

2012-11-17T19:43:19Z

Mvangeest: Added warning and removed incorrect entry from file listings

{{warning|The methods used in this document do not adhere to best practices and do not make optimal use of the flexibility provided by Joomla. More specifically, it is possible and recommended to reuse the model and form created during [[{{BASEPAGENAME}}/Adding_backend_actions|Part 9 (Adding backend actions)]] for front-end editing. Also, when using <code>JModelForm</code>, one should use the data manipulation methods provided by <code>JModelForm</code> instead of a custom <code>updItem</code> method. '''This code is not harmful''' and can be used in components, but could be written in a simpler and more maintainable way. If you are an expert developer, please consider editing this page to use the capabilities mentioned.}}
{{review|technical|This article needs to be reviewed by someone who knows what they're doing.}}
{{version/tutor|2.5}}
{{Chunk:Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Contents}}

== Introduction ==
This tutorial is part of the [[Developing a Model-View-Controller (MVC) Component for Joomla!2.5]] tutorial. You are encouraged to read the previous parts of the tutorial before reading this.

== Basic frontend form ==
Designing the frontend interface leads us to create a Model-View-Controller triptych similar to the backend in Part 7.

== Create the specific controller ==
The entry point now gets an instance of an ''UpdHelloWorld'' prefixed controller which extends the function of JControllerForm. Let's create a basic controllerform for the site part:

<span id="site/controllers/updhelloworld.php">
''site/controllers/updhelloworld.php''
<source lang="php">
<?php

// No direct access.
defined('_JEXEC') or die;

// Include dependancy of the main controllerform class
jimport('joomla.application.component.controllerform');

class HelloWorldControllerUpdHelloWorld extends JControllerForm
{

public function getModel($name = '', $prefix = '', $config = array('ignore_request' => true))
{
return parent::getModel($name, $prefix, array('ignore_request' => false));
}

public function submit()
{
// Check for request forgeries.
JRequest::checkToken() or jexit(JText::_('JINVALID_TOKEN'));

// Initialise variables.
$app = JFactory::getApplication();
$model = $this->getModel('updhelloworld');

// Get the data from the form POST
$data = JRequest::getVar('jform', array(), 'post', 'array');

// Now update the loaded data to the database via a function in the model
$upditem = $model->updItem($data);

// check if ok and display appropriate message. This can also have a redirect if desired.
if ($upditem) {
echo "<h2>Updated Greeting has been saved</h2>";
} else {
echo "<h2>Updated Greeting failed to be saved</h2>";
}

return true;
}

}
</source>
</span>

This controller will display the appropriate message after the form is submitted.

== Create the view ==

With your favorite file manager and editor, create a file ''site/views/updhelloworld/view.html.php'' containing:

<span id="site/views/updhelloworld/view.html.php">
''site/views/updhelloworld/view.html.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import Joomla view library
jimport('joomla.application.component.view');

/**
* HTML View class for the UpdHelloWorld Component
*/
class HelloWorldViewUpdHelloWorld extends JView
{
// Overwriting JView display method
function display($tpl = null)
{
$app = JFactory::getApplication();
$params = $app->getParams();
$dispatcher = JDispatcher::getInstance();

// Get some data from the models
$state = $this->get('State');
$item = $this->get('Item');
$this->form = $this->get('Form');

// Check for errors.
if (count($errors = $this->get('Errors')))
{
JError::raiseError(500, implode('<br />', $errors));
return false;
}
// Display the view
parent::display($tpl);
}
}
</source>
</span>

In Joomla, views display data using a layout. With your favorite file manager and editor, put a file ''site/views/updhelloworld/tmpl/default.php'' containing

<span id="site/views/updhelloworld/tmpl/default.php">
''site/views/updhelloworld/tmpl/default.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

JHtml::_('behavior.keepalive');
JHtml::_('behavior.formvalidation');
JHtml::_('behavior.tooltip');

?>
<h2>Update the Hello World greeting</h2>

<form class="form-validate" action="<?php echo JRoute::_('index.php'); ?>" method="post" id="updhelloworld" name="updhelloworld">
<fieldset>
<dl>
<dt><?php echo $this->form->getLabel('id'); ?></dt>
<dd><?php echo $this->form->getInput('id'); ?></dd>
<dt></dt><dd></dd>
<dt><?php echo $this->form->getLabel('greeting'); ?></dt>
<dd><?php echo $this->form->getInput('greeting'); ?></dd>
<dt></dt><dd></dd>
<dt></dt>
<dd><input type="hidden" name="option" value="com_helloworld" />
<input type="hidden" name="task" value="updhelloworld.submit" />
</dd>
<dt></dt>
<dd><button type="submit" class="button"><?php echo JText::_('Submit'); ?></button>
<?php echo JHtml::_('form.token'); ?>
</dd>
</dl>
</fieldset>
</form>
<div class="clr"></div>

</source>
</span>

This layout utilises the forms design which resides with the related model. The getLabel and getInput will pickup the xml fields defined and display appropriately. More on the xml file within the models section of this tutorial.

Create a file ''site/views/updhelloworld/tmpl/default.xml'' containing

<span id="site/views/updhelloworld/tmpl/default.xml">
''site/views/updhelloworld/tmpl/default.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<metadata>
<layout title="COM_HELLOWORLD_UPDHELLOWORLD_VIEW_DEFAULT_TITLE">
<message>COM_HELLOWORLD_UPDHELLOWORLD_VIEW_DEFAULT_DESC</message>
</layout>
</metadata>

</source>
</span>

This enables a menu option to be allocated to the frontend form.

== Create the model ==
The ''UpdHelloWorld'' model sets up the data through from the related form and allows the mechanism to save the subsequent data loaded into the form into the database.

<span id="site/models/updhelloworld.php">
''site/models/updhelloworld.php''
<source lang="php">
<?php
// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// Include dependancy of the main model form
jimport('joomla.application.component.modelform');
// import Joomla modelitem library
jimport('joomla.application.component.modelitem');
// Include dependancy of the dispatcher
jimport('joomla.event.dispatcher');

/**
* UpdHelloWorld Model
*/
class HelloWorldModelUpdHelloWorld extends JModelForm
{
/**
* @var object item
*/
protected $item;

/**
* Get the data for a new qualification
*/
public function getForm($data = array(), $loadData = true)
{

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

// Get the form.
$form = $this->loadForm('com_helloworld.updhelloworld', 'updhelloworld', array('control' => 'jform', 'load_data' => true));
if (empty($form)) {
return false;
}
return $form;

}

/**
* Get the message
* @return object The message to be displayed to the user
*/
function &getItem()
{

if (!isset($this->_item))
{
$cache = JFactory::getCache('com_helloworld', '');
$id = $this->getState('helloworld.id');
$this->_item = $cache->get($id);
if ($this->_item === false) {

}
}
return $this->_item;

}

public function updItem($data)
{
// set the variables from the passed data
$id = $data['id'];
$greeting = $data['greeting'];

// set the data into a query to update the record
$db = $this->getDbo();
$query = $db->getQuery(true);
$query->clear();
$query->update(' #__helloworld ');
$query->set(' greeting = '.$db->Quote($greeting) );
$query->where(' id = ' . (int) $id );

$db->setQuery((string)$query);

if (!$db->query()) {
JError::raiseError(500, $db->getErrorMsg());
return false;
} else {
return true;
}
}
}

</source>
</span>

The following file ''updhelloworld.xml'' should be created using your favourite editor and saved in the forms folder under the models directory. The first of the fields being referenced id using the sql type so that I returns the results from the query into a dropdown list form to be selected.
<span id="site/models/forms/updhelloworld.xml">
''site/models/forms/updhelloworld.xml''
<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>
<form name="updhelloworld">
<fieldset name="updhelloworld">

<field
name="id"
type="sql"
multiple="false"
size="1"
label="COM_HELLOWORLD_FORM_LBL_UPDHELLOWORLD_ID"
description="COM_HELLOWORLD_FORM_DESC_UPDHELLOWORLD_ID"
query="select id, greeting from #__helloworld"
key_field="id"
value_field="greeting"
default="0"
required="true"
>
<option value="">JOPTION_SELECT_ID</option>
</field>

<field
name="greeting"
type="text"
description="COM_HELLOWORLD_FORM_DESC_UPDHELLOWORLD_GREETING"
label="COM_HELLOWORLD_FORM_LBL_UPDHELLOWORLD_GREETING"
required="true"
size="50" />

</fieldset>
</form>

</source>
</span>

== Adding some language keys ==

This file provides the text link between the label in the model form definition to be displayed in the view. And being for the frontend, it resides in the site folder.

<span id="site/language/en-GB/en-GB.com_helloworld.ini">
''site/language/en-GB/en-GB.com_helloworld.ini''
<source lang="ini">
COM_HELLOWORLD_FORM_LBL_UPDHELLOWORLD_ID="Greeting ID"
COM_HELLOWORLD_FORM_DESC_UPDHELLOWORLD_ID="This is the ID of the Greeting record"
COM_HELLOWORLD_FORM_LBL_UPDHELLOWORLD_GREETING="Greeting"
COM_HELLOWORLD_FORM_DESC_UPDHELLOWORLD_GREETING="Greeting description"
JOPTION_SELECT_ID=" -- Select Greeting to Update -- "
</source>
</span>

Add the last 2 lines to the ''admin/language/en-GB/en-GB.com_helloworld.sys.ini'' file to provide the text link for the menu type display. And being for the backend, it resides in the admin language folder.

<span id="admin/language/en-GB/en-GB.com_helloworld.sys.ini">
''admin/language/en-GB/en-GB.com_helloworld.sys.ini''
<source lang="ini">
COM_HELLOWORLD="Hello World!"
COM_HELLOWORLD_DESCRIPTION="This is the Hello World description"
COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_DESC="This view displays a selected message"
COM_HELLOWORLD_HELLOWORLD_VIEW_DEFAULT_TITLE="Hello World"
COM_HELLOWORLD_INSTALL_TEXT="HelloWorld Install script"
COM_HELLOWORLD_MENU="Hello World!"
COM_HELLOWORLD_POSTFLIGHT_DISCOVER_INSTALL_TEXT="HelloWorld postlight discover install script"
COM_HELLOWORLD_POSTFLIGHT_INSTALL_TEXT="HelloWorld postflight install script"
COM_HELLOWORLD_POSTFLIGHT_UNINSTALL_TEXT="HelloWorld postflight uninstall script"
COM_HELLOWORLD_POSTFLIGHT_UPDATE_TEXT="HelloWorld postflight update script"
COM_HELLOWORLD_PREFLIGHT_DISCOVER_INSTALL_TEXT="HelloWorld preflight discover install script"
COM_HELLOWORLD_PREFLIGHT_INSTALL_TEXT="HelloWorld preflight install script"
COM_HELLOWORLD_PREFLIGHT_UNINSTALL_TEXT="HelloWorld preflight uninstall script"
COM_HELLOWORLD_PREFLIGHT_UPDATE_TEXT="HelloWorld preflight update script"
COM_HELLOWORLD_UNINSTALL_TEXT="HelloWorld Uninstall script"
COM_HELLOWORLD_UPDATE_TEXT="HelloWorld Update script"
COM_HELLOWORLD_UPDHELLOWORLD_VIEW_DEFAULT_TITLE="Update the Greeting"
COM_HELLOWORLD_UPDHELLOWORLD_VIEW_DEFAULT_DESC="Update greeting here"
</source>
</span>

The ''_populateState'' method is, by default, automatically called when a state is read by the ''getState'' method.

== Packaging the component ==

Content of your code directory-
* ''[[#helloworld.xml|helloworld.xml]]''
* ''[[#script.php|script.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_02#site/helloworld.php|site/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_02#site/controller.php|site/controller.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/controllers/updhelloworld.php|site/controllers/updhelloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/controllers/index.html|site/controllers/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/views/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/views/helloworld/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#site/views/helloworld/view.html.php|site/views/helloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/views/updhelloworld/view.html.php|site/views/updhelloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/views/helloworld/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/views/updhelloworld/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_06#site/views/helloworld/tmpl/default.xml|site/views/helloworld/tmpl/default.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#site/views/helloworld/tmpl/default.php|site/views/helloworld/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/views/updhelloworld/tmpl/default.xml|site/views/updhelloworld/tmpl/default.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/views/updhelloworld/tmpl/default.php|site/views/updhelloworld/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/models/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#site/models/helloworld.php|site/models/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/models/updhelloworld.php|site/models/updhelloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_18#site/models/forms/updhelloworld.xml|site/models/forms/updhelloworld.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/models/forms/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/language/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|site/language/en-GB/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_08#site/language/en-GB/en-GB.com_helloworld.ini|site/language/en-GB/en-GB.com_helloworld.ini]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/access.xml|admin/access.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/config.xml|admin/config.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/helloworld.php|admin/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_12#admin/controller.php|admin/controller.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/sql/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/sql/install.mysql.utf8.sql|admin/sql/install.mysql.utf8.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_06#admin/sql/uninstall.mysql.utf8.sql|admin/sql/uninstall.mysql.utf8.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/sql/updates/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/sql/updates/mysql/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#admin/sql/updates/mysql/0.0.1.sql|admin/sql/updates/mysql/0.0.1.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_06#admin/sql/install.mysql.utf8.sql|admin/sql/updates/mysql/0.0.6.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_12#admin/sql/updates/mysql/0.0.12.sql|admin/sql/updates/mysql/0.0.12.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/sql/updates/mysql/0.0.13.sql|admin/sql/updates/mysql/0.0.13.sql]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/models/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/models/fields/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_12#admin/models/fields/helloworld.php|admin/models/fields/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/models/forms/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/models/forms/helloworld.xml|admin/models/forms/helloworld.xml]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/models/forms/helloworld.js|admin/models/forms/helloworld.js]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/models/rules/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/models/rules/greeting.php|admin/models/rules/greeting.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/models/helloworld.php|admin/models/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_09#admin/models/helloworlds.php|admin/models/helloworlds.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/helloworlds/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/views/helloworlds/view.html.php|admin/views/helloworlds/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/helloworlds/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/views/helloworlds/tmpl/default.php|admin/views/helloworlds/tmpl/default.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_07#admin/views/helloworlds/tmpl/default_head.php|admin/views/helloworlds/tmpl/default_head.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_07#admin/views/helloworlds/tmpl/default_body.php|admin/views/helloworlds/tmpl/default_body.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_07#admin/views/helloworlds/tmpl/default_foot.php|admin/views/helloworlds/tmpl/default_foot.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/helloworld/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/views/helloworld/view.html.php|admin/views/helloworld/view.html.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/views/helloworld/submitbutton.js|admin/views/helloworld/submitbutton.js]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/views/helloworld/tmpl/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/views/helloworld/tmpl/edit.php|admin/views/helloworld/tmpl/edit.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/helpers/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/helpers/helloworld.php|admin/helpers/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/tables/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_14#admin/tables/helloworld.php|admin/tables/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_13#admin/language/en-GB/en-GB.com_helloworld.ini|admin/language/en-GB/en-GB.com_helloworld.ini]]''
* ''[[#admin/language/en-GB/en-GB.com_helloworld.sys.ini|admin/language/en-GB/en-GB.com_helloworld.sys.ini]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|admin/controllers/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/controllers/helloworld.php|admin/controllers/helloworld.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_11#admin/controllers/helloworlds.php|admin/controllers/helloworlds.php]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_08#language/en-GB/en-GB.ini|language/en-GB/en-GB.ini]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|media/index.html]]''
* ''[[Developing_a_Model-View-Controller_(MVC)_Component_for_Joomla!2.5_-_Part_01#index.html|media/images/index.html]]''
* ''media/images/tux-16x16.png''
* ''media/images/tux-48x48.png''

Create a compressed file of this directory or directly download the [http://joomlacode.org/gf/download/frsrelease/11394/58397/com_helloworld-1.6-part07.zip archive] and install it using the extension manager of Joomla. You can add a menu item of this component using the menu manager in the backend.

<span id="helloworld.xml">
''helloworld.xml''
<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension type="component" version="2.5.0" method="upgrade">

<name>COM_HELLOWORLD</name>

<creationDate>November 2009</creationDate>
<author>John Doe</author>
<authorEmail>john.doe@example.org</authorEmail>
<authorUrl>http://www.example.org</authorUrl>
<copyright>Copyright Info</copyright>
<license>License Info</license>

<version>0.0.18</version>

<description>COM_HELLOWORLD_DESCRIPTION</description>


<scriptfile>script.php</scriptfile>

<install> 
<sql>
<file driver="mysql" charset="utf8">sql/install.mysql.utf8.sql</file>
</sql>
</install>
<uninstall> 
<sql>
<file driver="mysql" charset="utf8">sql/uninstall.mysql.utf8.sql</file>
</sql>
</uninstall>
<update> 
<schemas>
<schemapath type="mysql">sql/updates/mysql</schemapath>
</schemas>
</update>



<files folder="site">
<filename>index.html</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>
<folder>views</folder>
<folder>models</folder>
<folder>controllers</folder>
<folder>language</folder>
</files>

<media destination="com_helloworld" folder="media">
<filename>index.html</filename>
<folder>images</folder>
</media>

<administration>

<menu img="../media/com_helloworld/images/tux-16x16.png">COM_HELLOWORLD_MENU</menu>


<files folder="admin">

<filename>index.html</filename>
<filename>config.xml</filename>
<filename>access.xml</filename>
<filename>helloworld.php</filename>
<filename>controller.php</filename>

<folder>sql</folder>

<folder>tables</folder>

<folder>models</folder>

<folder>views</folder>

<folder>controllers</folder>

<folder>helpers</folder>
</files>

<languages folder="admin">
<language tag="en-GB">language/en-GB/en-GB.com_helloworld.ini</language>
<language tag="en-GB">language/en-GB/en-GB.com_helloworld.sys.ini</language>
</languages>
</administration>


<updateservers>

<server type="extension" priority="1" name="HelloWorld Update Site">http://yourdomain.com/update/helloworld-update.xml</server>
</updateservers>

</extension>

</source>
</span>

Now you can see in your component '''hello-world''' an array with two colums, two rows and checkboxes. You can click the checkboxes in order to select the different options you want.

== Navigate ==

[[Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Part 17|Prev: Adding an update server]]
[[Developing a Model-View-Controller (MVC) Component for Joomla!2.5 - Part 19|Next: Example of Menu Parameters & Stylesheets]]

[[Category:Development]]
[[Category:Joomla! 1.6]]
[[Category:Joomla! 1.7]]
[[Category:Joomla! 2.5]]

Release and support cycle

2012-10-09T20:37:54Z

Mvangeest: Corrected mistake, adjusted layout, added examples

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:
:<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: standard support (STS) and long term support (LTS). Every '''third''' release will be assigned long term support.

*'''STS (standard support)''' releases are supported for '''seven months'''. Their support ends one month after the next release of Joomla is released.
*'''LTS (long term support)''' releases are supported for '''twenty-one 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. One more STS release follows (usually compatible with the first STS release), and the release cycle is finished by the release of an LTS release which finalizes of the work of the two STS releases. The three releases in one cycle will usually be numbered <tt>[major].0</tt> and <tt>[major].1</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 and 3.1.

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].1</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]]

Developers/Projects

2012-09-02T16:40:49Z

Mvangeest: Adapted the suggested titles to the continuous tense used in most tutorial titles

== Suggested topics ==
This is a short list of articles that might be written to support developers. Please feel free to add further topic ideas.

* [[Adding configuration objects to modules and plugins]].
* [[Storing data in the session between page loads]].
* [[Suppressing output of extra HTML]].
* [[Using the filter package]].
*: Describe how and when to use the Filter package and explain what needs to be filtered for various situations (for queries, for URLs, etc)
* [[Using the registry package]]
* [[Using JSimpleXML]].
*: How to load and store XML files and how to work with them
* [[Creating component feeds]] (RSS/ATOM)
* [[Generating paths for client side and server side]]
* [[Acessing information from the request]]
*: This focuses on using the JBrowser class to retrieve information about the features available in the user's browser.
* [[Creating an editor plugin]]
* [[What can be done with a user plugin]]
* [[Working with parameters]]
* [[Cloaking email addresses]]
* [[Using the caching system in your component]]. This might be enough (for now?) -> [[Cache]]
* [[Extending Joomla's MVC Architecture]]<noinclude>[[Category:Landing subpages|{{PAGENAME}}]]</noinclude>

User:MarkRS/cascading cheat sheets/components/preamble

2012-08-27T20:22:56Z

Mvangeest: Changed absolute link into relative link

{{inprogressbyuser}}

Let the Frame(work) Take The Strain {{JVer|2.5}}

Cascading cheat-sheets for the expert beginner.

= Component? =

Components deliver main areas of functionality, for example an event diary (there are many available as extensions), or the core functions of user management and displaying articles.

You'll find the code for components in the directories

<tt><site root>/components</tt>

<tt><site root>/administration/components</tt>

The first one is for for front end functionality, the second for back end (administration) functionality. The code for each component is in a subdirectory of one of these named <tt>com_<component name></tt>. Components, by definition, need functionality in both areas.

You should be able to find the, for example, content component ("com_content"), which is for displaying articles, the user component ("com_user"), which is for for managing website accounts, and several others.

This naming is one of those Joomla principles. You probably can hack it so that you can name a component directory “freds_diner”, but a whole load of defaults just won't work and you'll be fighting every step of the way.

= Component Internals =

== Getting started ==

We're going to zoom through the actions occurring from a website URL appearing to the beginning of a component running. We're going to start in the only possible place, the middle. It's going to look a little slow, but only for a very short while, and I think you'll find this will explain many of the Joomla idioms which will make your overall learning curve much quicker. Let's imagine we are looking at a component that allows website users to answer a questionnaire that is presented to them, stores their answers, and allows an administrator to look at their answers. To keep it nice and simple, we'll imagine our administrator has too much time on his hands and hard codes a new questionnaire into the front end every day.

Here's the process of events for the user

By selecting our questionnaire component, let's imagine that a URL like this

<yoursite>/questionnaire

is generated. Whilst this is not something that Joomla can directly work with, this is quite possibly the way it'll be. It could be the case if you had, for example, a SEF module enabled.

== Everything goes through index.php ==

This is the first step of every Joomla page. There are two different versions of index.php, one for the back end and a separate one for the front end. You'll find the front end file in the site root.

Have a look in this file and you'll see the first two active lines are

<source lang="php" highlight="33">
define('_JEXEC', 1);
define('DS', DIRECTORY_SEPARATOR);
</source>

The first line defines a constant called _JEXEC and gives it the value “1”. The value is pretty irrelevant but its simple existence is part of the system security. You'll see that many Joomla code files start with a check for this (or some other) constant, exiting immediately if it's not found. This helps prevent miscreants from going directly to internal parts of the system.

The second line is about to disappear in Joomla 3.0, since php handles converting “/” to the requirements of the platform you're actually running on. My advice is don't use DS, it's just BS these days.

The next three blocks are dull, simply loading defines files that are required for the core running. Even the line after doesn't really concern us yet, just setting a marker point used during debugging.

The line after that,
<source lang="php" highlight="33">
$app = JFactory::getApplication('site');
</source>

might look fairly dull, but it creates the application object that contains the top level scaffolding that defines Joomla. You start to get a sense of this with the next line

<source lang="php" highlight="33">
$app->initialise();
</source>
which, it's easy to guess, will set up a whole bunch of things to prepare Joomla for the job at hand.

== I know “factory”, but how does “JFactory” work? ==

Let's take a quick sidestep that helps make this very common Joomla style clearer.
Just taking the case above, as an OOP-aware developer you're familiar with the idea of an object factory, that thing that allows OOP people to tell themselves that they're not using global objects. But what about the “J”?

When you see stuff like this in the code, and there's a lot of it (JFactory, JForm, JText, and on and on), Joomla goes to the directory

<tt><site root>/libraries/joomla</tt>

to look for something with that name (without the “J”). So, for example there is a file

<tt><site root>/libraries/joomla/factory.php</tt>

that contains a class called JFactory, and, surprise surprise, it has a method named “getApplication”. This is a very standard way of Joomla calling core functionality. Some functionality is more detailed and so gets a whole directory in that location. For example the call

<source lang="php" highlight="33">
JUser::getInstance()
</source>

finds a file <tt><site root>/libraries/joomla/user/user.php</tt>. That file contains the definition of a class JUser, and you won't be shocked to find that it contains a method "getInstance".

Any call that looks like “J<Something>::function” will be using this mechanism. Now you know where to go when you need to know what a function like this does and the only answer you can get from the Joomla cognescenti is “read the code”! It's the same location for back end code as well as front end.

== And now, back to the records... ==

After another profiler call that I'm not going to talk about either, we come to the line

<source lang="php" highlight="33">
$app->route();
</source>

You remember I said that Joomla couldn't directly work with that URL we started with? The "route" method "decodes" the URL into something that Joomla can process. If we'd started with the URL

<your site>/index.php?option=com_questions

this "decoding" would have been at its simplest. Anything else will get converted back to this type of format, which is what the rest of the internals of the framework actually work with.

That all just brings us to the point where we can actually start doing something. You'll have realised that the line

<source lang="php" highlight="33">
$app->dispatch();
</source>

means that the application class (which, of course, is defined in the file <tt><site root>/libraries/joomla/application/application.php</tt>), that our factory class created for us initially, has a method “dispatch”. This method does a little bit of setting up and then starts the heavy lifting with the component. Having a brief look through that code, it's mostly easy to see this happening. But no, wait! Clearly the critical line doing this is

<source lang="php" highlight="33">
$contents = JComponentHelper::renderComponent($component);
</source>

but not only did we not pass in a value for $component to this method, but there's no file <tt><site root>/libraries/joomla/componenthelper</tt>

Well, no, that seems to be more of the internal wiring that does so much for you, you want to look in

<tt><site root>/libraries/joomla/application/component</tt>

where you'll find the file you want, “helper.php”.

And, when the framework doesn't find a component name stored in that variable, the dispatch method finds the component to load from the data that was stored during the "route" method. And, in case, like me, you're confused by this use of words; the not-so-obvious piece of information is that "renderComponent" is not the same as "render". The first one generates the output from a specific component. The second one takes that component output and fits it into the overall page that your user sees on screen.

So now we have arrived at the point that the component can start to do its work. The dispatcher has brought us there. Time to look at the details of component design!

I'm going to start developing an example of a simple component that looks after a little bit of data, shows it to some people and allows some people to edit it. In short, a "hello world" program for people who actually want to do something.

Follow along at [[{{#titleparts:{{FULLPAGENAME}}|-1}}/overview|Component Overview]].

[[Category:Development]]
[[Category:Tutorials]]
[[Category:Joomla! 2.5]]

User:MarkRS/cascading cheat sheets/components/overview

2012-08-27T20:22:21Z

Mvangeest: Changed absolute link into relative link

{{inprogressbyuser}}
= Component Overview =

Let the Frame(work) Take The Strain
{{JVer|2.5}}

Cascading cheat sheets for the expert beginner.

The previous article in this series was [[{{#titleparts:{{FULLPAGENAME}}|-1}}/preamble|Component Preamble]]

== Ready... ==

The framework has set the scene, it's ready and waiting to swing into action for you, you've just got to string the right sequences together.

== Steady... ==

To start your component Joomla looks for a file

<tt><site root>/components/com_<component-name>/<component name>.php</tt>

This is where your component takes over.
In the simplest case, Joomla already has the rigging to do most of what you want.

Your file can be as simple, and standard, as

<span id="questions.php">
'''<tt><site root>/components/com_questions/questions.php</tt>'''
<source lang="php" highlight="18">

// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import joomla controller library
jimport('joomla.application.component.controller');

// Get an instance of the controller prefixed by the component name
$controller = JController::getInstance('questions');

// Perform the Request task
$controller->execute(JRequest::getCmd('task'));

// Redirect if set by the controller
$controller->redirect();
</source></span>

The base controller class (from the third line above. You know where to find that if you've been following this series) just looks for a file called “controller.php” in the component main directory. Just to be clear, in this case that means that the controller file is

<tt><site root>/components/com_questions/controller.php</tt>

Provided that is an instance of a controller class called QuestionsController then everything will be set for the next phase.

Of course, at the moment the URL doesn't contain "task=<something>" for the command JRequest::getCmd('task') to find, so the default setting is to display the first view of the component. What's the first view? Of course you'd guess (correctly) that the default view is "questions", nice and simple.

== Go... ==

Well, almost go.

In fact, certainly for the front end, it may well be that you don't need to add anything at all to the existing controller class except a name of your own. Your controller class could be as simple as

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

jimport('joomla.application.component.controller');

class QuestionsController extends JController

{
}
</source>
Just an empty class definition to establish our own component controller class, but not adding anything to the base class.

Even so, there's already a bit of Joomla idiom and scaffolding going on. Clearly the class that we're subclassing here is Jcontroller, but the less obvious part is that the name of our controller class is quite important, get it right and the framework will make all sorts of correct guesses for us. The class naming convention that gives you all this extra magic is

{component name}{type name}{element name}

Our component name, without its "com_" prefix, is questions. This class is a controller and, because it's such an easy (or perhaps “simple”) thing, there's no element name in this case. By convention Joomla class names are in camel case. Php ignores case in class names. Beware, it does not do the same thing to filesystem names, the simple rule is camel-case class (&tc) names, lowercase file and directory names. No, you don't have to, but do yourself a favour and do do.

The check for _JEXEC is a really good idea for the top of every file, and the import line is fairly obvious, why use dots instead of slashes? I don't know, but it's easy to put two and two together from our previous discussion of “Jfactory” and come up with the correct supposition that jimport(some.dotted.path) imports a file <site root>/libraries/some/dotted/path.php into the current file.

== Really Go ==

From here, the controller loads your first view, which probably gets some data out of your model, for your user to interact with.

The simplest way this happens is that you just let the controller set up its defaults so that it loads you initial view file. If you just let it do this it will assume you want a view called “questions” (it got this from the first part of its own name, “QuestionsController”, see, I told you it was a good idea).

== A view? How does that work? ==

Like this. In short the framework tries to load a view class file, which pulls in the data it needs to show and displays it using a layout file. Easy. Of course, the framework will make a whole load of assumptions for you about how to pull that all together. If you don't give it any further clues or directives, the assumptions it makes are as follows.

It looks for the view definition file

<site root>/components/com_questions/views/questions/view.html.php

From what you know already you'd be quite happy with all of that. If you guessed that the “html” in the middle of the filename means this file is the default for a normal webpage view and you could have all sorts of different files with things like “pdf” or “rss” in the names to make different types of output, then you'd really be ahead of the game!

Anyway, let's stick with html for the moment. The bare bones of the file look like this

<source lang="php" highlight="33">
jimport('joomla.application.component.view');

/**
* HTML View class for the Questions Component front screen
*/

class QuestionsViewQuestions extends JView
{

function display($tpl = null)
{
$this->questions = $this->get('Items');

// Display the view
parent::display($tpl);
}
}
</source>
JView is the base view class, and we've given our subclass of it a name matching the template I gave you above {component}{type}{element}, nice and consistent.

We load our questions and display them. Very little for us to do, with Joomla's little legs flailing along like crazy under the surface, just the way it ought to be!

The view's "get" function is a highly flexible piece of code, "getting" all manner of things. In this instance though what it's doing is getting data out of the data model, using what might appear a long winded route. However, by carefully picking the places to intervene in this pathway, Joomla does the grubby work of loading our data and we can just do the fun bit!

== Load our questions? That sounds like data! Is that the “model” bit? ==

Yup, here comes the first part of the "model" interaction.

The view already has enough information to find the corresponding data model, if you handled your naming conventions correctly!
From the name of this view, the framework will look for a file

<source lang="php" highlight="33">
<site root>/components/com_questions/models/questions.php
</source>

Although this is very easy to follow, there are a lot very specific things going on here.
I have very carefully called this view "questions", plural. This is because we are going to show the user a list of questions. I could have called it "questionnaire", but that's a singular thing, and Joomla is set up not only to distinguish between singular things (ie one row from a table) and multiple things (ie a list containing several rows from a table!), but also to guess the singular name from the plural name. I'm fairly sure it can guess "question" from "questions", but I don't think it would get there from "questionnaire". But we're getting ahead of ourselves.

In order to make our display easy, ie get Joomla to do most of the work for us, we'll define our "questions" class like this.

<span id="site root/components/com_questions/models/questions.php">
'''<tt><site root>/components/com_questions/models/questions.php</tt>'''
<source lang="php" highlight="31">
jimport('joomla.application.component.modellist');

/**
* Questions list Model ie a questionnaire
*/
class QuestionsModelQuestions extends JModelList
{
protected function getListQuery()
{
$db = $this->getDbo();
$query = $db->getQuery(true);

// Select the required fields from the table.
$query->select('*');
$query->from('#__questions_questions');

$query->where('questionnaire_id=1');

return $query;
}
}
</source></span>

Looks simple, but again, take notice of the little details and suddenly a lot more becomes clear.
We're extending a class called "JModelList", a class that's specifically set up for handling result sets of multiple rows. You'll be pleased, and unsurprised, to know there's a JModel class for single row result types, two of them in fact, but you'll probably be able to guess a lot about them from seeing this one.

So what's going on here? This is the only part of a chain of actions that we need to concern ourselves with in this simple instance. This method just defines the query object that the framework needs to select the precise pieces of data we want to see. You can guess that we've set up a "questions" table that has a field which groups questions into individual questionnaires. I've cheated here, let's pretend our fictitious admin with too much time on his hands puts these rows into the table manually, and changes this class every day. On other days he may select a different questionnaire number, just so we don't have to worry about how to pick one!

A protected function? Yes, it's internal to the chain of actions already in place to give us the list of questions in questionnaire "1" ready to display, and all we had to do was write one little query. How easy is that!

[[Category:Development]]
[[Category:Tutorials]]
[[Category:Joomla! 2.5]]

User:MarkRS/cascading cheat sheets/components/overview

2012-08-27T20:09:32Z

Mvangeest: Undo revision 71903: not in line with the intention

{{inprogressbyuser}}
= Component Overview =

Let the Frame(work) Take The Strain
{{JVer|2.5}}

Cascading cheat sheets for the expert beginner.

The previous article in this series was [[User:MarkRS/cascading_cheat_sheets/components/preamble|Component Preamble]]

== Ready... ==

The framework has set the scene, it's ready and waiting to swing into action for you, you've just got to string the right sequences together.

== Steady... ==

To start your component Joomla looks for a file

<tt><site root>/components/com_<component-name>/<component name>.php</tt>

This is where your component takes over.
In the simplest case, Joomla already has the rigging to do most of what you want.

Your file can be as simple, and standard, as

<span id="questions.php">
'''<tt><site root>/components/com_questions/questions.php</tt>'''
<source lang="php" highlight="18">

// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import joomla controller library
jimport('joomla.application.component.controller');

// Get an instance of the controller prefixed by the component name
$controller = JController::getInstance('questions');

// Perform the Request task
$controller->execute(JRequest::getCmd('task'));

// Redirect if set by the controller
$controller->redirect();
</source></span>

The base controller class (from the third line above. You know where to find that if you've been following this series) just looks for a file called “controller.php” in the component main directory. Just to be clear, in this case that means that the controller file is

<tt><site root>/components/com_questions/controller.php</tt>

Provided that is an instance of a controller class called QuestionsController then everything will be set for the next phase.

Of course, at the moment the URL doesn't contain "task=<something>" for the command JRequest::getCmd('task') to find, so the default setting is to display the first view of the component. What's the first view? Of course you'd guess (correctly) that the default view is "questions", nice and simple.

== Go... ==

Well, almost go.

In fact, certainly for the front end, it may well be that you don't need to add anything at all to the existing controller class except a name of your own. Your controller class could be as simple as

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

jimport('joomla.application.component.controller');

class QuestionsController extends JController

{
}
</source>
Just an empty class definition to establish our own component controller class, but not adding anything to the base class.

Even so, there's already a bit of Joomla idiom and scaffolding going on. Clearly the class that we're subclassing here is Jcontroller, but the less obvious part is that the name of our controller class is quite important, get it right and the framework will make all sorts of correct guesses for us. The class naming convention that gives you all this extra magic is

{component name}{type name}{element name}

Our component name, without its "com_" prefix, is questions. This class is a controller and, because it's such an easy (or perhaps “simple”) thing, there's no element name in this case. By convention Joomla class names are in camel case. Php ignores case in class names. Beware, it does not do the same thing to filesystem names, the simple rule is camel-case class (&tc) names, lowercase file and directory names. No, you don't have to, but do yourself a favour and do do.

The check for _JEXEC is a really good idea for the top of every file, and the import line is fairly obvious, why use dots instead of slashes? I don't know, but it's easy to put two and two together from our previous discussion of “Jfactory” and come up with the correct supposition that jimport(some.dotted.path) imports a file <site root>/libraries/some/dotted/path.php into the current file.

== Really Go ==

From here, the controller loads your first view, which probably gets some data out of your model, for your user to interact with.

The simplest way this happens is that you just let the controller set up its defaults so that it loads you initial view file. If you just let it do this it will assume you want a view called “questions” (it got this from the first part of its own name, “QuestionsController”, see, I told you it was a good idea).

== A view? How does that work? ==

Like this. In short the framework tries to load a view class file, which pulls in the data it needs to show and displays it using a layout file. Easy. Of course, the framework will make a whole load of assumptions for you about how to pull that all together. If you don't give it any further clues or directives, the assumptions it makes are as follows.

It looks for the view definition file

<site root>/components/com_questions/views/questions/view.html.php

From what you know already you'd be quite happy with all of that. If you guessed that the “html” in the middle of the filename means this file is the default for a normal webpage view and you could have all sorts of different files with things like “pdf” or “rss” in the names to make different types of output, then you'd really be ahead of the game!

Anyway, let's stick with html for the moment. The bare bones of the file look like this

<source lang="php" highlight="33">
jimport('joomla.application.component.view');

/**
* HTML View class for the Questions Component front screen
*/

class QuestionsViewQuestions extends JView
{

function display($tpl = null)
{
$this->questions = $this->get('Items');

// Display the view
parent::display($tpl);
}
}
</source>
JView is the base view class, and we've given our subclass of it a name matching the template I gave you above {component}{type}{element}, nice and consistent.

We load our questions and display them. Very little for us to do, with Joomla's little legs flailing along like crazy under the surface, just the way it ought to be!

The view's "get" function is a highly flexible piece of code, "getting" all manner of things. In this instance though what it's doing is getting data out of the data model, using what might appear a long winded route. However, by carefully picking the places to intervene in this pathway, Joomla does the grubby work of loading our data and we can just do the fun bit!

== Load our questions? That sounds like data! Is that the “model” bit? ==

Yup, here comes the first part of the "model" interaction.

The view already has enough information to find the corresponding data model, if you handled your naming conventions correctly!
From the name of this view, the framework will look for a file

<source lang="php" highlight="33">
<site root>/components/com_questions/models/questions.php
</source>

Although this is very easy to follow, there are a lot very specific things going on here.
I have very carefully called this view "questions", plural. This is because we are going to show the user a list of questions. I could have called it "questionnaire", but that's a singular thing, and Joomla is set up not only to distinguish between singular things (ie one row from a table) and multiple things (ie a list containing several rows from a table!), but also to guess the singular name from the plural name. I'm fairly sure it can guess "question" from "questions", but I don't think it would get there from "questionnaire". But we're getting ahead of ourselves.

In order to make our display easy, ie get Joomla to do most of the work for us, we'll define our "questions" class like this.

<span id="site root/components/com_questions/models/questions.php">
'''<tt><site root>/components/com_questions/models/questions.php</tt>'''
<source lang="php" highlight="31">
jimport('joomla.application.component.modellist');

/**
* Questions list Model ie a questionnaire
*/
class QuestionsModelQuestions extends JModelList
{
protected function getListQuery()
{
$db = $this->getDbo();
$query = $db->getQuery(true);

// Select the required fields from the table.
$query->select('*');
$query->from('#__questions_questions');

$query->where('questionnaire_id=1');

return $query;
}
}
</source></span>

Looks simple, but again, take notice of the little details and suddenly a lot more becomes clear.
We're extending a class called "JModelList", a class that's specifically set up for handling result sets of multiple rows. You'll be pleased, and unsurprised, to know there's a JModel class for single row result types, two of them in fact, but you'll probably be able to guess a lot about them from seeing this one.

So what's going on here? This is the only part of a chain of actions that we need to concern ourselves with in this simple instance. This method just defines the query object that the framework needs to select the precise pieces of data we want to see. You can guess that we've set up a "questions" table that has a field which groups questions into individual questionnaires. I've cheated here, let's pretend our fictitious admin with too much time on his hands puts these rows into the table manually, and changes this class every day. On other days he may select a different questionnaire number, just so we don't have to worry about how to pick one!

A protected function? Yes, it's internal to the chain of actions already in place to give us the list of questions in questionnaire "1" ready to display, and all we had to do was write one little query. How easy is that!

[[Category:Development]]
[[Category:Tutorials]]
[[Category:Joomla! 2.5]]

User:MarkRS/cascading cheat sheets/components/overview

2012-08-26T23:06:19Z

Mvangeest: Added information

{{inprogressbyuser}}
= Component Overview =

Let the Frame(work) Take The Strain
{{JVer|2.5}}

Cascading cheat sheets for the expert beginner.

The previous article in this series was [[User:MarkRS/cascading_cheat_sheets/components/preamble|Component Preamble]]

== Ready... ==

The framework has set the scene, it's ready and waiting to swing into action for you, you've just got to string the right sequences together.

== Steady... ==

To start your component Joomla looks for a file

<tt><site root>/components/com_<component-name>/<component name>.php</tt>

This is where your component takes over. Joomla places no restrictions on what you do from this point. You could decide to put all the code of the entire component into this file. However, you would probably like to avoid making an unmaintainable mess of your component, and take advantage of more of Joomla's built-in capabilities. To do this, you need to use the [[Model-View-Controller]] (MVC) pattern.

In Joomla's MVC implementation, a component has a base controller and can have any number of subcontrollers. Therefore the first step in using it to is to find and activate the controller you need. There is a simple and standard way to do this:

<span id="questions.php">
'''<tt><site root>/components/com_questions/questions.php</tt>'''
<source lang="php" highlight="18">

// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import joomla controller library
jimport('joomla.application.component.controller');

// Get an instance of the controller prefixed by the component name
$controller = JController::getInstance('questions');

// Perform the Request task
$controller->execute(JRequest::getCmd('task'));

// Redirect if set by the controller
$controller->redirect();
</source></span>

The getInstance method in the <code>JController</code> class (on the third line above. You know where to find that if you've been following this series) is a factory method that will create the right type of controller based on the value of the <code>task</code> URL parameter (<tt>index.php?option=com_questions&task=<something></tt>).

Of course, at the moment the URL doesn't contain "task=<something>" for the command <code>JRequest::getCmd('task')</code> to find, so the default is to look for the base controller in a file called “controller.php” in the component main directory. Just to be clear, in this case that means that the controller file is

<tt><site root>/components/com_questions/controller.php</tt>.

== Go... ==

Well, almost go.

In fact, certainly for the front end, it may well be that you don't need to add anything at all to the existing controller class except a name of your own. Your controller class could be as simple as

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

jimport('joomla.application.component.controller');

class QuestionsController extends JController

{
}
</source>
Just an empty class definition to establish our own component controller class, but not adding anything to the base class.

Even so, there's already a bit of Joomla idiom and scaffolding going on. Clearly the class that we're subclassing here is JController, but the less obvious part is that the name of our controller class is quite important, get it right and the framework will make all sorts of correct guesses for us. The class naming convention that gives you all this extra magic is

<code>{component name}{type name}{element name}</code>

Our component name, without its "com_" prefix, is questions. This class is a controller and, because it's such an easy (or perhaps “simple”) thing, there's no element name in this case. By convention Joomla class names are in camel case. PHP ignores case in class names. Beware, it does not do the same thing to filesystem names, the simple rule is camel-case class (&tc) names, lowercase file and directory names. No, you don't have to, but do yourself a favour and do do.

The check for _JEXEC is a really good idea for the top of every file, and the import line is fairly obvious, why use dots instead of slashes? I don't know, but it's easy to put two and two together from our previous discussion of “JFactory” and come up with the correct supposition that jimport(some.dotted.path) imports a file <site root>/libraries/some/dotted/path.php into the current file.

== Really Go ==

The "starter code" in your index.php will now have created an instance of the <code>QuestionsController</code> and the <code>execute</code> method is being processed. Because the <code>task</code> URL parameter is empty, it will determine that a subcontroller is not needed. It also means that no task has been specified, so the default method of the base controller will be executed: the <code>display</code> method. Since we haven't overridden that method, it will behave like it normally does: it will display the first view of the component. What's the first view? Of course you'd guess (correctly) that the default view is "questions", nice and simple.

The simplest way this happens is that you just let the controller set up its defaults so that it loads you initial view file. If you just let it do this it will assume you want a view called “questions” (it got this from the first part of its own name, “QuestionsController”, see, I told you it was a good idea).

== A view? How does that work? ==

Like this. In short the framework tries to load a view class file, which pulls in the data it needs to show and displays it using a layout file. Easy. Of course, the framework will make a whole load of assumptions for you about how to pull that all together. If you don't give it any further clues or directives, the assumptions it makes are as follows.

It looks for the view definition file

<site root>/components/com_questions/views/questions/view.html.php

From what you know already you'd be quite happy with all of that. If you guessed that the “html” in the middle of the filename means this file is the default for a normal webpage view and you could have all sorts of different files with things like “pdf” or “rss” in the names to make different types of output, then you'd really be ahead of the game!

Anyway, let's stick with html for the moment. The bare bones of the file look like this

<source lang="php" highlight="33">
jimport('joomla.application.component.view');

/**
* HTML View class for the Questions Component front screen
*/

class QuestionsViewQuestions extends JView
{

function display($tpl = null)
{
$this->questions = $this->get('Items');

// Display the view
parent::display($tpl);
}
}
</source>
JView is the base view class, and we've given our subclass of it a name matching the template I gave you above {component}{type}{element}, nice and consistent.

We load our questions and display them. Very little for us to do, with Joomla's little legs flailing along like crazy under the surface, just the way it ought to be!

The view's "get" function is a highly flexible piece of code, "getting" all manner of things. In this instance though what it's doing is getting data out of the data model, using what might appear a long winded route. However, by carefully picking the places to intervene in this pathway, Joomla does the grubby work of loading our data and we can just do the fun bit!

== Load our questions? That sounds like data! Is that the “model” bit? ==

Yup, here comes the first part of the "model" interaction.

The view already has enough information to find the corresponding data model, if you handled your naming conventions correctly!
From the name of this view, the framework will look for a file

<source lang="php" highlight="33">
<site root>/components/com_questions/models/questions.php
</source>

Although this is very easy to follow, there are a lot very specific things going on here.
I have very carefully called this view "questions", plural. This is because we are going to show the user a list of questions. I could have called it "questionnaire", but that's a singular thing, and Joomla is set up not only to distinguish between singular things (ie one row from a table) and multiple things (ie a list containing several rows from a table!), but also to guess the singular name from the plural name. I'm fairly sure it can guess "question" from "questions", but I don't think it would get there from "questionnaire". But we're getting ahead of ourselves.

In order to make our display easy, ie get Joomla to do most of the work for us, we'll define our "questions" class like this.

<span id="site root/components/com_questions/models/questions.php">
'''<tt><site root>/components/com_questions/models/questions.php</tt>'''
<source lang="php" highlight="31">
jimport('joomla.application.component.modellist');

/**
* Questions list Model ie a questionnaire
*/
class QuestionsModelQuestions extends JModelList
{
protected function getListQuery()
{
$db = $this->getDbo();
$query = $db->getQuery(true);

// Select the required fields from the table.
$query->select('*');
$query->from('#__questions_questions');

$query->where('questionnaire_id=1');

return $query;
}
}
</source></span>

Looks simple, but again, take notice of the little details and suddenly a lot more becomes clear.
We're extending a class called "JModelList", a class that's specifically set up for handling result sets of multiple rows. You'll be pleased, and unsurprised, to know there's a JModel class for single row result types, two of them in fact, but you'll probably be able to guess a lot about them from seeing this one.

So what's going on here? This is the only part of a chain of actions that we need to concern ourselves with in this simple instance. This method just defines the query object that the framework needs to select the precise pieces of data we want to see. You can guess that we've set up a "questions" table that has a field which groups questions into individual questionnaires. I've cheated here, let's pretend our fictitious admin with too much time on his hands puts these rows into the table manually, and changes this class every day. On other days he may select a different questionnaire number, just so we don't have to worry about how to pick one!

A protected function? Yes, it's internal to the chain of actions already in place to give us the list of questions in questionnaire "1" ready to display, and all we had to do was write one little query. How easy is that!

[[Category:Development]]
[[Category:Tutorials]]
[[Category:Joomla! 2.5]]

User:MarkRS/cascading cheat sheets/components/overview

2012-08-26T17:47:09Z

Mvangeest: Applied template

{{inprogressbyuser}}
= Component Overview =

Let the Frame(work) Take The Strain
{{JVer|2.5}}

Cascading cheat sheets for the expert beginner.

The previous article in this series was [[User:MarkRS/cascading_cheat_sheets/components/preamble|Component Preamble]]

== Ready... ==

The framework has set the scene, it's ready and waiting to swing into action for you, you've just got to string the right sequences together.

== Steady... ==

To start your component Joomla looks for a file

<tt><site root>/components/com_<component-name>/<component name>.php</tt>

This is where your component takes over.
In the simplest case, Joomla already has the rigging to do most of what you want.

Your file can be as simple, and standard, as

<span id="questions.php">
'''<tt><site root>/components/com_questions/questions.php</tt>'''
<source lang="php" highlight="18">

// No direct access to this file
defined('_JEXEC') or die('Restricted access');

// import joomla controller library
jimport('joomla.application.component.controller');

// Get an instance of the controller prefixed by the component name
$controller = JController::getInstance('questions');

// Perform the Request task
$controller->execute(JRequest::getCmd('task'));

// Redirect if set by the controller
$controller->redirect();
</source></span>

The base controller class (from the third line above. You know where to find that if you've been following this series) just looks for a file called “controller.php” in the component main directory. Just to be clear, in this case that means that the controller file is

<tt><site root>/components/com_questions/controller.php</tt>

Provided that is an instance of a controller class called QuestionsController then everything will be set for the next phase.

Of course, at the moment the URL doesn't contain "task=<something>" for the command JRequest::getCmd('task') to find, so the default setting is to display the first view of the component. What's the first view? Of course you'd guess (correctly) that the default view is "questions", nice and simple.

== Go... ==

Well, almost go.

In fact, certainly for the front end, it may well be that you don't need to add anything at all to the existing controller class except a name of your own. Your controller class could be as simple as

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

jimport('joomla.application.component.controller');

class QuestionsController extends JController

{
}
</source>
Just an empty class definition to establish our own component controller class, but not adding anything to the base class.

Even so, there's already a bit of Joomla idiom and scaffolding going on. Clearly the class that we're subclassing here is Jcontroller, but the less obvious part is that the name of our controller class is quite important, get it right and the framework will make all sorts of correct guesses for us. The class naming convention that gives you all this extra magic is

{component name}{type name}{element name}

Our component name, without its "com_" prefix, is questions. This class is a controller and, because it's such an easy (or perhaps “simple”) thing, there's no element name in this case. By convention Joomla class names are in camel case. Php ignores case in class names. Beware, it does not do the same thing to filesystem names, the simple rule is camel-case class (&tc) names, lowercase file and directory names. No, you don't have to, but do yourself a favour and do do.

The check for _JEXEC is a really good idea for the top of every file, and the import line is fairly obvious, why use dots instead of slashes? I don't know, but it's easy to put two and two together from our previous discussion of “Jfactory” and come up with the correct supposition that jimport(some.dotted.path) imports a file <site root>/libraries/some/dotted/path.php into the current file.

== Really Go ==

From here, the controller loads your first view, which probably gets some data out of your model, for your user to interact with.

The simplest way this happens is that you just let the controller set up its defaults so that it loads you initial view file. If you just let it do this it will assume you want a view called “questions” (it got this from the first part of its own name, “QuestionsController”, see, I told you it was a good idea).

== A view? How does that work? ==

Like this. In short the framework tries to load a view class file, which pulls in the data it needs to show and displays it using a layout file. Easy. Of course, the framework will make a whole load of assumptions for you about how to pull that all together. If you don't give it any further clues or directives, the assumptions it makes are as follows.

It looks for the view definition file

<site root>/components/com_questions/views/questions/view.html.php

From what you know already you'd be quite happy with all of that. If you guessed that the “html” in the middle of the filename means this file is the default for a normal webpage view and you could have all sorts of different files with things like “pdf” or “rss” in the names to make different types of output, then you'd really be ahead of the game!

Anyway, let's stick with html for the moment. The bare bones of the file look like this

<source lang="php" highlight="33">
jimport('joomla.application.component.view');

/**
* HTML View class for the Questions Component front screen
*/

class QuestionsViewQuestions extends JView
{

function display($tpl = null)
{
$this->questions = $this->get('Items');

// Display the view
parent::display($tpl);
}
}
</source>
JView is the base view class, and we've given our subclass of it a name matching the template I gave you above {component}{type}{element}, nice and consistent.

We load our questions and display them. Very little for us to do, with Joomla's little legs flailing along like crazy under the surface, just the way it ought to be!

The view's "get" function is a highly flexible piece of code, "getting" all manner of things. In this instance though what it's doing is getting data out of the data model, using what might appear a long winded route. However, by carefully picking the places to intervene in this pathway, Joomla does the grubby work of loading our data and we can just do the fun bit!

== Load our questions? That sounds like data! Is that the “model” bit? ==

Yup, here comes the first part of the "model" interaction.

The view already has enough information to find the corresponding data model, if you handled your naming conventions correctly!
From the name of this view, the framework will look for a file

<source lang="php" highlight="33">
<site root>/components/com_questions/models/questions.php
</source>

Although this is very easy to follow, there are a lot very specific things going on here.
I have very carefully called this view "questions", plural. This is because we are going to show the user a list of questions. I could have called it "questionnaire", but that's a singular thing, and Joomla is set up not only to distinguish between singular things (ie one row from a table) and multiple things (ie a list containing several rows from a table!), but also to guess the singular name from the plural name. I'm fairly sure it can guess "question" from "questions", but I don't think it would get there from "questionnaire". But we're getting ahead of ourselves.

In order to make our display easy, ie get Joomla to do most of the work for us, we'll define our "questions" class like this.

<span id="site root/components/com_questions/models/questions.php">
'''<tt><site root>/components/com_questions/models/questions.php</tt>'''
<source lang="php" highlight="31">
jimport('joomla.application.component.modellist');

/**
* Questions list Model ie a questionnaire
*/
class QuestionsModelQuestions extends JModelList
{
protected function getListQuery()
{
$db = $this->getDbo();
$query = $db->getQuery(true);

// Select the required fields from the table.
$query->select('*');
$query->from('#__questions_questions');

$query->where('questionnaire_id=1');

return $query;
}
}
</source></span>

Looks simple, but again, take notice of the little details and suddenly a lot more becomes clear.
We're extending a class called "JModelList", a class that's specifically set up for handling result sets of multiple rows. You'll be pleased, and unsurprised, to know there's a JModel class for single row result types, two of them in fact, but you'll probably be able to guess a lot about them from seeing this one.

So what's going on here? This is the only part of a chain of actions that we need to concern ourselves with in this simple instance. This method just defines the query object that the framework needs to select the precise pieces of data we want to see. You can guess that we've set up a "questions" table that has a field which groups questions into individual questionnaires. I've cheated here, let's pretend our fictitious admin with too much time on his hands puts these rows into the table manually, and changes this class every day. On other days he may select a different questionnaire number, just so we don't have to worry about how to pick one!

A protected function? Yes, it's internal to the chain of actions already in place to give us the list of questions in questionnaire "1" ready to display, and all we had to do was write one little query. How easy is that!

[[Category:Development]]
[[Category:Tutorials]]
[[Category:Joomla! 2.5]]

User:MarkRS/cascading cheat sheets/components/preamble

2012-08-26T17:46:29Z

Mvangeest: Applied template

{{inprogressbyuser}}

Let the Frame(work) Take The Strain {{JVer|2.5}}

Cascading cheat-sheets for the expert beginner.

= Component? =

Components deliver main areas of functionality, for example an event diary (there are many available as extensions), or the core functions of user management and displaying articles.

You'll find the code for components in the directories

<tt><site root>/components</tt>

<tt><site root>/administration/components</tt>

The first one is for for front end functionality, the second for back end (administration) functionality. The code for each component is in a subdirectory of one of these named <tt>com_<component name></tt>. Components, by definition, need functionality in both areas.

You should be able to find the, for example, content component ("com_content"), which is for displaying articles, the user component ("com_user"), which is for for managing website accounts, and several others.

This naming is one of those Joomla principles. You probably can hack it so that you can name a component directory “freds_diner”, but a whole load of defaults just won't work and you'll be fighting every step of the way.

= Component Internals =

== Getting started ==

We're going to zoom through the actions occurring from a website URL appearing to the beginning of a component running. We're going to start in the only possible place, the middle. It's going to look a little slow, but only for a very short while, and I think you'll find this will explain many of the Joomla idioms which will make your overall learning curve much quicker. Let's imagine we are looking at a component that allows website users to answer a questionnaire that is presented to them, stores their answers, and allows an administrator to look at their answers. To keep it nice and simple, we'll imagine our administrator has too much time on his hands and hard codes a new questionnaire into the front end every day.

Here's the process of events for the user

By selecting our questionnaire component, let's imagine that a URL like this

<yoursite>/questionnaire

is generated. Whilst this is not something that Joomla can directly work with, this is quite possibly the way it'll be. It could be the case if you had, for example, a SEF module enabled.

== Everything goes through index.php ==

This is the first step of every Joomla page. There are two different versions of index.php, one for the back end and a separate one for the front end. You'll find the front end file in the site root.

Have a look in this file and you'll see the first two active lines are

<source lang="php" highlight="33">
define('_JEXEC', 1);
define('DS', DIRECTORY_SEPARATOR);
</source>

The first line defines a constant called _JEXEC and gives it the value “1”. The value is pretty irrelevant but its simple existence is part of the system security. You'll see that many Joomla code files start with a check for this (or some other) constant, exiting immediately if it's not found. This helps prevent miscreants from going directly to internal parts of the system.

The second line is about to disappear in Joomla 3.0, since php handles converting “/” to the requirements of the platform you're actually running on. My advice is don't use DS, it's just BS these days.

The next three blocks are dull, simply loading defines files that are required for the core running. Even the line after doesn't really concern us yet, just setting a marker point used during debugging.

The line after that,
<source lang="php" highlight="33">
$app = JFactory::getApplication('site');
</source>

might look fairly dull, but it creates the application object that contains the top level scaffolding that defines Joomla. You start to get a sense of this with the next line

<source lang="php" highlight="33">
$app->initialise();
</source>
which, it's easy to guess, will set up a whole bunch of things to prepare Joomla for the job at hand.

== I know “factory”, but how does “JFactory” work? ==

Let's take a quick sidestep that helps make this very common Joomla style clearer.
Just taking the case above, as an OOP-aware developer you're familiar with the idea of an object factory, that thing that allows OOP people to tell themselves that they're not using global objects. But what about the “J”?

When you see stuff like this in the code, and there's a lot of it (JFactory, JForm, JText, and on and on), Joomla goes to the directory

<tt><site root>/libraries/joomla</tt>

to look for something with that name (without the “J”). So, for example there is a file

<tt><site root>/libraries/joomla/factory.php</tt>

that contains a class called JFactory, and, surprise surprise, it has a method named “getApplication”. This is a very standard way of Joomla calling core functionality. Some functionality is more detailed and so gets a whole directory in that location. For example the call

<source lang="php" highlight="33">
JUser::getInstance()
</source>

finds a file <tt><site root>/libraries/joomla/user/user.php</tt>. That file contains the definition of a class JUser, and you won't be shocked to find that it contains a method "getInstance".

Any call that looks like “J<Something>::function” will be using this mechanism. Now you know where to go when you need to know what a function like this does and the only answer you can get from the Joomla cognescenti is “read the code”! It's the same location for back end code as well as front end.

== And now, back to the records... ==

After another profiler call that I'm not going to talk about either, we come to the line

<source lang="php" highlight="33">
$app->route();
</source>

You remember I said that Joomla couldn't directly work with that URL we started with? The "route" method "decodes" the URL into something that Joomla can process. If we'd started with the URL

<your site>/index.php?option=com_questions

this "decoding" would have been at its simplest. Anything else will get converted back to this type of format, which is what the rest of the internals of the framework actually work with.

That all just brings us to the point where we can actually start doing something. You'll have realised that the line

<source lang="php" highlight="33">
$app->dispatch();
</source>

means that the application class (which, of course, is defined in the file <tt><site root>/libraries/joomla/application/application.php</tt>), that our factory class created for us initially, has a method “dispatch”. This method does a little bit of setting up and then starts the heavy lifting with the component. Having a brief look through that code, it's mostly easy to see this happening. But no, wait! Clearly the critical line doing this is

<source lang="php" highlight="33">
$contents = JComponentHelper::renderComponent($component);
</source>

but not only did we not pass in a value for $component to this method, but there's no file <tt><site root>/libraries/joomla/componenthelper</tt>

Well, no, that seems to be more of the internal wiring that does so much for you, you want to look in

<tt><site root>/libraries/joomla/application/component</tt>

where you'll find the file you want, “helper.php”.

And, when the framework doesn't find a component name stored in that variable, the dispatch method finds the component to load from the data that was stored during the "route" method. And, in case, like me, you're confused by this use of words; the not-so-obvious piece of information is that "renderComponent" is not the same as "render". The first one generates the output from a specific component. The second one takes that component output and fits it into the overall page that your user sees on screen.

So now we have arrived at the point that the component can start to do its work. The dispatcher has brought us there. Time to look at the details of component design!

I'm going to start developing an example of a simple component that looks after a little bit of data, shows it to some people and allows some people to edit it. In short, a "hello world" program for people who actually want to do something.

Follow along at [[User:MarkRS/cascading_cheat_sheets/components/overview|Component Overview]].

[[Category:Development]]
[[Category:Tutorials]]
[[Category:Joomla! 2.5]]

Template:Inprogressbyuser

2012-08-26T17:42:23Z

Mvangeest: Created template using Template:Incomplete

{{#ifeq:{{NAMESPACE}}|{{ns:User}}|
<div style="margin:0em 0em 1em 0em; width:100% vertical-align:top; text-align: center; border:1px solid #A0522D; background-color:#FFF8DC;">
<div style="border-bottom:1px solid #A0522D; background-color:#F5DEB3; padding:0.2em 0.5em 0.2em 0.5em; font-size:130%; font-weight:bold;">Note</div>
<div style="text-align: center; padding:1em 5em 1em 1em;"> 
This user subpage is a work in progress being written by [[{{#titleparts:{{FULLPAGENAME}}|1}}]]. Please {{#ifexist:{{TALKPAGENAME}}|discuss this page on [[{{TALKPAGENAME}}|its talk page]]|[[{{ns:User talk}}:{{#titleparts:{{PAGENAME}}|1}}|contact this user]]}} before editing it.
</div>
</div>
}}

Template:Incomplete

2012-08-26T15:45:27Z

Mvangeest: Changed layout <table> into <div>

<div style="margin:0em 0em 1em 0em; width:100% vertical-align:top; text-align: center; border:1px solid #A0522D; background-color:#FFF8DC;">
<div style="border-bottom:1px solid #A0522D; background-color:#F5DEB3; padding:0.2em 0.5em 0.2em 0.5em; font-size:130%; font-weight:bold;">Note</div>
<div style="text-align: center; padding:1em 5em 1em 1em;"> 
Please note that the content on this page is currently incomplete. Please treat it as a work in progress.
<div style="text-align:left;">{{#if:{{{1|}}}|{{needs|{{{1|}}}|{{{2|}}}}}|}}</div>
</div>
</div><includeonly>{{#if:{{{1|}}}||{{#ifeq:{{NAMESPACE}}|Template||[[Category:Joomla! Wiki need pages|{{PAGENAME}}]][[Category:Needs completion|{{PAGENAME}}]]}}}}</includeonly><noinclude>
{{documentation}}</noinclude>

Chunk:Framework

2012-08-25T13:39:25Z

Mvangeest: Removed reference: the link is already in the text itself

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

Joomla CMS

2012-08-24T21:46:15Z

Mvangeest: Created landing page

#REDIRECT [[CMS]]
[[Category:Landing Pages]]

Joomla! CMS

2012-08-24T21:45:44Z

Mvangeest: Created landing page

#REDIRECT [[CMS]]
[[Category:Landing Pages]]

Joomla Platform

2012-08-24T21:45:07Z

Mvangeest: Created landing page

#REDIRECT [[Platform]]
[[Category:Landing Pages]]

Joomla! Platform

2012-08-24T21:44:33Z

Mvangeest: Created landing page

#REDIRECT [[Platform]]
[[Category:Landing Pages]]

CMS

2012-08-24T21:43:39Z

Mvangeest: Changed page into article

{{For|content management systems in general|Content Management System}}

The Joomla! CMS is a PHP-based system for creating dynamic web pages. The CMS contains built-in functionality for managing and displaying HTML [[content]] items as well as a variety of data such as contacts and web links. Additionally, its flexible and extensible structure allows functionality to be added using [[Extension|extensions]].

In 2011, the underlying libraries were collected and released as the Joomla! [[Platform]]. The Joomla! project was split up and the Platform is now being developed as a separate project. The Joomla! CMS project uses the Platform releases as a framework to build the CMS on.

The home of the Joomla! CMS project is [http://joomla.org/ Joomla.org], which contains end-user information. [https://github.com/joomla/joomla-cms The ''joomla/joomla-cms'' GitHub repository] contains the source code, while the [[bug tracker]] and this documentation wiki are operated separately.

[[Category:Landing Pages]]

Main Page

2012-08-24T16:42:26Z

Mvangeest: Added links

__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]]
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]]
* [[:Category:Security Checklist|Joomla! Security Checklist]]
* [[Vulnerable Extensions List]]
* [[:Category:Top_Level|Browse all categories]]
* [[JDOC:Wiki policy|Wiki policy]]
* [[JEDL|Documentation license]]
* [[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.

* [[Getting Started with Joomla!]] {{JVer|2.5}}
* [[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.0, currently scheduled for release in September 2012. This will be the first of a new series (3.0/3.1/3.5) and maintaining backwards compatibility with 2.5 will not be required.
</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 [[Platform]]</div>
<div style="padding:0.4em 1em 0.3em 1em;">

The Joomla Platform is available. Development will be time-based with roughly a three-month release cycle.
* {{JVer|11.1}} [[Platform/11.1|Joomla Platform API Reference]]
* {{JVer|11.1}} [https://github.com/joomla/joomla-platform Joomla Platform on Github]
* {{JVer|11.1}} [[Potential_backward_compatibility_issues_in_Joomla_1.7_and_Joomla_Platform_11.1 | Backward Compatibility Tracking]]
</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.
* [[Migrating from Joomla 1.5 to Joomla 2.5]]
* [[:Category:Version {{CurrentLTSVer}} FAQ|Version {{CurrentLTSVer}} FAQ]]
* [http://www.joomla.org/about-joomla/technical-requirements.html Technical Requirements]
* [[Installing Joomla!]]
* [[Upgrading from Joomla 1.7 to Joomla 2.5]]

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]
</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}} was the last [[Release and support cycle|STS version]] prior to Joomla 2.5. Support for Joomla {{CurrentSTSVer|minor}} ended on 24 February 2012.
* [[Technical requirements]]
* [[{{NewestPageVer|Installing Joomla! }}|Installation]]
* [[What's new in Joomla 1.6|What's new]]
* [[ACL Tutorial for Joomla 1.6|Access control system]]
* [[International Enhancements for Version 1.6|International enhancements]]
* [[Layout Overrides in Joomla 1.6|Layout overrides]]
* [[: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==
{{license}}

Standard form field types

2012-08-24T16:06:34Z

Mvangeest: Added link

Numerous types of [[form field]] are built into Joomla!. The following table lists these standard types and their availability. Use the [[/Single-page reference|single-page reference]] if you want to print all existing form field documentation.

{{JVer|1.5}} Please note that many of these fields are available as [[Parameter|parameter types]] in Joomla! 1.5. For a list of parameter types, see [[Standard parameter types]]. For a comparison between form field and parameter types, see [[Standard form field and parameter types]].
{| class="wikitable" style="vertical-align:top; border:1px solid Sienna; background-color:Cornsilk;"
|- style="background-color:Wheat; font-weight:bold; text-align: left;"
!width=15%|Type
!width=70%|Description
!width=15%|Availability
|-
|[[Accesslevel form field type|accesslevel]]
|provides a drop down list of viewing access levels.
|{{JVer|1.6}} and newer
|-
|[[Cachehandler form field type|cachehandler]]
|provides a list of available cache handling options.
|{{JVer|1.6}} and newer
|-
|[[Calendar form field type|calendar]]
|provides a text box for entry of a date. An icon next to the text box provides a link to a pop-up calendar, which can also be used to enter the date value.
|{{JVer|1.6}} and newer
|-
|[[Category form field type|category]]
|provides a drop down list of categories for an extension.
|{{JVer|1.6}} and newer
|-
|[[Checkbox form field type|checkbox]]
|provides a single checkbox to be checked or unchecked
|{{JVer|1.6}} and newer
|-
|[[Checkboxes form field type|checkboxes]]
|provides unlimited checkboxes that can be used for multi-select.
|{{JVer|1.6}} and newer
|-
|[[Combo form field type|combo]]
|provides a combo box field.
|{{JVer|1.6}} and newer
|-
|[[Componentlayout form field type|componentlayout]]
|provides a grouped list of core and template alternate layouts for a component item.
|{{JVer|1.6}} and newer
|-
|[[Contentlanguage form field type|contentlanguage]]
|provides a list of installed content languages for use in conjunction with the language switcher plugin.
|{{JVer|1.6}} and newer
|-
|[[Editor form field type|editor]]
|provides an editor area field.
|{{JVer|1.6}} and newer
|-
|[[Editors form field type|editors]]
|provides a drop down list of the available WYSIWYG editors.
|{{JVer|1.6}} and newer
|-
|[[File form field type|file]]
|
|{{JVer|1.6}} and newer
|-
|[[Filelist form field type|filelist]]
|provides a drop down list of files from a specified directory.
|{{JVer|1.6}} and newer
|-
|[[Folderlist form field type|folderlist]]
|provides a drop down list of folders from a specified directory.
|{{JVer|1.6}} and newer
|-
|[[Groupedlist form field type|groupedlist]]
|provides a drop down list of items organized into groups.
|{{JVer|1.6}} and newer
|-
|[[Helpsite form field type|helpsite]]
|provides a drop down list of the help sites for your Joomla installation.
|{{JVer|1.6}} and newer
|-
|[[Hidden form field type|hidden]]
|provides a hidden field for saving a form field whose value cannot be altered directly by a user in the Administrator (it can be altered in code or by editing the ''params.ini'' file).
|{{JVer|1.6}} and newer
|-
|[[Imagelist form field type|imagelist]]
|provides a drop down list of image files in a specified directory.
|{{JVer|1.6}} and newer
|-
|-
|[[Integer form field type|integer]]
|provides a drop down list of integers between a minimum and maximum.
|{{JVer|1.6}} and newer
|-
|[[Language form field type|language]]
|provides a drop down list of the installed languages for the Front-end or Back-end.
|{{JVer|1.6}} and newer
|-
|[[List form field type|list]]
|provides a drop down list of custom-defined entries.
|{{JVer|1.6}} and newer
|-
|[[Media form field type|media]]
|provides modal access to the media manager for insertion of images with upload for users with appropriate permissions.
|{{JVer|1.6}} and newer
|-
|[[Menu form field type|menu]]
|provides a drop down list of the available menus from your Joomla site.
|{{JVer|1.6}} and newer
|-
|[[Menuitem form field type|menuitem]]
|provides a drop down list of the available menu items from your Joomla site.
|{{JVer|1.6}} and newer
|-
|[[Modulelayout form field type|modulelayout]]
|provides a list of alternative layout for a module grouped by core and template.
|{{JVer|1.6}} and newer
|-
|[[Password form field type|password]]
|provides a text box for entry of a password. The password characters will be obscured as they are entered.
|{{JVer|1.6}} and newer
|-
|[[Radio form field type|radio]]
|provides radio buttons to select different options.
|{{JVer|1.6}} and newer
|-
|[[Rules form field type|rules]]
|provides a matrix of group by action options for managing access control. Display depends on context.
|{{JVer|1.6}} and newer
|-
|[[Sessionhandler form field type|sessionhandler]]
|provides a drop down list of session handler options.
|{{JVer|1.6}} and newer
|-
|[[Spacer form field type|spacer]]
|provides a visual separator between form fields. It is purely a visual aid and no value is stored.
|{{JVer|1.6}} and newer
|-
|[[SQL form field type|sql]]
|provides a drop down list of entries obtained by running a query on the Joomla Database. The first results column returned by the query provides the values for the drop down box.
|{{JVer|1.6}} and newer
|-
|[[Templatestyle form field type|templatestyle]]
|provides a drop down list of template styles.
|{{JVer|1.6}} and newer
|-
|[[Text form field type|text]]
|provides a text box for data entry.
|{{JVer|1.6}} and newer
|-
|[[Textarea form field type|textarea]]
|provides a text area for entry of multi-line text.
|{{JVer|1.6}} and newer
|-
|[[Timezone form field type|timezone]]
|provides a drop down list of time zones.
|{{JVer|1.6}} and newer
|-
|[[User form field type|user]]
|provides a modal list of users.
|{{JVer|1.6}} and newer
|-
|[[Usergroup form field type|usergroup]]
|provides a drop down list of user groups.
|{{JVer|1.6}} and newer
|}

Checkbox form field type

2012-08-24T16:00:05Z

Mvangeest: Changed examples for consistency with other form field types

The '''checkbox''' form field type provides a single checkbox. If the parameter has a saved value this is selected when the page is first loaded. If not, the default value (if any) is selected.

* '''type''' (mandatory) must be checkbox
* '''name''' (mandatory) is the unique name of the parameter.
* '''label''' (mandatory) (translatable) is the descriptive title of the field.
* '''value''' (optional) is the default value of the checkbox. If exist the checkbox will be checked by default.
* '''description''' (optional) (translatable) is text that will be shown as a tooltip when the user moves the mouse over the label.
* '''class''' (optional) is a CSS class name for the HTML form field. If omitted this will default to 'inputbox'.
<noinclude>
Example XML field definition:

<source lang="xml"><field name="show_title" type="checkbox" label="Show title" description="Show the title of the item" value="1" /></source>

=== See also ===
* [[Standard form field types|List of standard form field types]]
[[Category:Standard form field types]]</noinclude>

Standard form field types/Single-page reference

2012-08-24T15:55:27Z

Mvangeest: Created page

This page lists all documented [[form field]] types together. Use [http://docs.joomla.org/index.php?title={{FULLPAGENAMEE}}&printable=yes the printable version of this page] to print this reference.
<DPL>
noresultsheader=\n
include=*
format=,\n== [[%TITLE%|%TITLE%]] ==\n
reset=categories
category=Standard form field types
</DPL>

Chunk:Platform

2012-08-24T13:51:18Z

Mvangeest: Added link

<noinclude>{{chunk}}</noinclude>__NOTOC__
{|
|-
|colspan=2|<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>
|-
|The release of the Joomla Platform on 5 July 2011<ref>http://developer.joomla.org/news/362-version-11-1-of-the-joomla-platform-released.html</ref> marked an important change in the Joomla! CMS architecture. From the very beginning of Joomla!, the Joomla! CMS and its Framework, which the Joomla! CMS Application was built on, were an integral part of each other. The main difference now with the release of the Joomla! Platform is the separation of the Joomla! [[Framework]] from the Joomla! CMS Application. Before, from the previous Joomla! Framework could not be used separate from the Joomla! CMS Application. Now, the Joomla! Platform is a completely independent set of libraries which do not require the Joomla! CMS Application. These libraries are made up of libraries maintained by the Joomla! Project and libraries maintained by other 3rd party developers. 'Connectors' or 'Event Listeners' which are simply called Plugins, can now be created by 3rd party developers to interact with either or both libraries to create Applications independent of the Joomla! CMS Application.

The home of the Joomla! Platform is [https://github.com/joomla/joomla-platform the ''joomla/joomla-platform'' GitHub repository] that contains the source, documentation and means to contribute (pull requests).
|[[File:Architecture Joomla Platform.png|thumb|500px|The Joomla! Platform]]
|}
<noinclude><references/></noinclude>

Chunk:Framework

2012-08-24T13:42:55Z

Mvangeest: Adjusted link after page move

<noinclude>{{chunk}}</noinclude>__NOTOC__
{|
|-
|The Joomla! Framework<ref>See also [[Platform]]</ref><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>

CMS Architecture in 1.5 and 1.6

2012-08-24T13:39:58Z

Mvangeest: Updated contents

{{RightTOC}}

The [[:Category:Joomla! 1.5|1.5]] and [[:Category:Joomla! 1.6|1.6]] versions of the Joomla! [[CMS]] are based on a three-tiered system that consists of the following:

[[File:JoomlaArchitecture0.png|thumb|425px|Joomla! 1.5 Architecture]]
# The top, Extensions layer, consists of [[Extension|Extensions]] to the Joomla [[Framework]] and its applications:
#*[[Module|Modules]]
#*[[Component|Components]]
#*[[Template|Templates]]
# The middle, Application layer, consists of applications that extend the Framework [[JApplication]] class. Currently, there are four applications included in the Joomla distribution:
#*[[JInstallation]] is responsible for installing Joomla on a web server and is deleted after the installation procedure has been completed.
#*[[JAdministrator]] is responsible for the back-end website administration.
#*[[JSite]] is responsible for the front-end of the website.
#*[[XML-RPC]] supports remote administration of the Joomla website.
# The bottom, Framework layer, consists of:
#*the Joomla! [[Framework|Framework]]<ref>See also [[Platform]]</ref><ref>[[Joomla! Framework vs Joomla! Platform]]</ref> itself, whose classes are listed [[Framework/1.5#Packages and Classes|here]].
#*[[Library|Libraries]] that are required by the [[Framework]] or are installed for use by third-party developers.
#*[[Plugin|Plugins]] extend the functionality available in the [[Framework]].

== Further Reading ==
<references/>

[[Category:Explanations]][[Category:Framework]]

About the Joomla Framework

2012-08-24T13:36:41Z

Mvangeest: moved About the Joomla Framework to CMS Architecture in 1.5 and 1.6: This page describes the entire architecture of the CMS in those two releases and not just the Framework.

#REDIRECT [[CMS Architecture in 1.5 and 1.6]]

CMS Architecture in 1.5 and 1.6

2012-08-24T13:36:40Z

Mvangeest: moved About the Joomla Framework to CMS Architecture in 1.5 and 1.6: This page describes the entire architecture of the CMS in those two releases and not just the Framework.

{{RightTOC}}

==The Joomla! Framework<ref>See also [[Platform]]</ref><ref>See also [[Framework]]</ref><ref>[[Joomla! Framework vs Joomla! Platform]]</ref>==

The [[:Category:Joomla! 1.5|Joomla! 1.5]] and [[:Category:Joomla! 1.6|Joomla! 1.6]] is a three tiered system consisting of the following:

[[File:JoomlaArchitecture0.png|thumb|425px|Joomla! 1.5 Architecture]]
# The top, Extensions layer, consists of [[Extension|Extensions]] to the Joomla [[Framework]] and its applications:
#*[[Module|Modules]]
#*[[Component|Components]]
#*[[Template|Templates]]
# The middle, Application layer, consists of applications that extend the Framework [[JApplication]] class. Currently there are four applications included in the Joomla distribution:-
#*[[JInstallation]] is responsible for installing Joomla on a web server and is deleted after the installation procedure has been completed.
#*[[JAdministrator]] is responsible for the back-end website administration.
#*[[JSite]] is responsible for the front-end of the website.
#*[[XML-RPC]] supports remote administration of the Joomla website.
# The bottom, Framework layer, consists of:-
#*the Joomla! 1.5 [[Framework/1.5|Framework]] itself, whose classes are listed [[Framework/1.5#Packages and Classes|here]].
#*[[Library|Libraries]] that are required by the [[Framework]] or are installed for use by third-party developers.
#*[[Plugin|Plugins]] extend the functionality available in the [[Framework]].

== Further Reading ==
<references/>

[[Category:Tutorials]][[Category:Framework]]

Chunk:Framework

2012-08-24T13:33:19Z

Mvangeest: Updated contents

<noinclude>{{chunk}}</noinclude>__NOTOC__
{|
|-
|The Joomla Framework<ref>See also [[Platform]]</ref><ref>See also [[Subpackages]]</ref> was an important part of the Joomla 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 ([[About the Joomla Framework|Learn more about the Joomla Framework]]). Between April and July 2011, the Framework was rebranded as the Joomla! [[Platform]], which is now being developed separately from the Joomla! [[CMS]]. The first version of the CMS to ship with the Platform was version 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>

Framework

2012-08-24T13:31:48Z

Mvangeest: Adjusted layout

{{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]].

{{splist}}
=== See Also ===
<references/>
<noinclude>[[Category:Framework]][[Category:Subpackages]]</noinclude>

Chunk:Framework

2012-08-24T13:31:14Z

Mvangeest: Moved reference-specific text to Framework

<noinclude>{{chunk}}</noinclude>__NOTOC__
{|
|-
|The Joomla Framework<ref>See also [[Platform]]</ref><ref>See also [[Subpackages]]</ref> was an important part of the Joomla 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 ([[About the Joomla Framework|Learn more about the Joomla Framework]]). In April 2011, the Framework was rebranded as the Joomla! [[Platform]], which is now being developed separately from the Joomla! [[CMS]]. The first version of the CMS to ship with the Platform was version 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>

Framework

2012-08-24T13:30:56Z

Mvangeest: Moved reference-specific text from Chunk:Platform

{{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]].

{{splist}}

=== See Also ===
<references/>
<noinclude>[[Category:Framework]][[Category:Subpackages]]</noinclude>

Chunk:Framework

2012-08-24T13:28:54Z

Mvangeest: Updated contents

<noinclude>{{chunk}}</noinclude>__NOTOC__
{|
|-
|The Joomla Framework<ref>See also [[Platform]]</ref><ref>See also [[Subpackages]]</ref> was an important part of the Joomla 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 ([[About the Joomla Framework|Learn more about the Joomla Framework]]). In April 2011, the Framework was rebranded as the Joomla! [[Platform]], which is now being developed separately from the Joomla! [[CMS]]. The first version of the CMS to ship with the Platform was version 1.7.

Third party developers benefit from the rich, and easily accessible functionality that the Joomla Framework provides. 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]].
|[[Image:JoomlaArchitecture0.png|thumb|425px|The Joomla Architecture]]
|}
<noinclude><references/></noinclude>

Where are the web pages ?

2012-08-23T19:04:45Z

Mvangeest: moved Where are the web pages ? to Where are the web pages?: Fixed spelling error

#REDIRECT [[Where are the web pages?]]

Where are the web pages?

2012-08-23T19:04:45Z

Mvangeest: moved Where are the web pages ? to Where are the web pages?: Fixed spelling error

If you are coming from a traditional website made up of separate HTML pages, you may well wonder where the pages are.

In Joomla! almost everything that you would normally think of as a web page is actually stored in a MySQL database. When you create a new page, your content is stored in a database record, not in a separate file.

Then when your site is viewed, Joomla! calls up different items from your database and puts them together to make what is displayed to the user.

One exception is that your images are usually stored in the images directory and not the database.

Your MySQL database usually is created by you during the installation process (unless you use a Fantastico or a similar installer that will create the database automatically). If you have a control panel on a linux host, you can usually access MySQL through a program called [http://www.phpmyadmin.net/ phpMyAdmin]. This will allow you to view your database.

For a short tutorial on converting a static HTML web site to Joomla!, see [[Converting an existing website to a Joomla! website]].

[[Category:FAQ]]
[[Category:Administration FAQ]]
[[Category:Getting Started FAQ]]
[[Category:Version 1.5 FAQ]]

Entering raw HTML in editors

2012-08-23T18:59:54Z

Mvangeest: Only the redirect page should be in the FAQ

If you want to enter raw [[wikipedia:HTML|HTML]] in a Joomla! editor field, you may encounter problems such as tags and attributes disappearing after you save the item you are editing. This is usually caused by a filtering mechanism; either your editor's or Joomla!'s.

On the [[Administrator (Application)|Administrator panel]], take the following steps to disable filtering:

* '''Disable your editor'''. Since each editor has its own filtering mechanism and it is not always possible to turn it off, disabling your editor is the easiest way of eliminating it as a possible source of the problem. Open ''My Profile'' from the ''Site'' menu, set ''Editor'' under ''Basic Settings'' to ''Editor - None'' and click ''Save & Close''.
* '''Disable Joomla's filtering'''. Open the ''Global Configuration'' from the ''Site'' menu and go to the ''Text Filters'' tab. Set the ''Filter Type'' to ''No Filtering'' for the user group that you are in - ''Administrator'', ''Super Users'', or both (this is site-dependent). '''Caution''': Do not use the ''No Filtering'' setting for user groups that are not fully trusted – that would introduce a sizeable security risk.'''

You should be able to enter raw HTML in any editor field now. You may try to re-enable your editor to see whether it influences the process. If the editor does mangle the HTML you are trying to enter, consult its documentation to see if there is a way to disable its filtering.

[[Category:Tutorials]]
[[Category:Article Management]]

How do you enter raw HTML in editors?

2012-08-23T18:58:16Z

Mvangeest: Created FAQ question

#REDIRECT [[Entering raw HTML in editors]]
[[Category:Administration FAQ]]

Platform

2012-08-23T16:30:18Z

Mvangeest: Added references to additional documentation. These should not be part of the Chunk

{{Chunk:Platform}}
{{splist|API documentation is available for the following Joomla Platform versions}}

The Platform project maintains its own documentation that may be more up-to-date than the documentation found on this Wiki:

* [http://api.joomla.org/ An automatically genenerated '''API reference''']
* [http://developer.joomla.org/manual/ A DocBook '''developer manual''' inside the source tree]

===See Also===
* [[Framework]]
* [[Subpackages]]
<references/>
<noinclude>[[Category:Platform]][[Category:Subpackages]]</noinclude>