Joomla! Documentation - User contributions [en]

Development Working Group

2011-09-23T00:03:03Z

Iv660: /* Introduction */ letter case

{{incomplete}}[[Image:workgroups_development.jpg|right]]

== Introduction ==

'''''"..To develop a cutting edge, state of the art Web Content Management application framework..."'''''

The main responsibility of the [[Development Working Group]] is taking care of the development of the Joomla! application framework and the Joomla! Content Management System (CMS). Besides the development of the Joomla! codebase the development working group defines the Joomla! roadmap strategy, creating (architectural) designs for major and minor versions and of course take care of bug and security fixes in maintenance versions.

The development working group holds two teams: the [[Development Team]] and the so called [[Bug Squad]]. Both teams have a separate responsibility but together they form the development force for the Joomla! project.

Joomla! is as every other open-source project based upon the fundaments of collaborative and is a community-driven project. This means that the software, the documentation, the ever growing number of available the extensions, support (forum, mailing, lists newsletters, user groups are collaboratively produced by users and developers all over the world.

In this section of the documentation wiki we have tried to describe all relevant aspects to Joomla! development. Our effort strives to be as complete as we can be, but we don't rule out that information you are looking for is not (yet) documented. We encourage everyone to help completing the documentation effort and maximize the community effect within the Joomla! project.

== Getting started ==

The amount of information that is available from this page is like a small (e-)book. We tried to organize the information in a logical order, and also structure the information in the most efficient way. To prevent you from reading for some hours, we use a simple documentation method. Per topic we draft a short description on the information that can be found, and in the linked pages we will provide as much as possible detail. Keep in mind that you can use the free-text search or the generated table of contents for this documentation category to find your information. If there is information missing, feel free to add this within this wiki.

* [[First look around]]
* [[Guide to the Development Documentation wiki section]]

== Technical infrastructure ==

For collaboration we have set up an infrastructure like version control, the bug tracker and of course this wiki for documentation. These assets are essential for Joomla! development. Below you will find links to the infrastructure that is used within the Joomla! project.

* [[Mailing lists]]
* [[Version control]]
* [[Bug tracker]]
* [[IRC/Real-Time Chat]]
* [[Wikis]]
* [[Web sites]]
* [[Joomlacode]]

== Social and Political Infrastructure ==

Ready for something more heavy at tea? Then you're in the right place here ;-) In this section we describe the basic organizational structures we have put in place, but probably at least important we describe the code of conduct we follow. For open source projects this is especially important because we have no hierarchical relation with our volunteers, the Joomla! project follows the [[http://producingoss.com/en/consensus-democracy.html Consensus Based Democracy]] model.

* [[Organizational structure]]
* [[Code of conduct]]

== Communications ==

There are several ways to get in touch, or communicate with the development community of Joomla! Within the working groups we try to share as much as possible information, using different media. It is a mix of tools and events we organized, details can be found in the links below.

* [http://developer.joomla.org/section-blog.html Development blog]
* [http://developer.joomla.org/gsoc2008.html Summer of Code blog]
* [http://developer.joomla.org/bug-squad-blog.html Bug Squad blog]
* [http://forum.joomla.org/viewforum.php?f=509&sid=fb99f7b1a81437ff25e8dd707343bae0 Development forum]
* [[Development meetings]]
* [http://www.google.com/calendar/embed?src=calendar@joomla.org Joomla! events]
* [http://community.joomla.org/joomla-user-groups.html Local user groups]
* [http://docs.joomla.org/Pizza_Bugs_and_Fun_2 Pizza Bugs and Fun]

== Packaging, releasing and daily development ==

* Release numbering
* Release branches
* Sandboxes
* Stabilizing a release
* Packaging
* Testing and releasing
* Maintaining multiple release lines (general description, and our current release lines)
* Releases and daily development

== Development community ==

* How to get involved?
* 3rd party development
* Interesting topics to study
* Recommended readings and books

== Licensing and copyrights ==

* General Public License

== How to contribute to Joomla! development ==

== Coding standards ==
A list of Joomla! coding standards as of 13 February 2010 can be found here: [[Coding style and standards]]. There is also a list of [[Core Development Best Practices]].

== Writing secure Joomla! code ==

* [http://developer.joomla.org/tutorials/181-preventing-sql-injections.html Preventing SQL injections]
* [[Secure coding guidelines]]

== Unit testing within Joomla! ==

The goal of unit testing is to isolate each part of the program and show that the individual parts are correct. A unit test provides a strict, written contract that the piece of code must satisfy. As a result, it affords several benefits. Unit tests find problems early in the development cycle.

In computer programming, unit testing is a method of testing that verifies the individual units of source code are working properly. A unit is the smallest testable part of an application. In procedural programming a unit may be an individual program, function, procedure, etc., while in object-oriented programming, the smallest unit is a method, which may belong to a base/super class, abstract class or derived/child class.

Ideally, each test case is independent from the others; Double objects like stubs, mock or fake objects as well as test harnesses can be used to assist testing a module in isolation. Unit testing is typically done by software developers to ensure that the code they have written meets software requirements and behaves as the developer intended.

Ground work on the implementation of unit testing has been done by Enno Klasing during the Summer of Code 2007 project and has been perfected by Alan Langford from the Joomla! [[Development Team]]. The way [[Unit Testing]] is implemented within the Joomla! project has been documented in the [[Unit Testing]] chapter.

* [[Unit Testing]]

== What does a Joomla! development environment look like ==

== Debugging your Joomla! code ==
One way to debug Joomla! code is using the open-source programs Eclipse and XDebug. Instructions for setting up these programs is available in [[Setting up your workstation for Joomla! development]].

== Joomla! organization ==

* An explanation on how the [[Development Team]] is organized.
* An explanation on how the [[Bug Squad]] is organized.

== Joomla! planning process and procedures ==
* Description on the [[Development Strategy of Joomla!]]
* A description of how the [[Joomla! Maintenance Procedures]] are organized
* [[Release procedure and checklist]]
* [[Team member administration]]

== Miscellaneous ==

This is "old" content and needs to be moved to the final location in this wiki, work in progress...

* [[Unit Testing]] within the Joomla! project
* [[The use of Subversion]]
<noinclude>[[Category:Development Working Group]]</noinclude>

[[Category:Working Groups]]

Talk:How to determine if the user is viewing the front page

2011-08-13T00:30:31Z

Iv660:

would then function as in the case of a 404 SEF to show that a module appears as a 404?

===Joomla! 1.5 example fails===

Joomla! 1.5 example fails unless the Itemid is added explicitly to URL.
[[User:Iv660|Iv660]] 19:29, 12 August 2011 (CDT)

Talk:How to determine if the user is viewing the front page

2011-08-13T00:29:03Z

Iv660:

would then function as in the case of a 404 SEF to show that a module appears as a 404?

----

Joomla! 1.5 example fails unless the Itemid is added explicitly to URL.
[[User:Iv660|Iv660]] 19:29, 12 August 2011 (CDT)

J2.5:Supporting SEF URLs in your component

2011-08-12T23:45:35Z

Iv660: /* The Slug */

{{:Search Engine Friendly URLs}}
Joomla can, initially, only create human readable URLs for built-in components. As a [[Developers|developer]], you have to create a '''router''' to allow your [[component]] to create human readable URLs.

== 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 URL's ==

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, the catid is second and the id is third 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 nice and human readable component URL's.

== Application Route Parsing ==

The [[API 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>