Joomla! Documentation - User contributions [en]

Understanding Output Overrides

2008-07-05T14:30:00Z

Instance: /* Customise the Component Output */

= Understanding Output Overrides in "Joomla!" 1.5 =
Written by Andrew Eddie

This was Developer Blog post by Andrew, initially copied to the wiki with minor edits by Alan Langford. This is still a work in progress.
== Introduction ==
There are many competing requirements for web designers ranging from accessibility to legislative to personal preferences. Rather than trying to over-parameterise views, or trying to aim for some sort of line of best fit, or worse, sticking its head in the sand, "Joomla!" has added the potential for the designer to take over control of virtually all of the output that is generated.

"Joomla!" has been criticized by some for not giving due attention to accessibility or being archaic in their approach to web standards. However with 1.5, the responsibility, but more importantly the power is back in the designer's hands.

In addition, except for files that are provided in the "Joomla!" distribution itself, these methods for customisation eliminate the need for designers and developers to "hack" core files that could change when the site is updated to a new version. Because they are contained within the template, they can be deployed to the Web site without having to worry about changes being accidentally overwritten when your System Administrator upgrades the site.

The aim of this tutorial is to introduce the how fours areas of the output of "Joomla!" are able to be customised by the template designer.

Not interested in all the theory? Jump straight to the cheat sheet.
== MVC 101 ==
MVC can be a scary acronym. It stands for Model-View-Controller and the concepts behind MVC are responsible for the extra flexibility that is now afforded to the designer. While parts of the theory can be rather involved and complicated, the only part that the designer need worry about is the V for View. This is the part that is concerned with output.

Different extensions display output in different ways.

Components, as you would already know, are fairly complex and have the ability to display different information in different ways. For example, the Articles Component (com_content) is able to display a single article, or articles in a category, or categories in a section. Each of the ways of representing the different types of data (an article, or a category, or a section) is called a "view" (this comes from our MVC terminology). Most components will have many views. However, the view doesn't actually display the output. This is left up to what we call a "layout" and it is possible for a view to have a variety of layouts.

The main thing to remember here is that components can have multiple views, and each view can have one or more layouts. Each view assembles a fixed set of information, but each layout can display that information in different ways. For example, the Category view in the Articles component assembles a number of articles. These articles could be displayed in a list or in a table (and probably other ways as well). So this view may have a "list" layout and a "table" layout to choose from.

Modules, on the other hand, are very simple. They generally display one thing one way. Modules don't really have views but they do support a layout. Some developers might even support a choice of layout through module parameters.
=== Template versus Layout ===

It is very important to distinguish between the role of template and the role of layouts. The template sets up a structural framework for the page of the Web site. Within this framework are positions for modules and a component to display. What actually gets displayed is governed by the module layout, or the combination of view and layout in the case of the component.

The following image shows the structural layout of a typical "Joomla!" template (rhuk_milkyway, the default for 1.5). The module positions are displayed by adding tp=1 to the URL (eg, index.php?tp=1). You can clearly see where the module output is contained within the overall template, as well as the main component output starting in the lower-centre region. However, what is actually output in those regions, is controlled by the layouts.

[[Image:FrontpageTemplatePositions.png|Typical Joomla! screenshot with template positions shown.]]

=== Ancillary Customisation ===

While not strictly related to the MVC, there are two other important areas to consider when looking at customising the output of "Joomla!".

In addition to layouts, modules have what we call "chrome". Chrome is the style with which a module is to display. Most developers, designers and probably some end-users will be familiar with the different built-in styles for modules (raw, xhtml, etc). It is also possible to define your own chrome styles for modules depending on the designer result. For example, you could design a chrome to display all the modules in a particular position in a fancy Javascript collapsing blind arrangement.

In the screenshot above, you can just make out the names of some of the built-in module chrome used (rounded, none and xhtml).

The second area has to do with controlling the pagination controls when viewing lists of data. We will look at that in more detail later.
== Component Output Types and Layout Overrides ==

To understand layout overrides we must first understand the file structure of a component. While there are many parts to a component, all fulfilling different roles and responsibilities, we want to look just in the /views/ directory. Here is the partial structure for two of the com_content views:
<pre>
/components
/com_content
/views
/articles
/tmpl
default.php (this is a layout)
form.php (this is a layout)
view.html.php (this is the view that outputs the HTML)
view.pdf.php (this is the view that outputs the PDF)
/category
/tmpl
blog.php (layout)
blog_items.php (a sub-layout
default.php (layout)
view.html.php (HTML view)
view.feed.php (RSS feed)
</pre>
So what you see here is that under the /views/ directory, each view is placed in a directory of its own. The content component actually has three other views not shown: archive, frontpage and section.
=== Output Types ===
Under the /articles/ directory we have a number of files. There is almost always a file called view.html.php. This is what we call the view file, but there can be more than one depending on the type of output to produce. It has a specific naming convention, view.output_type.php, where the output type can be html, feed, pdf, raw or error (for more information see JDocument in the API reference and look in the directory /libraries/joomla/document/). What this means is when we want html output for this particular view, the view.html.php file is used. When we want the RSS output, the view.feed.php file is used.

The affect of these different output types is most apparent when the Global Configuration setting for Search Engine Friendly URLs is set to Yes, Use Apache mod_rewrite is set to Yes, and Add suffix to URLs is also set to Yes. When this is done, the site URLs will look something like this:

<pre>
http://domain/sports.html
http://domain/sports.feed
http://domain/sports/rowing.html
http://domain/sports/rowing.pdf
</pre>
The exact URL will vary depending on how you set up your site but the point here is to show that sports.html will use the category view's view.html.php file to, and that sports.feed will display the RSS feed for the category using view.feed.php. It should be noted that you cannot currently customise feed or PDF output types. However, you can customise the html output type and this is where layouts come into play.

=== Layouts ===
Under the view directory there is a /tmpl/ directory in which the layout files reside. Each PHP file in this directory represents a layout. For example, article/tmpl/default.php is the default layout for an article whereas article/tmpl/form.php is the edit form for an article; category/tmpl/default.php is the default layout for a category whereas category/tmpl/blog.php displays the list of article differently.

The relationship between component views and layout is most plainly seen when adding a new menu item. The next screenshot represents the typical display of the New Menu Item page. Having clicked on Articles (which represents com_content), the tree expands to show the list of views and each layout within the view.

[[Image:Menu_item_type_articles.png|Screenshot of creating a new menu item fro an article.]]

You will notice that while there are extra files in some of the /tmpl/ directories (like pagebreak.php in the article view), they are missing from the list. This is due to instructions in the XML file for the layout (for example, pagebreak.xml) to hide the layout (or even the view) from the menu item list. However, this is another broad topic which will be covered in another tutorial.

Armed with all that knowledge of how all the parts relate to each other, we are now ready to actually create our layout overrides.

=== Copying or Creating Layout Files ===

Layout overrides only work within the active template and are located under the /html/ directory in the template. For example, the overrides for rhuk_milkyway are located under /templates/rhuk_milkyway/html/, for the JA Purity template under /templates/ja_purity/html/ and for Beez under /templates/beez/html/.

It is important to understand that if you create overrides in one template, they will not be available in other templates. For example, rhuk_milkyway has no component layout overrides at all. When you use this template you are seeing the raw output from all components. When you use the Beez template, almost every piece of component output is being controlled by the layout overrides in the template. JA Purity is in between having overrides for some components and only some views of those components.

The layout overrides must be placed in particular way. Using Beez as an example you will see the following structure:
<pre>
/templates
/beez
/html
/com_content (this directory matches the component directory name)
/articles (this directory matches the view directory name)
default.php (this file matches the layout file name)
form.php
</pre>

The structure for component overrides is quite simple: /html/com_component_name/view_name/layout_file_name.php. Let's look at a few examples.

The rhuk_milkyway template does not have any layout overrides for any components. If we want to override the default layout for an article, first we need to copy this file:

/components/com_content/views/article/tmpl/default.php

to this location, creating the appropriate directories in the event they don't already exist:

/templates/rhuk_milkyway/html/com_content/article/default.php

If we wanted to override the blog layout in the category view, we would copy this file:

/components/com_content/views/category/tmpl/blog.php

to:

/templates/rhuk_milkyway/html/com_content/category/blog.php

Once the files are copied, you are free to customise these files as much or as little as required or desired. You do not have to honour parameter settings if you don't want to.
=== Overriding Sub-Layouts ===

In some views you will see that some of the layouts have a group of files that start with the same name. The category view has an example of this. The blog layout actually has three parts: the main layout file blog.php and two sub-layout files, blog_item.php and blog_links.php. You can see where these sub-layouts are loaded in the blog.php file using the loadTemplate method, for example:
<source lang="php">
echo $this->loadTemplate('item');
// or
echo $this->loadTemplate('links');
</source>
When loading sub-layouts, the view already knows what layout you are in, so you don't have to provide the prefix (that is, you load just 'item', not 'blog_item').

What is important to note here is that it is possible to override just a sub-layout without copying the whole set of files. For example, if you were happy with the "Joomla!" default output for the blog layout, but just wanted to customise the item sub-layout, you could just copy:

/components/com_content/views/category/tmpl/blog_item.php

to:

/templates/rhuk_milkyway/html/com_content/category/blog_item.php

When "Joomla!" is parsing the view, it will automatically know to load blog.php from com_content natively and blog_item.php from your template overrides.
== Module Layout Overrides ==

Modules, like components, are set up in a particular directory structure.
<pre>
/modules
/mod_latest_news
/tmpl
default.php (the layout)
helper.php (a helper file containing data logic)
mod_latest_news.php (the main module file)
mod_latest_news.xml (the installation XML file)
</pre>
Similar to components, under the main module directory (in the example, mod_latest_news) there is a /tmpl/ directory. There is usually only one layout file but depending on who wrote the module, and how it is written, there could be more.

As for components, the layout override for a module must be placed in particular way. Using Beez as an example again, you will see the following structure:
<pre>
/templates
/beez
/html
/mod_latest_news.php (this directory matches the module directory name)
default.php (this file matches the layout file name)
</pre>
The structure for module overrides is again quite simple: /html/mod_module_name/layout_file_name.php.
=== Copying or Creating Layout Files ===

The rhuk_milkyway template does not have any layout overrides for any modules. If we want to override the default layout for Latest News module, we need to copy this file:

/components/mod_latest_news/default.php

to this location, creating the approriate directories in the event they don't already exist:

/templates/rhuk_milkyway/html/mod_latest_news/default.php

You need to take a little care with overriding module layout because there are a number of different ways that modules can or have been designed so you need to treat each one individually.
== Module Chrome ==

"Joomla!" 1.0 had a number of fixed styles that could display a list of modules in a particular position. These where represented by numbers:

* 0 (the default) displayed modules in a vertical table
* 1 displayed them in a horizontal table
* -1 displayed the raw module output
* -2 displayed the modules in a XHTML compatible format with the title in a H3 tag.
* -3 displayed modules in a set of nested DIVs that allowed for rounded-corner techniques

It was a great system except for two things:

# Nobody could remember which number was which, and
# You couldn't expand on the styles.

Well, in 1.5, the numbers are still recognised, but more commonly the style is represented as a word. As well as that, the syntax for displaying a module position was changed. For example, this snippet displays each module in the left position in the xhtml style:
<source lang="php">
<jdoc:include type="modules" name="left" style="xhtml" />
</source>
The built-in styles that are now available are:

* table (was 0 and is the default)
* horz (was 1)
* none (was -1)
* xhtml (was -2)
* rounded (was -3)
* outline (new - used to preview module positions - see screenshot above)

In the source code, these styles are actually referred to ask "chrome". The default chrome can actually be found in the system template provided in the default "Joomla!" install:

/templates/system/html/modules.php

This file is maintained by the project so you should never modify it directly otherwise there is a risk that you will loose your changes if and when you upgrade your "Joomla!" installation.

To create your own chrome, or module styles, all you need to do is create or edit modules.php under the templates /html/ directory (this is the same directory we have been talking about for component and module layout overrides).

The rhuk_milkyway template actually does provide some extra chrome as an example (it provides and new example style called "slider"). This can be found in the following file:

/templates/rhuk_milkyway/html/modules.php

To create your own chrome is really easy. Let's look at ficticious example that displays the module in a Definition List (a set of DL's, DT's and DD's).

Just add the following function to the /html/modules.php file in your default template directory (create it if it does not exist):
<source lang="php">
/*
* Module chrome that wraps the module in a definition list
*/
function modChrome_dlist($module, &$params, &$attribs)
{ ?>
<dl class="<?php echo $params->get('moduleclass_sfx'); ?>">
<?php if ($module->showtitle != 0) : ?>
<dt>
<?php echo $module->title; ?>
</dt>
<?php endif; ?>
<dd>
<?php echo $module->content; ?>
</dd>
</dl>
<?php
}
</source>
We will be calling the style "dlist", so the name of the function needs to be modChrome_dlist.

The function must take the three arguments as shown for the module object, the module parameters, and lastly the $attribs is an array of all the attributes in the jdoc XML tag.

There are three main properties in the module object to be concerned with:

* showtitle tells you whether to show the title of the module of not
* title is the title of the module
* content is the output of the module (from its layout)

This is a very simple case and you can of course design more complex styles, possibly using custom atrributes in the XML tag.
== Pagination Links Overrides ==

The final override we will look at is the pagination override. This override can control the display of items-per-page and the pagination links that are used with lists of information, as shown in the following screenshot.

[[Image:Article_list_pagination.png|Typical Joomla! page showing a paginated list.]]

The rhuk_milkyway template provides a well commented example for this override. The file is found here:

/templates/rhuk_milkyway/html/pagination.php

When the pagination list is required, "Joomla!" will look for this file in the default templates. If it is found it will be loaded and the display functions it contains will be used.

There are four functions that can be used:

pagination_list_footer

This function is responsible for showing the select list for the number of items to display per page.

pagination_list_render

This function is responsible for showing the list of page number links as well at the Start, End, Previous and Next links.

pagination_item_active

This function displays the links to other page numbers other than the "current" page.

pagination_item_active

This function displays the current page number, usually not hyperlinked.

== Cheat Sheet ==

Using the rhuk_milkyway template as an example, here is a brief summary of the priniciples we've looked at.
=== Customise the Component Output ===

To override a component layout (for example the default layout in the article view), copy:

/components/com_content/views/article/tmpl/default.php

to:

/templates/rhuk_milkyway/html/com_content/article/default.php

Read more about [[#Component Output Types and Layout Overrides|component output]].

=== Customise the Module Output ===

To override a module layout (for example the Latest News module using the rhuk_milkyway template), copy:

/components/mod_latest_news/default.php

to:

/templates/rhuk_milkyway/html/mod_latest_news/default.php

Read more about [[#Module Layout Overrides|module output]].

=== Add New Module Styles ===

To add new module styles (chrome), add them to the following file:

/templates/rhuk_milkyway/html/modules.php

Read more about [[#Module Chrome|module chrome]].

=== Customise the Pagination Links ===

To customise the way the items-per-page selector and pagination links display, edit the following file:

/templates/rhuk_milkyway/html/pagination.php

Read more about [[#Pagination Links Overrides|pagination]].

== Conclusion ==

"Joomla!" 1.5, through the use of an MVC paradigm has greatly improved the flexibility that is afforded to Web site designers. By way of a few simple principles, like copying certain files to certain places in your template, the designer is able to override almost all of the output generated by "Joomla!".

If you have any questions relating to output overrides please let us know so that we can improve this tutorial.

If you have translated this article into another language, please let us know.

Understanding Output Overrides

2008-07-05T14:28:47Z

Instance: /* Customise the Component Output */

= Understanding Output Overrides in "Joomla!" 1.5 =
Written by Andrew Eddie

This was Developer Blog post by Andrew, initially copied to the wiki with minor edits by Alan Langford. This is still a work in progress.
== Introduction ==
There are many competing requirements for web designers ranging from accessibility to legislative to personal preferences. Rather than trying to over-parameterise views, or trying to aim for some sort of line of best fit, or worse, sticking its head in the sand, "Joomla!" has added the potential for the designer to take over control of virtually all of the output that is generated.

"Joomla!" has been criticized by some for not giving due attention to accessibility or being archaic in their approach to web standards. However with 1.5, the responsibility, but more importantly the power is back in the designer's hands.

In addition, except for files that are provided in the "Joomla!" distribution itself, these methods for customisation eliminate the need for designers and developers to "hack" core files that could change when the site is updated to a new version. Because they are contained within the template, they can be deployed to the Web site without having to worry about changes being accidentally overwritten when your System Administrator upgrades the site.

The aim of this tutorial is to introduce the how fours areas of the output of "Joomla!" are able to be customised by the template designer.

Not interested in all the theory? Jump straight to the cheat sheet.
== MVC 101 ==
MVC can be a scary acronym. It stands for Model-View-Controller and the concepts behind MVC are responsible for the extra flexibility that is now afforded to the designer. While parts of the theory can be rather involved and complicated, the only part that the designer need worry about is the V for View. This is the part that is concerned with output.

Different extensions display output in different ways.

Components, as you would already know, are fairly complex and have the ability to display different information in different ways. For example, the Articles Component (com_content) is able to display a single article, or articles in a category, or categories in a section. Each of the ways of representing the different types of data (an article, or a category, or a section) is called a "view" (this comes from our MVC terminology). Most components will have many views. However, the view doesn't actually display the output. This is left up to what we call a "layout" and it is possible for a view to have a variety of layouts.

The main thing to remember here is that components can have multiple views, and each view can have one or more layouts. Each view assembles a fixed set of information, but each layout can display that information in different ways. For example, the Category view in the Articles component assembles a number of articles. These articles could be displayed in a list or in a table (and probably other ways as well). So this view may have a "list" layout and a "table" layout to choose from.

Modules, on the other hand, are very simple. They generally display one thing one way. Modules don't really have views but they do support a layout. Some developers might even support a choice of layout through module parameters.
=== Template versus Layout ===

It is very important to distinguish between the role of template and the role of layouts. The template sets up a structural framework for the page of the Web site. Within this framework are positions for modules and a component to display. What actually gets displayed is governed by the module layout, or the combination of view and layout in the case of the component.

The following image shows the structural layout of a typical "Joomla!" template (rhuk_milkyway, the default for 1.5). The module positions are displayed by adding tp=1 to the URL (eg, index.php?tp=1). You can clearly see where the module output is contained within the overall template, as well as the main component output starting in the lower-centre region. However, what is actually output in those regions, is controlled by the layouts.

[[Image:FrontpageTemplatePositions.png|Typical Joomla! screenshot with template positions shown.]]

=== Ancillary Customisation ===

While not strictly related to the MVC, there are two other important areas to consider when looking at customising the output of "Joomla!".

In addition to layouts, modules have what we call "chrome". Chrome is the style with which a module is to display. Most developers, designers and probably some end-users will be familiar with the different built-in styles for modules (raw, xhtml, etc). It is also possible to define your own chrome styles for modules depending on the designer result. For example, you could design a chrome to display all the modules in a particular position in a fancy Javascript collapsing blind arrangement.

In the screenshot above, you can just make out the names of some of the built-in module chrome used (rounded, none and xhtml).

The second area has to do with controlling the pagination controls when viewing lists of data. We will look at that in more detail later.
== Component Output Types and Layout Overrides ==

To understand layout overrides we must first understand the file structure of a component. While there are many parts to a component, all fulfilling different roles and responsibilities, we want to look just in the /views/ directory. Here is the partial structure for two of the com_content views:
<pre>
/components
/com_content
/views
/articles
/tmpl
default.php (this is a layout)
form.php (this is a layout)
view.html.php (this is the view that outputs the HTML)
view.pdf.php (this is the view that outputs the PDF)
/category
/tmpl
blog.php (layout)
blog_items.php (a sub-layout
default.php (layout)
view.html.php (HTML view)
view.feed.php (RSS feed)
</pre>
So what you see here is that under the /views/ directory, each view is placed in a directory of its own. The content component actually has three other views not shown: archive, frontpage and section.
=== Output Types ===
Under the /articles/ directory we have a number of files. There is almost always a file called view.html.php. This is what we call the view file, but there can be more than one depending on the type of output to produce. It has a specific naming convention, view.output_type.php, where the output type can be html, feed, pdf, raw or error (for more information see JDocument in the API reference and look in the directory /libraries/joomla/document/). What this means is when we want html output for this particular view, the view.html.php file is used. When we want the RSS output, the view.feed.php file is used.

The affect of these different output types is most apparent when the Global Configuration setting for Search Engine Friendly URLs is set to Yes, Use Apache mod_rewrite is set to Yes, and Add suffix to URLs is also set to Yes. When this is done, the site URLs will look something like this:

<pre>
http://domain/sports.html
http://domain/sports.feed
http://domain/sports/rowing.html
http://domain/sports/rowing.pdf
</pre>
The exact URL will vary depending on how you set up your site but the point here is to show that sports.html will use the category view's view.html.php file to, and that sports.feed will display the RSS feed for the category using view.feed.php. It should be noted that you cannot currently customise feed or PDF output types. However, you can customise the html output type and this is where layouts come into play.

=== Layouts ===
Under the view directory there is a /tmpl/ directory in which the layout files reside. Each PHP file in this directory represents a layout. For example, article/tmpl/default.php is the default layout for an article whereas article/tmpl/form.php is the edit form for an article; category/tmpl/default.php is the default layout for a category whereas category/tmpl/blog.php displays the list of article differently.

The relationship between component views and layout is most plainly seen when adding a new menu item. The next screenshot represents the typical display of the New Menu Item page. Having clicked on Articles (which represents com_content), the tree expands to show the list of views and each layout within the view.

[[Image:Menu_item_type_articles.png|Screenshot of creating a new menu item fro an article.]]

You will notice that while there are extra files in some of the /tmpl/ directories (like pagebreak.php in the article view), they are missing from the list. This is due to instructions in the XML file for the layout (for example, pagebreak.xml) to hide the layout (or even the view) from the menu item list. However, this is another broad topic which will be covered in another tutorial.

Armed with all that knowledge of how all the parts relate to each other, we are now ready to actually create our layout overrides.

=== Copying or Creating Layout Files ===

Layout overrides only work within the active template and are located under the /html/ directory in the template. For example, the overrides for rhuk_milkyway are located under /templates/rhuk_milkyway/html/, for the JA Purity template under /templates/ja_purity/html/ and for Beez under /templates/beez/html/.

It is important to understand that if you create overrides in one template, they will not be available in other templates. For example, rhuk_milkyway has no component layout overrides at all. When you use this template you are seeing the raw output from all components. When you use the Beez template, almost every piece of component output is being controlled by the layout overrides in the template. JA Purity is in between having overrides for some components and only some views of those components.

The layout overrides must be placed in particular way. Using Beez as an example you will see the following structure:
<pre>
/templates
/beez
/html
/com_content (this directory matches the component directory name)
/articles (this directory matches the view directory name)
default.php (this file matches the layout file name)
form.php
</pre>

The structure for component overrides is quite simple: /html/com_component_name/view_name/layout_file_name.php. Let's look at a few examples.

The rhuk_milkyway template does not have any layout overrides for any components. If we want to override the default layout for an article, first we need to copy this file:

/components/com_content/views/article/tmpl/default.php

to this location, creating the appropriate directories in the event they don't already exist:

/templates/rhuk_milkyway/html/com_content/article/default.php

If we wanted to override the blog layout in the category view, we would copy this file:

/components/com_content/views/category/tmpl/blog.php

to:

/templates/rhuk_milkyway/html/com_content/category/blog.php

Once the files are copied, you are free to customise these files as much or as little as required or desired. You do not have to honour parameter settings if you don't want to.
=== Overriding Sub-Layouts ===

In some views you will see that some of the layouts have a group of files that start with the same name. The category view has an example of this. The blog layout actually has three parts: the main layout file blog.php and two sub-layout files, blog_item.php and blog_links.php. You can see where these sub-layouts are loaded in the blog.php file using the loadTemplate method, for example:
<source lang="php">
echo $this->loadTemplate('item');
// or
echo $this->loadTemplate('links');
</source>
When loading sub-layouts, the view already knows what layout you are in, so you don't have to provide the prefix (that is, you load just 'item', not 'blog_item').

What is important to note here is that it is possible to override just a sub-layout without copying the whole set of files. For example, if you were happy with the "Joomla!" default output for the blog layout, but just wanted to customise the item sub-layout, you could just copy:

/components/com_content/views/category/tmpl/blog_item.php

to:

/templates/rhuk_milkyway/html/com_content/category/blog_item.php

When "Joomla!" is parsing the view, it will automatically know to load blog.php from com_content natively and blog_item.php from your template overrides.
== Module Layout Overrides ==

Modules, like components, are set up in a particular directory structure.
<pre>
/modules
/mod_latest_news
/tmpl
default.php (the layout)
helper.php (a helper file containing data logic)
mod_latest_news.php (the main module file)
mod_latest_news.xml (the installation XML file)
</pre>
Similar to components, under the main module directory (in the example, mod_latest_news) there is a /tmpl/ directory. There is usually only one layout file but depending on who wrote the module, and how it is written, there could be more.

As for components, the layout override for a module must be placed in particular way. Using Beez as an example again, you will see the following structure:
<pre>
/templates
/beez
/html
/mod_latest_news.php (this directory matches the module directory name)
default.php (this file matches the layout file name)
</pre>
The structure for module overrides is again quite simple: /html/mod_module_name/layout_file_name.php.
=== Copying or Creating Layout Files ===

The rhuk_milkyway template does not have any layout overrides for any modules. If we want to override the default layout for Latest News module, we need to copy this file:

/components/mod_latest_news/default.php

to this location, creating the approriate directories in the event they don't already exist:

/templates/rhuk_milkyway/html/mod_latest_news/default.php

You need to take a little care with overriding module layout because there are a number of different ways that modules can or have been designed so you need to treat each one individually.
== Module Chrome ==

"Joomla!" 1.0 had a number of fixed styles that could display a list of modules in a particular position. These where represented by numbers:

* 0 (the default) displayed modules in a vertical table
* 1 displayed them in a horizontal table
* -1 displayed the raw module output
* -2 displayed the modules in a XHTML compatible format with the title in a H3 tag.
* -3 displayed modules in a set of nested DIVs that allowed for rounded-corner techniques

It was a great system except for two things:

# Nobody could remember which number was which, and
# You couldn't expand on the styles.

Well, in 1.5, the numbers are still recognised, but more commonly the style is represented as a word. As well as that, the syntax for displaying a module position was changed. For example, this snippet displays each module in the left position in the xhtml style:
<source lang="php">
<jdoc:include type="modules" name="left" style="xhtml" />
</source>
The built-in styles that are now available are:

* table (was 0 and is the default)
* horz (was 1)
* none (was -1)
* xhtml (was -2)
* rounded (was -3)
* outline (new - used to preview module positions - see screenshot above)

In the source code, these styles are actually referred to ask "chrome". The default chrome can actually be found in the system template provided in the default "Joomla!" install:

/templates/system/html/modules.php

This file is maintained by the project so you should never modify it directly otherwise there is a risk that you will loose your changes if and when you upgrade your "Joomla!" installation.

To create your own chrome, or module styles, all you need to do is create or edit modules.php under the templates /html/ directory (this is the same directory we have been talking about for component and module layout overrides).

The rhuk_milkyway template actually does provide some extra chrome as an example (it provides and new example style called "slider"). This can be found in the following file:

/templates/rhuk_milkyway/html/modules.php

To create your own chrome is really easy. Let's look at ficticious example that displays the module in a Definition List (a set of DL's, DT's and DD's).

Just add the following function to the /html/modules.php file in your default template directory (create it if it does not exist):
<source lang="php">
/*
* Module chrome that wraps the module in a definition list
*/
function modChrome_dlist($module, &$params, &$attribs)
{ ?>
<dl class="<?php echo $params->get('moduleclass_sfx'); ?>">
<?php if ($module->showtitle != 0) : ?>
<dt>
<?php echo $module->title; ?>
</dt>
<?php endif; ?>
<dd>
<?php echo $module->content; ?>
</dd>
</dl>
<?php
}
</source>
We will be calling the style "dlist", so the name of the function needs to be modChrome_dlist.

The function must take the three arguments as shown for the module object, the module parameters, and lastly the $attribs is an array of all the attributes in the jdoc XML tag.

There are three main properties in the module object to be concerned with:

* showtitle tells you whether to show the title of the module of not
* title is the title of the module
* content is the output of the module (from its layout)

This is a very simple case and you can of course design more complex styles, possibly using custom atrributes in the XML tag.
== Pagination Links Overrides ==

The final override we will look at is the pagination override. This override can control the display of items-per-page and the pagination links that are used with lists of information, as shown in the following screenshot.

[[Image:Article_list_pagination.png|Typical Joomla! page showing a paginated list.]]

The rhuk_milkyway template provides a well commented example for this override. The file is found here:

/templates/rhuk_milkyway/html/pagination.php

When the pagination list is required, "Joomla!" will look for this file in the default templates. If it is found it will be loaded and the display functions it contains will be used.

There are four functions that can be used:

pagination_list_footer

This function is responsible for showing the select list for the number of items to display per page.

pagination_list_render

This function is responsible for showing the list of page number links as well at the Start, End, Previous and Next links.

pagination_item_active

This function displays the links to other page numbers other than the "current" page.

pagination_item_active

This function displays the current page number, usually not hyperlinked.

== Cheat Sheet ==

Using the rhuk_milkyway template as an example, here is a brief summary of the priniciples we've looked at.
=== Customise the Component Output ===

To override a component layout (for example the default layout in the article view), copy:

/components/com_content/views/article/tmpl/default.php

to:

/templates/rhuk_milkyway/html/com_content/article/default.php

Read more about [[#Component Output Types and Layout Override|component output]].

=== Customise the Module Output ===

To override a module layout (for example the Latest News module using the rhuk_milkyway template), copy:

/components/mod_latest_news/default.php

to:

/templates/rhuk_milkyway/html/mod_latest_news/default.php

Read more about [[#Module Layout Overrides|module output]].

=== Add New Module Styles ===

To add new module styles (chrome), add them to the following file:

/templates/rhuk_milkyway/html/modules.php

Read more about [[#Module Chrome|module chrome]].

=== Customise the Pagination Links ===

To customise the way the items-per-page selector and pagination links display, edit the following file:

/templates/rhuk_milkyway/html/pagination.php

Read more about [[#Pagination Links Overrides|pagination]].

== Conclusion ==

"Joomla!" 1.5, through the use of an MVC paradigm has greatly improved the flexibility that is afforded to Web site designers. By way of a few simple principles, like copying certain files to certain places in your template, the designer is able to override almost all of the output generated by "Joomla!".

If you have any questions relating to output overrides please let us know so that we can improve this tutorial.

If you have translated this article into another language, please let us know.

Understanding Output Overrides

2008-07-05T14:27:27Z

Instance: /* Customise the Module Output */

= Understanding Output Overrides in "Joomla!" 1.5 =
Written by Andrew Eddie

This was Developer Blog post by Andrew, initially copied to the wiki with minor edits by Alan Langford. This is still a work in progress.
== Introduction ==
There are many competing requirements for web designers ranging from accessibility to legislative to personal preferences. Rather than trying to over-parameterise views, or trying to aim for some sort of line of best fit, or worse, sticking its head in the sand, "Joomla!" has added the potential for the designer to take over control of virtually all of the output that is generated.

"Joomla!" has been criticized by some for not giving due attention to accessibility or being archaic in their approach to web standards. However with 1.5, the responsibility, but more importantly the power is back in the designer's hands.

In addition, except for files that are provided in the "Joomla!" distribution itself, these methods for customisation eliminate the need for designers and developers to "hack" core files that could change when the site is updated to a new version. Because they are contained within the template, they can be deployed to the Web site without having to worry about changes being accidentally overwritten when your System Administrator upgrades the site.

The aim of this tutorial is to introduce the how fours areas of the output of "Joomla!" are able to be customised by the template designer.

Not interested in all the theory? Jump straight to the cheat sheet.
== MVC 101 ==
MVC can be a scary acronym. It stands for Model-View-Controller and the concepts behind MVC are responsible for the extra flexibility that is now afforded to the designer. While parts of the theory can be rather involved and complicated, the only part that the designer need worry about is the V for View. This is the part that is concerned with output.

Different extensions display output in different ways.

Components, as you would already know, are fairly complex and have the ability to display different information in different ways. For example, the Articles Component (com_content) is able to display a single article, or articles in a category, or categories in a section. Each of the ways of representing the different types of data (an article, or a category, or a section) is called a "view" (this comes from our MVC terminology). Most components will have many views. However, the view doesn't actually display the output. This is left up to what we call a "layout" and it is possible for a view to have a variety of layouts.

The main thing to remember here is that components can have multiple views, and each view can have one or more layouts. Each view assembles a fixed set of information, but each layout can display that information in different ways. For example, the Category view in the Articles component assembles a number of articles. These articles could be displayed in a list or in a table (and probably other ways as well). So this view may have a "list" layout and a "table" layout to choose from.

Modules, on the other hand, are very simple. They generally display one thing one way. Modules don't really have views but they do support a layout. Some developers might even support a choice of layout through module parameters.
=== Template versus Layout ===

It is very important to distinguish between the role of template and the role of layouts. The template sets up a structural framework for the page of the Web site. Within this framework are positions for modules and a component to display. What actually gets displayed is governed by the module layout, or the combination of view and layout in the case of the component.

The following image shows the structural layout of a typical "Joomla!" template (rhuk_milkyway, the default for 1.5). The module positions are displayed by adding tp=1 to the URL (eg, index.php?tp=1). You can clearly see where the module output is contained within the overall template, as well as the main component output starting in the lower-centre region. However, what is actually output in those regions, is controlled by the layouts.

[[Image:FrontpageTemplatePositions.png|Typical Joomla! screenshot with template positions shown.]]

=== Ancillary Customisation ===

While not strictly related to the MVC, there are two other important areas to consider when looking at customising the output of "Joomla!".

In addition to layouts, modules have what we call "chrome". Chrome is the style with which a module is to display. Most developers, designers and probably some end-users will be familiar with the different built-in styles for modules (raw, xhtml, etc). It is also possible to define your own chrome styles for modules depending on the designer result. For example, you could design a chrome to display all the modules in a particular position in a fancy Javascript collapsing blind arrangement.

In the screenshot above, you can just make out the names of some of the built-in module chrome used (rounded, none and xhtml).

The second area has to do with controlling the pagination controls when viewing lists of data. We will look at that in more detail later.
== Component Output Types and Layout Overrides ==

To understand layout overrides we must first understand the file structure of a component. While there are many parts to a component, all fulfilling different roles and responsibilities, we want to look just in the /views/ directory. Here is the partial structure for two of the com_content views:
<pre>
/components
/com_content
/views
/articles
/tmpl
default.php (this is a layout)
form.php (this is a layout)
view.html.php (this is the view that outputs the HTML)
view.pdf.php (this is the view that outputs the PDF)
/category
/tmpl
blog.php (layout)
blog_items.php (a sub-layout
default.php (layout)
view.html.php (HTML view)
view.feed.php (RSS feed)
</pre>
So what you see here is that under the /views/ directory, each view is placed in a directory of its own. The content component actually has three other views not shown: archive, frontpage and section.
=== Output Types ===
Under the /articles/ directory we have a number of files. There is almost always a file called view.html.php. This is what we call the view file, but there can be more than one depending on the type of output to produce. It has a specific naming convention, view.output_type.php, where the output type can be html, feed, pdf, raw or error (for more information see JDocument in the API reference and look in the directory /libraries/joomla/document/). What this means is when we want html output for this particular view, the view.html.php file is used. When we want the RSS output, the view.feed.php file is used.

The affect of these different output types is most apparent when the Global Configuration setting for Search Engine Friendly URLs is set to Yes, Use Apache mod_rewrite is set to Yes, and Add suffix to URLs is also set to Yes. When this is done, the site URLs will look something like this:

<pre>
http://domain/sports.html
http://domain/sports.feed
http://domain/sports/rowing.html
http://domain/sports/rowing.pdf
</pre>
The exact URL will vary depending on how you set up your site but the point here is to show that sports.html will use the category view's view.html.php file to, and that sports.feed will display the RSS feed for the category using view.feed.php. It should be noted that you cannot currently customise feed or PDF output types. However, you can customise the html output type and this is where layouts come into play.

=== Layouts ===
Under the view directory there is a /tmpl/ directory in which the layout files reside. Each PHP file in this directory represents a layout. For example, article/tmpl/default.php is the default layout for an article whereas article/tmpl/form.php is the edit form for an article; category/tmpl/default.php is the default layout for a category whereas category/tmpl/blog.php displays the list of article differently.

The relationship between component views and layout is most plainly seen when adding a new menu item. The next screenshot represents the typical display of the New Menu Item page. Having clicked on Articles (which represents com_content), the tree expands to show the list of views and each layout within the view.

[[Image:Menu_item_type_articles.png|Screenshot of creating a new menu item fro an article.]]

You will notice that while there are extra files in some of the /tmpl/ directories (like pagebreak.php in the article view), they are missing from the list. This is due to instructions in the XML file for the layout (for example, pagebreak.xml) to hide the layout (or even the view) from the menu item list. However, this is another broad topic which will be covered in another tutorial.

Armed with all that knowledge of how all the parts relate to each other, we are now ready to actually create our layout overrides.

=== Copying or Creating Layout Files ===

Layout overrides only work within the active template and are located under the /html/ directory in the template. For example, the overrides for rhuk_milkyway are located under /templates/rhuk_milkyway/html/, for the JA Purity template under /templates/ja_purity/html/ and for Beez under /templates/beez/html/.

It is important to understand that if you create overrides in one template, they will not be available in other templates. For example, rhuk_milkyway has no component layout overrides at all. When you use this template you are seeing the raw output from all components. When you use the Beez template, almost every piece of component output is being controlled by the layout overrides in the template. JA Purity is in between having overrides for some components and only some views of those components.

The layout overrides must be placed in particular way. Using Beez as an example you will see the following structure:
<pre>
/templates
/beez
/html
/com_content (this directory matches the component directory name)
/articles (this directory matches the view directory name)
default.php (this file matches the layout file name)
form.php
</pre>

The structure for component overrides is quite simple: /html/com_component_name/view_name/layout_file_name.php. Let's look at a few examples.

The rhuk_milkyway template does not have any layout overrides for any components. If we want to override the default layout for an article, first we need to copy this file:

/components/com_content/views/article/tmpl/default.php

to this location, creating the appropriate directories in the event they don't already exist:

/templates/rhuk_milkyway/html/com_content/article/default.php

If we wanted to override the blog layout in the category view, we would copy this file:

/components/com_content/views/category/tmpl/blog.php

to:

/templates/rhuk_milkyway/html/com_content/category/blog.php

Once the files are copied, you are free to customise these files as much or as little as required or desired. You do not have to honour parameter settings if you don't want to.
=== Overriding Sub-Layouts ===

In some views you will see that some of the layouts have a group of files that start with the same name. The category view has an example of this. The blog layout actually has three parts: the main layout file blog.php and two sub-layout files, blog_item.php and blog_links.php. You can see where these sub-layouts are loaded in the blog.php file using the loadTemplate method, for example:
<source lang="php">
echo $this->loadTemplate('item');
// or
echo $this->loadTemplate('links');
</source>
When loading sub-layouts, the view already knows what layout you are in, so you don't have to provide the prefix (that is, you load just 'item', not 'blog_item').

What is important to note here is that it is possible to override just a sub-layout without copying the whole set of files. For example, if you were happy with the "Joomla!" default output for the blog layout, but just wanted to customise the item sub-layout, you could just copy:

/components/com_content/views/category/tmpl/blog_item.php

to:

/templates/rhuk_milkyway/html/com_content/category/blog_item.php

When "Joomla!" is parsing the view, it will automatically know to load blog.php from com_content natively and blog_item.php from your template overrides.
== Module Layout Overrides ==

Modules, like components, are set up in a particular directory structure.
<pre>
/modules
/mod_latest_news
/tmpl
default.php (the layout)
helper.php (a helper file containing data logic)
mod_latest_news.php (the main module file)
mod_latest_news.xml (the installation XML file)
</pre>
Similar to components, under the main module directory (in the example, mod_latest_news) there is a /tmpl/ directory. There is usually only one layout file but depending on who wrote the module, and how it is written, there could be more.

As for components, the layout override for a module must be placed in particular way. Using Beez as an example again, you will see the following structure:
<pre>
/templates
/beez
/html
/mod_latest_news.php (this directory matches the module directory name)
default.php (this file matches the layout file name)
</pre>
The structure for module overrides is again quite simple: /html/mod_module_name/layout_file_name.php.
=== Copying or Creating Layout Files ===

The rhuk_milkyway template does not have any layout overrides for any modules. If we want to override the default layout for Latest News module, we need to copy this file:

/components/mod_latest_news/default.php

to this location, creating the approriate directories in the event they don't already exist:

/templates/rhuk_milkyway/html/mod_latest_news/default.php

You need to take a little care with overriding module layout because there are a number of different ways that modules can or have been designed so you need to treat each one individually.
== Module Chrome ==

"Joomla!" 1.0 had a number of fixed styles that could display a list of modules in a particular position. These where represented by numbers:

* 0 (the default) displayed modules in a vertical table
* 1 displayed them in a horizontal table
* -1 displayed the raw module output
* -2 displayed the modules in a XHTML compatible format with the title in a H3 tag.
* -3 displayed modules in a set of nested DIVs that allowed for rounded-corner techniques

It was a great system except for two things:

# Nobody could remember which number was which, and
# You couldn't expand on the styles.

Well, in 1.5, the numbers are still recognised, but more commonly the style is represented as a word. As well as that, the syntax for displaying a module position was changed. For example, this snippet displays each module in the left position in the xhtml style:
<source lang="php">
<jdoc:include type="modules" name="left" style="xhtml" />
</source>
The built-in styles that are now available are:

* table (was 0 and is the default)
* horz (was 1)
* none (was -1)
* xhtml (was -2)
* rounded (was -3)
* outline (new - used to preview module positions - see screenshot above)

In the source code, these styles are actually referred to ask "chrome". The default chrome can actually be found in the system template provided in the default "Joomla!" install:

/templates/system/html/modules.php

This file is maintained by the project so you should never modify it directly otherwise there is a risk that you will loose your changes if and when you upgrade your "Joomla!" installation.

To create your own chrome, or module styles, all you need to do is create or edit modules.php under the templates /html/ directory (this is the same directory we have been talking about for component and module layout overrides).

The rhuk_milkyway template actually does provide some extra chrome as an example (it provides and new example style called "slider"). This can be found in the following file:

/templates/rhuk_milkyway/html/modules.php

To create your own chrome is really easy. Let's look at ficticious example that displays the module in a Definition List (a set of DL's, DT's and DD's).

Just add the following function to the /html/modules.php file in your default template directory (create it if it does not exist):
<source lang="php">
/*
* Module chrome that wraps the module in a definition list
*/
function modChrome_dlist($module, &$params, &$attribs)
{ ?>
<dl class="<?php echo $params->get('moduleclass_sfx'); ?>">
<?php if ($module->showtitle != 0) : ?>
<dt>
<?php echo $module->title; ?>
</dt>
<?php endif; ?>
<dd>
<?php echo $module->content; ?>
</dd>
</dl>
<?php
}
</source>
We will be calling the style "dlist", so the name of the function needs to be modChrome_dlist.

The function must take the three arguments as shown for the module object, the module parameters, and lastly the $attribs is an array of all the attributes in the jdoc XML tag.

There are three main properties in the module object to be concerned with:

* showtitle tells you whether to show the title of the module of not
* title is the title of the module
* content is the output of the module (from its layout)

This is a very simple case and you can of course design more complex styles, possibly using custom atrributes in the XML tag.
== Pagination Links Overrides ==

The final override we will look at is the pagination override. This override can control the display of items-per-page and the pagination links that are used with lists of information, as shown in the following screenshot.

[[Image:Article_list_pagination.png|Typical Joomla! page showing a paginated list.]]

The rhuk_milkyway template provides a well commented example for this override. The file is found here:

/templates/rhuk_milkyway/html/pagination.php

When the pagination list is required, "Joomla!" will look for this file in the default templates. If it is found it will be loaded and the display functions it contains will be used.

There are four functions that can be used:

pagination_list_footer

This function is responsible for showing the select list for the number of items to display per page.

pagination_list_render

This function is responsible for showing the list of page number links as well at the Start, End, Previous and Next links.

pagination_item_active

This function displays the links to other page numbers other than the "current" page.

pagination_item_active

This function displays the current page number, usually not hyperlinked.

== Cheat Sheet ==

Using the rhuk_milkyway template as an example, here is a brief summary of the priniciples we've looked at.
=== Customise the Component Output ===

To override a component layout (for example the default layout in the article view), copy:

/components/com_content/views/article/tmpl/default.php

to:

/templates/rhuk_milkyway/html/com_content/article/default.php

Read more about component output.
=== Customise the Module Output ===

To override a module layout (for example the Latest News module using the rhuk_milkyway template), copy:

/components/mod_latest_news/default.php

to:

/templates/rhuk_milkyway/html/mod_latest_news/default.php

Read more about [[#Module Layout Overrides|module output]].

=== Add New Module Styles ===

To add new module styles (chrome), add them to the following file:

/templates/rhuk_milkyway/html/modules.php

Read more about [[#Module Chrome|module chrome]].

=== Customise the Pagination Links ===

To customise the way the items-per-page selector and pagination links display, edit the following file:

/templates/rhuk_milkyway/html/pagination.php

Read more about [[#Pagination Links Overrides|pagination]].

== Conclusion ==

"Joomla!" 1.5, through the use of an MVC paradigm has greatly improved the flexibility that is afforded to Web site designers. By way of a few simple principles, like copying certain files to certain places in your template, the designer is able to override almost all of the output generated by "Joomla!".

If you have any questions relating to output overrides please let us know so that we can improve this tutorial.

If you have translated this article into another language, please let us know.

Understanding Output Overrides

2008-07-05T14:25:51Z

Instance: /* Add New Module Styles */

= Understanding Output Overrides in "Joomla!" 1.5 =
Written by Andrew Eddie

This was Developer Blog post by Andrew, initially copied to the wiki with minor edits by Alan Langford. This is still a work in progress.
== Introduction ==
There are many competing requirements for web designers ranging from accessibility to legislative to personal preferences. Rather than trying to over-parameterise views, or trying to aim for some sort of line of best fit, or worse, sticking its head in the sand, "Joomla!" has added the potential for the designer to take over control of virtually all of the output that is generated.

"Joomla!" has been criticized by some for not giving due attention to accessibility or being archaic in their approach to web standards. However with 1.5, the responsibility, but more importantly the power is back in the designer's hands.

In addition, except for files that are provided in the "Joomla!" distribution itself, these methods for customisation eliminate the need for designers and developers to "hack" core files that could change when the site is updated to a new version. Because they are contained within the template, they can be deployed to the Web site without having to worry about changes being accidentally overwritten when your System Administrator upgrades the site.

The aim of this tutorial is to introduce the how fours areas of the output of "Joomla!" are able to be customised by the template designer.

Not interested in all the theory? Jump straight to the cheat sheet.
== MVC 101 ==
MVC can be a scary acronym. It stands for Model-View-Controller and the concepts behind MVC are responsible for the extra flexibility that is now afforded to the designer. While parts of the theory can be rather involved and complicated, the only part that the designer need worry about is the V for View. This is the part that is concerned with output.

Different extensions display output in different ways.

Components, as you would already know, are fairly complex and have the ability to display different information in different ways. For example, the Articles Component (com_content) is able to display a single article, or articles in a category, or categories in a section. Each of the ways of representing the different types of data (an article, or a category, or a section) is called a "view" (this comes from our MVC terminology). Most components will have many views. However, the view doesn't actually display the output. This is left up to what we call a "layout" and it is possible for a view to have a variety of layouts.

The main thing to remember here is that components can have multiple views, and each view can have one or more layouts. Each view assembles a fixed set of information, but each layout can display that information in different ways. For example, the Category view in the Articles component assembles a number of articles. These articles could be displayed in a list or in a table (and probably other ways as well). So this view may have a "list" layout and a "table" layout to choose from.

Modules, on the other hand, are very simple. They generally display one thing one way. Modules don't really have views but they do support a layout. Some developers might even support a choice of layout through module parameters.
=== Template versus Layout ===

It is very important to distinguish between the role of template and the role of layouts. The template sets up a structural framework for the page of the Web site. Within this framework are positions for modules and a component to display. What actually gets displayed is governed by the module layout, or the combination of view and layout in the case of the component.

The following image shows the structural layout of a typical "Joomla!" template (rhuk_milkyway, the default for 1.5). The module positions are displayed by adding tp=1 to the URL (eg, index.php?tp=1). You can clearly see where the module output is contained within the overall template, as well as the main component output starting in the lower-centre region. However, what is actually output in those regions, is controlled by the layouts.

[[Image:FrontpageTemplatePositions.png|Typical Joomla! screenshot with template positions shown.]]

=== Ancillary Customisation ===

While not strictly related to the MVC, there are two other important areas to consider when looking at customising the output of "Joomla!".

In addition to layouts, modules have what we call "chrome". Chrome is the style with which a module is to display. Most developers, designers and probably some end-users will be familiar with the different built-in styles for modules (raw, xhtml, etc). It is also possible to define your own chrome styles for modules depending on the designer result. For example, you could design a chrome to display all the modules in a particular position in a fancy Javascript collapsing blind arrangement.

In the screenshot above, you can just make out the names of some of the built-in module chrome used (rounded, none and xhtml).

The second area has to do with controlling the pagination controls when viewing lists of data. We will look at that in more detail later.
== Component Output Types and Layout Overrides ==

To understand layout overrides we must first understand the file structure of a component. While there are many parts to a component, all fulfilling different roles and responsibilities, we want to look just in the /views/ directory. Here is the partial structure for two of the com_content views:
<pre>
/components
/com_content
/views
/articles
/tmpl
default.php (this is a layout)
form.php (this is a layout)
view.html.php (this is the view that outputs the HTML)
view.pdf.php (this is the view that outputs the PDF)
/category
/tmpl
blog.php (layout)
blog_items.php (a sub-layout
default.php (layout)
view.html.php (HTML view)
view.feed.php (RSS feed)
</pre>
So what you see here is that under the /views/ directory, each view is placed in a directory of its own. The content component actually has three other views not shown: archive, frontpage and section.
=== Output Types ===
Under the /articles/ directory we have a number of files. There is almost always a file called view.html.php. This is what we call the view file, but there can be more than one depending on the type of output to produce. It has a specific naming convention, view.output_type.php, where the output type can be html, feed, pdf, raw or error (for more information see JDocument in the API reference and look in the directory /libraries/joomla/document/). What this means is when we want html output for this particular view, the view.html.php file is used. When we want the RSS output, the view.feed.php file is used.

The affect of these different output types is most apparent when the Global Configuration setting for Search Engine Friendly URLs is set to Yes, Use Apache mod_rewrite is set to Yes, and Add suffix to URLs is also set to Yes. When this is done, the site URLs will look something like this:

<pre>
http://domain/sports.html
http://domain/sports.feed
http://domain/sports/rowing.html
http://domain/sports/rowing.pdf
</pre>
The exact URL will vary depending on how you set up your site but the point here is to show that sports.html will use the category view's view.html.php file to, and that sports.feed will display the RSS feed for the category using view.feed.php. It should be noted that you cannot currently customise feed or PDF output types. However, you can customise the html output type and this is where layouts come into play.

=== Layouts ===
Under the view directory there is a /tmpl/ directory in which the layout files reside. Each PHP file in this directory represents a layout. For example, article/tmpl/default.php is the default layout for an article whereas article/tmpl/form.php is the edit form for an article; category/tmpl/default.php is the default layout for a category whereas category/tmpl/blog.php displays the list of article differently.

The relationship between component views and layout is most plainly seen when adding a new menu item. The next screenshot represents the typical display of the New Menu Item page. Having clicked on Articles (which represents com_content), the tree expands to show the list of views and each layout within the view.

[[Image:Menu_item_type_articles.png|Screenshot of creating a new menu item fro an article.]]

You will notice that while there are extra files in some of the /tmpl/ directories (like pagebreak.php in the article view), they are missing from the list. This is due to instructions in the XML file for the layout (for example, pagebreak.xml) to hide the layout (or even the view) from the menu item list. However, this is another broad topic which will be covered in another tutorial.

Armed with all that knowledge of how all the parts relate to each other, we are now ready to actually create our layout overrides.

=== Copying or Creating Layout Files ===

Layout overrides only work within the active template and are located under the /html/ directory in the template. For example, the overrides for rhuk_milkyway are located under /templates/rhuk_milkyway/html/, for the JA Purity template under /templates/ja_purity/html/ and for Beez under /templates/beez/html/.

It is important to understand that if you create overrides in one template, they will not be available in other templates. For example, rhuk_milkyway has no component layout overrides at all. When you use this template you are seeing the raw output from all components. When you use the Beez template, almost every piece of component output is being controlled by the layout overrides in the template. JA Purity is in between having overrides for some components and only some views of those components.

The layout overrides must be placed in particular way. Using Beez as an example you will see the following structure:
<pre>
/templates
/beez
/html
/com_content (this directory matches the component directory name)
/articles (this directory matches the view directory name)
default.php (this file matches the layout file name)
form.php
</pre>

The structure for component overrides is quite simple: /html/com_component_name/view_name/layout_file_name.php. Let's look at a few examples.

The rhuk_milkyway template does not have any layout overrides for any components. If we want to override the default layout for an article, first we need to copy this file:

/components/com_content/views/article/tmpl/default.php

to this location, creating the appropriate directories in the event they don't already exist:

/templates/rhuk_milkyway/html/com_content/article/default.php

If we wanted to override the blog layout in the category view, we would copy this file:

/components/com_content/views/category/tmpl/blog.php

to:

/templates/rhuk_milkyway/html/com_content/category/blog.php

Once the files are copied, you are free to customise these files as much or as little as required or desired. You do not have to honour parameter settings if you don't want to.
=== Overriding Sub-Layouts ===

In some views you will see that some of the layouts have a group of files that start with the same name. The category view has an example of this. The blog layout actually has three parts: the main layout file blog.php and two sub-layout files, blog_item.php and blog_links.php. You can see where these sub-layouts are loaded in the blog.php file using the loadTemplate method, for example:
<source lang="php">
echo $this->loadTemplate('item');
// or
echo $this->loadTemplate('links');
</source>
When loading sub-layouts, the view already knows what layout you are in, so you don't have to provide the prefix (that is, you load just 'item', not 'blog_item').

What is important to note here is that it is possible to override just a sub-layout without copying the whole set of files. For example, if you were happy with the "Joomla!" default output for the blog layout, but just wanted to customise the item sub-layout, you could just copy:

/components/com_content/views/category/tmpl/blog_item.php

to:

/templates/rhuk_milkyway/html/com_content/category/blog_item.php

When "Joomla!" is parsing the view, it will automatically know to load blog.php from com_content natively and blog_item.php from your template overrides.
== Module Layout Overrides ==

Modules, like components, are set up in a particular directory structure.
<pre>
/modules
/mod_latest_news
/tmpl
default.php (the layout)
helper.php (a helper file containing data logic)
mod_latest_news.php (the main module file)
mod_latest_news.xml (the installation XML file)
</pre>
Similar to components, under the main module directory (in the example, mod_latest_news) there is a /tmpl/ directory. There is usually only one layout file but depending on who wrote the module, and how it is written, there could be more.

As for components, the layout override for a module must be placed in particular way. Using Beez as an example again, you will see the following structure:
<pre>
/templates
/beez
/html
/mod_latest_news.php (this directory matches the module directory name)
default.php (this file matches the layout file name)
</pre>
The structure for module overrides is again quite simple: /html/mod_module_name/layout_file_name.php.
=== Copying or Creating Layout Files ===

The rhuk_milkyway template does not have any layout overrides for any modules. If we want to override the default layout for Latest News module, we need to copy this file:

/components/mod_latest_news/default.php

to this location, creating the approriate directories in the event they don't already exist:

/templates/rhuk_milkyway/html/mod_latest_news/default.php

You need to take a little care with overriding module layout because there are a number of different ways that modules can or have been designed so you need to treat each one individually.
== Module Chrome ==

"Joomla!" 1.0 had a number of fixed styles that could display a list of modules in a particular position. These where represented by numbers:

* 0 (the default) displayed modules in a vertical table
* 1 displayed them in a horizontal table
* -1 displayed the raw module output
* -2 displayed the modules in a XHTML compatible format with the title in a H3 tag.
* -3 displayed modules in a set of nested DIVs that allowed for rounded-corner techniques

It was a great system except for two things:

# Nobody could remember which number was which, and
# You couldn't expand on the styles.

Well, in 1.5, the numbers are still recognised, but more commonly the style is represented as a word. As well as that, the syntax for displaying a module position was changed. For example, this snippet displays each module in the left position in the xhtml style:
<source lang="php">
<jdoc:include type="modules" name="left" style="xhtml" />
</source>
The built-in styles that are now available are:

* table (was 0 and is the default)
* horz (was 1)
* none (was -1)
* xhtml (was -2)
* rounded (was -3)
* outline (new - used to preview module positions - see screenshot above)

In the source code, these styles are actually referred to ask "chrome". The default chrome can actually be found in the system template provided in the default "Joomla!" install:

/templates/system/html/modules.php

This file is maintained by the project so you should never modify it directly otherwise there is a risk that you will loose your changes if and when you upgrade your "Joomla!" installation.

To create your own chrome, or module styles, all you need to do is create or edit modules.php under the templates /html/ directory (this is the same directory we have been talking about for component and module layout overrides).

The rhuk_milkyway template actually does provide some extra chrome as an example (it provides and new example style called "slider"). This can be found in the following file:

/templates/rhuk_milkyway/html/modules.php

To create your own chrome is really easy. Let's look at ficticious example that displays the module in a Definition List (a set of DL's, DT's and DD's).

Just add the following function to the /html/modules.php file in your default template directory (create it if it does not exist):
<source lang="php">
/*
* Module chrome that wraps the module in a definition list
*/
function modChrome_dlist($module, &$params, &$attribs)
{ ?>
<dl class="<?php echo $params->get('moduleclass_sfx'); ?>">
<?php if ($module->showtitle != 0) : ?>
<dt>
<?php echo $module->title; ?>
</dt>
<?php endif; ?>
<dd>
<?php echo $module->content; ?>
</dd>
</dl>
<?php
}
</source>
We will be calling the style "dlist", so the name of the function needs to be modChrome_dlist.

The function must take the three arguments as shown for the module object, the module parameters, and lastly the $attribs is an array of all the attributes in the jdoc XML tag.

There are three main properties in the module object to be concerned with:

* showtitle tells you whether to show the title of the module of not
* title is the title of the module
* content is the output of the module (from its layout)

This is a very simple case and you can of course design more complex styles, possibly using custom atrributes in the XML tag.
== Pagination Links Overrides ==

The final override we will look at is the pagination override. This override can control the display of items-per-page and the pagination links that are used with lists of information, as shown in the following screenshot.

[[Image:Article_list_pagination.png|Typical Joomla! page showing a paginated list.]]

The rhuk_milkyway template provides a well commented example for this override. The file is found here:

/templates/rhuk_milkyway/html/pagination.php

When the pagination list is required, "Joomla!" will look for this file in the default templates. If it is found it will be loaded and the display functions it contains will be used.

There are four functions that can be used:

pagination_list_footer

This function is responsible for showing the select list for the number of items to display per page.

pagination_list_render

This function is responsible for showing the list of page number links as well at the Start, End, Previous and Next links.

pagination_item_active

This function displays the links to other page numbers other than the "current" page.

pagination_item_active

This function displays the current page number, usually not hyperlinked.

== Cheat Sheet ==

Using the rhuk_milkyway template as an example, here is a brief summary of the priniciples we've looked at.
=== Customise the Component Output ===

To override a component layout (for example the default layout in the article view), copy:

/components/com_content/views/article/tmpl/default.php

to:

/templates/rhuk_milkyway/html/com_content/article/default.php

Read more about component output.
=== Customise the Module Output ===

To override a module layout (for example the Latest News module using the rhuk_milkyway template), copy:

/components/mod_latest_news/default.php

to:

/templates/rhuk_milkyway/html/mod_latest_news/default.php

Read more about module output.
=== Add New Module Styles ===

To add new module styles (chrome), add them to the following file:

/templates/rhuk_milkyway/html/modules.php

Read more about [[#Module Chrome|module chrome]].

=== Customise the Pagination Links ===

To customise the way the items-per-page selector and pagination links display, edit the following file:

/templates/rhuk_milkyway/html/pagination.php

Read more about [[#Pagination Links Overrides|pagination]].

== Conclusion ==

"Joomla!" 1.5, through the use of an MVC paradigm has greatly improved the flexibility that is afforded to Web site designers. By way of a few simple principles, like copying certain files to certain places in your template, the designer is able to override almost all of the output generated by "Joomla!".

If you have any questions relating to output overrides please let us know so that we can improve this tutorial.

If you have translated this article into another language, please let us know.

Understanding Output Overrides

2008-07-05T14:24:25Z

Instance: /* Customise the Pagination Links */

= Understanding Output Overrides in "Joomla!" 1.5 =
Written by Andrew Eddie

This was Developer Blog post by Andrew, initially copied to the wiki with minor edits by Alan Langford. This is still a work in progress.
== Introduction ==
There are many competing requirements for web designers ranging from accessibility to legislative to personal preferences. Rather than trying to over-parameterise views, or trying to aim for some sort of line of best fit, or worse, sticking its head in the sand, "Joomla!" has added the potential for the designer to take over control of virtually all of the output that is generated.

"Joomla!" has been criticized by some for not giving due attention to accessibility or being archaic in their approach to web standards. However with 1.5, the responsibility, but more importantly the power is back in the designer's hands.

In addition, except for files that are provided in the "Joomla!" distribution itself, these methods for customisation eliminate the need for designers and developers to "hack" core files that could change when the site is updated to a new version. Because they are contained within the template, they can be deployed to the Web site without having to worry about changes being accidentally overwritten when your System Administrator upgrades the site.

The aim of this tutorial is to introduce the how fours areas of the output of "Joomla!" are able to be customised by the template designer.

Not interested in all the theory? Jump straight to the cheat sheet.
== MVC 101 ==
MVC can be a scary acronym. It stands for Model-View-Controller and the concepts behind MVC are responsible for the extra flexibility that is now afforded to the designer. While parts of the theory can be rather involved and complicated, the only part that the designer need worry about is the V for View. This is the part that is concerned with output.

Different extensions display output in different ways.

Components, as you would already know, are fairly complex and have the ability to display different information in different ways. For example, the Articles Component (com_content) is able to display a single article, or articles in a category, or categories in a section. Each of the ways of representing the different types of data (an article, or a category, or a section) is called a "view" (this comes from our MVC terminology). Most components will have many views. However, the view doesn't actually display the output. This is left up to what we call a "layout" and it is possible for a view to have a variety of layouts.

The main thing to remember here is that components can have multiple views, and each view can have one or more layouts. Each view assembles a fixed set of information, but each layout can display that information in different ways. For example, the Category view in the Articles component assembles a number of articles. These articles could be displayed in a list or in a table (and probably other ways as well). So this view may have a "list" layout and a "table" layout to choose from.

Modules, on the other hand, are very simple. They generally display one thing one way. Modules don't really have views but they do support a layout. Some developers might even support a choice of layout through module parameters.
=== Template versus Layout ===

It is very important to distinguish between the role of template and the role of layouts. The template sets up a structural framework for the page of the Web site. Within this framework are positions for modules and a component to display. What actually gets displayed is governed by the module layout, or the combination of view and layout in the case of the component.

The following image shows the structural layout of a typical "Joomla!" template (rhuk_milkyway, the default for 1.5). The module positions are displayed by adding tp=1 to the URL (eg, index.php?tp=1). You can clearly see where the module output is contained within the overall template, as well as the main component output starting in the lower-centre region. However, what is actually output in those regions, is controlled by the layouts.

[[Image:FrontpageTemplatePositions.png|Typical Joomla! screenshot with template positions shown.]]

=== Ancillary Customisation ===

While not strictly related to the MVC, there are two other important areas to consider when looking at customising the output of "Joomla!".

In addition to layouts, modules have what we call "chrome". Chrome is the style with which a module is to display. Most developers, designers and probably some end-users will be familiar with the different built-in styles for modules (raw, xhtml, etc). It is also possible to define your own chrome styles for modules depending on the designer result. For example, you could design a chrome to display all the modules in a particular position in a fancy Javascript collapsing blind arrangement.

In the screenshot above, you can just make out the names of some of the built-in module chrome used (rounded, none and xhtml).

The second area has to do with controlling the pagination controls when viewing lists of data. We will look at that in more detail later.
== Component Output Types and Layout Overrides ==

To understand layout overrides we must first understand the file structure of a component. While there are many parts to a component, all fulfilling different roles and responsibilities, we want to look just in the /views/ directory. Here is the partial structure for two of the com_content views:
<pre>
/components
/com_content
/views
/articles
/tmpl
default.php (this is a layout)
form.php (this is a layout)
view.html.php (this is the view that outputs the HTML)
view.pdf.php (this is the view that outputs the PDF)
/category
/tmpl
blog.php (layout)
blog_items.php (a sub-layout
default.php (layout)
view.html.php (HTML view)
view.feed.php (RSS feed)
</pre>
So what you see here is that under the /views/ directory, each view is placed in a directory of its own. The content component actually has three other views not shown: archive, frontpage and section.
=== Output Types ===
Under the /articles/ directory we have a number of files. There is almost always a file called view.html.php. This is what we call the view file, but there can be more than one depending on the type of output to produce. It has a specific naming convention, view.output_type.php, where the output type can be html, feed, pdf, raw or error (for more information see JDocument in the API reference and look in the directory /libraries/joomla/document/). What this means is when we want html output for this particular view, the view.html.php file is used. When we want the RSS output, the view.feed.php file is used.

The affect of these different output types is most apparent when the Global Configuration setting for Search Engine Friendly URLs is set to Yes, Use Apache mod_rewrite is set to Yes, and Add suffix to URLs is also set to Yes. When this is done, the site URLs will look something like this:

<pre>
http://domain/sports.html
http://domain/sports.feed
http://domain/sports/rowing.html
http://domain/sports/rowing.pdf
</pre>
The exact URL will vary depending on how you set up your site but the point here is to show that sports.html will use the category view's view.html.php file to, and that sports.feed will display the RSS feed for the category using view.feed.php. It should be noted that you cannot currently customise feed or PDF output types. However, you can customise the html output type and this is where layouts come into play.

=== Layouts ===
Under the view directory there is a /tmpl/ directory in which the layout files reside. Each PHP file in this directory represents a layout. For example, article/tmpl/default.php is the default layout for an article whereas article/tmpl/form.php is the edit form for an article; category/tmpl/default.php is the default layout for a category whereas category/tmpl/blog.php displays the list of article differently.

The relationship between component views and layout is most plainly seen when adding a new menu item. The next screenshot represents the typical display of the New Menu Item page. Having clicked on Articles (which represents com_content), the tree expands to show the list of views and each layout within the view.

[[Image:Menu_item_type_articles.png|Screenshot of creating a new menu item fro an article.]]

You will notice that while there are extra files in some of the /tmpl/ directories (like pagebreak.php in the article view), they are missing from the list. This is due to instructions in the XML file for the layout (for example, pagebreak.xml) to hide the layout (or even the view) from the menu item list. However, this is another broad topic which will be covered in another tutorial.

Armed with all that knowledge of how all the parts relate to each other, we are now ready to actually create our layout overrides.

=== Copying or Creating Layout Files ===

Layout overrides only work within the active template and are located under the /html/ directory in the template. For example, the overrides for rhuk_milkyway are located under /templates/rhuk_milkyway/html/, for the JA Purity template under /templates/ja_purity/html/ and for Beez under /templates/beez/html/.

It is important to understand that if you create overrides in one template, they will not be available in other templates. For example, rhuk_milkyway has no component layout overrides at all. When you use this template you are seeing the raw output from all components. When you use the Beez template, almost every piece of component output is being controlled by the layout overrides in the template. JA Purity is in between having overrides for some components and only some views of those components.

The layout overrides must be placed in particular way. Using Beez as an example you will see the following structure:
<pre>
/templates
/beez
/html
/com_content (this directory matches the component directory name)
/articles (this directory matches the view directory name)
default.php (this file matches the layout file name)
form.php
</pre>

The structure for component overrides is quite simple: /html/com_component_name/view_name/layout_file_name.php. Let's look at a few examples.

The rhuk_milkyway template does not have any layout overrides for any components. If we want to override the default layout for an article, first we need to copy this file:

/components/com_content/views/article/tmpl/default.php

to this location, creating the appropriate directories in the event they don't already exist:

/templates/rhuk_milkyway/html/com_content/article/default.php

If we wanted to override the blog layout in the category view, we would copy this file:

/components/com_content/views/category/tmpl/blog.php

to:

/templates/rhuk_milkyway/html/com_content/category/blog.php

Once the files are copied, you are free to customise these files as much or as little as required or desired. You do not have to honour parameter settings if you don't want to.
=== Overriding Sub-Layouts ===

In some views you will see that some of the layouts have a group of files that start with the same name. The category view has an example of this. The blog layout actually has three parts: the main layout file blog.php and two sub-layout files, blog_item.php and blog_links.php. You can see where these sub-layouts are loaded in the blog.php file using the loadTemplate method, for example:
<source lang="php">
echo $this->loadTemplate('item');
// or
echo $this->loadTemplate('links');
</source>
When loading sub-layouts, the view already knows what layout you are in, so you don't have to provide the prefix (that is, you load just 'item', not 'blog_item').

What is important to note here is that it is possible to override just a sub-layout without copying the whole set of files. For example, if you were happy with the "Joomla!" default output for the blog layout, but just wanted to customise the item sub-layout, you could just copy:

/components/com_content/views/category/tmpl/blog_item.php

to:

/templates/rhuk_milkyway/html/com_content/category/blog_item.php

When "Joomla!" is parsing the view, it will automatically know to load blog.php from com_content natively and blog_item.php from your template overrides.
== Module Layout Overrides ==

Modules, like components, are set up in a particular directory structure.
<pre>
/modules
/mod_latest_news
/tmpl
default.php (the layout)
helper.php (a helper file containing data logic)
mod_latest_news.php (the main module file)
mod_latest_news.xml (the installation XML file)
</pre>
Similar to components, under the main module directory (in the example, mod_latest_news) there is a /tmpl/ directory. There is usually only one layout file but depending on who wrote the module, and how it is written, there could be more.

As for components, the layout override for a module must be placed in particular way. Using Beez as an example again, you will see the following structure:
<pre>
/templates
/beez
/html
/mod_latest_news.php (this directory matches the module directory name)
default.php (this file matches the layout file name)
</pre>
The structure for module overrides is again quite simple: /html/mod_module_name/layout_file_name.php.
=== Copying or Creating Layout Files ===

The rhuk_milkyway template does not have any layout overrides for any modules. If we want to override the default layout for Latest News module, we need to copy this file:

/components/mod_latest_news/default.php

to this location, creating the approriate directories in the event they don't already exist:

/templates/rhuk_milkyway/html/mod_latest_news/default.php

You need to take a little care with overriding module layout because there are a number of different ways that modules can or have been designed so you need to treat each one individually.
== Module Chrome ==

"Joomla!" 1.0 had a number of fixed styles that could display a list of modules in a particular position. These where represented by numbers:

* 0 (the default) displayed modules in a vertical table
* 1 displayed them in a horizontal table
* -1 displayed the raw module output
* -2 displayed the modules in a XHTML compatible format with the title in a H3 tag.
* -3 displayed modules in a set of nested DIVs that allowed for rounded-corner techniques

It was a great system except for two things:

# Nobody could remember which number was which, and
# You couldn't expand on the styles.

Well, in 1.5, the numbers are still recognised, but more commonly the style is represented as a word. As well as that, the syntax for displaying a module position was changed. For example, this snippet displays each module in the left position in the xhtml style:
<source lang="php">
<jdoc:include type="modules" name="left" style="xhtml" />
</source>
The built-in styles that are now available are:

* table (was 0 and is the default)
* horz (was 1)
* none (was -1)
* xhtml (was -2)
* rounded (was -3)
* outline (new - used to preview module positions - see screenshot above)

In the source code, these styles are actually referred to ask "chrome". The default chrome can actually be found in the system template provided in the default "Joomla!" install:

/templates/system/html/modules.php

This file is maintained by the project so you should never modify it directly otherwise there is a risk that you will loose your changes if and when you upgrade your "Joomla!" installation.

To create your own chrome, or module styles, all you need to do is create or edit modules.php under the templates /html/ directory (this is the same directory we have been talking about for component and module layout overrides).

The rhuk_milkyway template actually does provide some extra chrome as an example (it provides and new example style called "slider"). This can be found in the following file:

/templates/rhuk_milkyway/html/modules.php

To create your own chrome is really easy. Let's look at ficticious example that displays the module in a Definition List (a set of DL's, DT's and DD's).

Just add the following function to the /html/modules.php file in your default template directory (create it if it does not exist):
<source lang="php">
/*
* Module chrome that wraps the module in a definition list
*/
function modChrome_dlist($module, &$params, &$attribs)
{ ?>
<dl class="<?php echo $params->get('moduleclass_sfx'); ?>">
<?php if ($module->showtitle != 0) : ?>
<dt>
<?php echo $module->title; ?>
</dt>
<?php endif; ?>
<dd>
<?php echo $module->content; ?>
</dd>
</dl>
<?php
}
</source>
We will be calling the style "dlist", so the name of the function needs to be modChrome_dlist.

The function must take the three arguments as shown for the module object, the module parameters, and lastly the $attribs is an array of all the attributes in the jdoc XML tag.

There are three main properties in the module object to be concerned with:

* showtitle tells you whether to show the title of the module of not
* title is the title of the module
* content is the output of the module (from its layout)

This is a very simple case and you can of course design more complex styles, possibly using custom atrributes in the XML tag.
== Pagination Links Overrides ==

The final override we will look at is the pagination override. This override can control the display of items-per-page and the pagination links that are used with lists of information, as shown in the following screenshot.

[[Image:Article_list_pagination.png|Typical Joomla! page showing a paginated list.]]

The rhuk_milkyway template provides a well commented example for this override. The file is found here:

/templates/rhuk_milkyway/html/pagination.php

When the pagination list is required, "Joomla!" will look for this file in the default templates. If it is found it will be loaded and the display functions it contains will be used.

There are four functions that can be used:

pagination_list_footer

This function is responsible for showing the select list for the number of items to display per page.

pagination_list_render

This function is responsible for showing the list of page number links as well at the Start, End, Previous and Next links.

pagination_item_active

This function displays the links to other page numbers other than the "current" page.

pagination_item_active

This function displays the current page number, usually not hyperlinked.

== Cheat Sheet ==

Using the rhuk_milkyway template as an example, here is a brief summary of the priniciples we've looked at.
=== Customise the Component Output ===

To override a component layout (for example the default layout in the article view), copy:

/components/com_content/views/article/tmpl/default.php

to:

/templates/rhuk_milkyway/html/com_content/article/default.php

Read more about component output.
=== Customise the Module Output ===

To override a module layout (for example the Latest News module using the rhuk_milkyway template), copy:

/components/mod_latest_news/default.php

to:

/templates/rhuk_milkyway/html/mod_latest_news/default.php

Read more about module output.
=== Add New Module Styles ===

To add new module styles (chrome), add them to the following file:

/templates/rhuk_milkyway/html/modules.php

Read more about module styles.
=== Customise the Pagination Links ===

To customise the way the items-per-page selector and pagination links display, edit the following file:

/templates/rhuk_milkyway/html/pagination.php

Read more about [[#Pagination Links Overrides|pagination]].

== Conclusion ==

"Joomla!" 1.5, through the use of an MVC paradigm has greatly improved the flexibility that is afforded to Web site designers. By way of a few simple principles, like copying certain files to certain places in your template, the designer is able to override almost all of the output generated by "Joomla!".

If you have any questions relating to output overrides please let us know so that we can improve this tutorial.

If you have translated this article into another language, please let us know.

Understanding Output Overrides

2008-07-05T14:22:40Z

Instance: /* Pagination Links Overrides */

= Understanding Output Overrides in "Joomla!" 1.5 =
Written by Andrew Eddie

This was Developer Blog post by Andrew, initially copied to the wiki with minor edits by Alan Langford. This is still a work in progress.
== Introduction ==
There are many competing requirements for web designers ranging from accessibility to legislative to personal preferences. Rather than trying to over-parameterise views, or trying to aim for some sort of line of best fit, or worse, sticking its head in the sand, "Joomla!" has added the potential for the designer to take over control of virtually all of the output that is generated.

"Joomla!" has been criticized by some for not giving due attention to accessibility or being archaic in their approach to web standards. However with 1.5, the responsibility, but more importantly the power is back in the designer's hands.

In addition, except for files that are provided in the "Joomla!" distribution itself, these methods for customisation eliminate the need for designers and developers to "hack" core files that could change when the site is updated to a new version. Because they are contained within the template, they can be deployed to the Web site without having to worry about changes being accidentally overwritten when your System Administrator upgrades the site.

The aim of this tutorial is to introduce the how fours areas of the output of "Joomla!" are able to be customised by the template designer.

Not interested in all the theory? Jump straight to the cheat sheet.
== MVC 101 ==
MVC can be a scary acronym. It stands for Model-View-Controller and the concepts behind MVC are responsible for the extra flexibility that is now afforded to the designer. While parts of the theory can be rather involved and complicated, the only part that the designer need worry about is the V for View. This is the part that is concerned with output.

Different extensions display output in different ways.

Components, as you would already know, are fairly complex and have the ability to display different information in different ways. For example, the Articles Component (com_content) is able to display a single article, or articles in a category, or categories in a section. Each of the ways of representing the different types of data (an article, or a category, or a section) is called a "view" (this comes from our MVC terminology). Most components will have many views. However, the view doesn't actually display the output. This is left up to what we call a "layout" and it is possible for a view to have a variety of layouts.

The main thing to remember here is that components can have multiple views, and each view can have one or more layouts. Each view assembles a fixed set of information, but each layout can display that information in different ways. For example, the Category view in the Articles component assembles a number of articles. These articles could be displayed in a list or in a table (and probably other ways as well). So this view may have a "list" layout and a "table" layout to choose from.

Modules, on the other hand, are very simple. They generally display one thing one way. Modules don't really have views but they do support a layout. Some developers might even support a choice of layout through module parameters.
=== Template versus Layout ===

It is very important to distinguish between the role of template and the role of layouts. The template sets up a structural framework for the page of the Web site. Within this framework are positions for modules and a component to display. What actually gets displayed is governed by the module layout, or the combination of view and layout in the case of the component.

The following image shows the structural layout of a typical "Joomla!" template (rhuk_milkyway, the default for 1.5). The module positions are displayed by adding tp=1 to the URL (eg, index.php?tp=1). You can clearly see where the module output is contained within the overall template, as well as the main component output starting in the lower-centre region. However, what is actually output in those regions, is controlled by the layouts.

[[Image:FrontpageTemplatePositions.png|Typical Joomla! screenshot with template positions shown.]]

=== Ancillary Customisation ===

While not strictly related to the MVC, there are two other important areas to consider when looking at customising the output of "Joomla!".

In addition to layouts, modules have what we call "chrome". Chrome is the style with which a module is to display. Most developers, designers and probably some end-users will be familiar with the different built-in styles for modules (raw, xhtml, etc). It is also possible to define your own chrome styles for modules depending on the designer result. For example, you could design a chrome to display all the modules in a particular position in a fancy Javascript collapsing blind arrangement.

In the screenshot above, you can just make out the names of some of the built-in module chrome used (rounded, none and xhtml).

The second area has to do with controlling the pagination controls when viewing lists of data. We will look at that in more detail later.
== Component Output Types and Layout Overrides ==

To understand layout overrides we must first understand the file structure of a component. While there are many parts to a component, all fulfilling different roles and responsibilities, we want to look just in the /views/ directory. Here is the partial structure for two of the com_content views:
<pre>
/components
/com_content
/views
/articles
/tmpl
default.php (this is a layout)
form.php (this is a layout)
view.html.php (this is the view that outputs the HTML)
view.pdf.php (this is the view that outputs the PDF)
/category
/tmpl
blog.php (layout)
blog_items.php (a sub-layout
default.php (layout)
view.html.php (HTML view)
view.feed.php (RSS feed)
</pre>
So what you see here is that under the /views/ directory, each view is placed in a directory of its own. The content component actually has three other views not shown: archive, frontpage and section.
=== Output Types ===
Under the /articles/ directory we have a number of files. There is almost always a file called view.html.php. This is what we call the view file, but there can be more than one depending on the type of output to produce. It has a specific naming convention, view.output_type.php, where the output type can be html, feed, pdf, raw or error (for more information see JDocument in the API reference and look in the directory /libraries/joomla/document/). What this means is when we want html output for this particular view, the view.html.php file is used. When we want the RSS output, the view.feed.php file is used.

The affect of these different output types is most apparent when the Global Configuration setting for Search Engine Friendly URLs is set to Yes, Use Apache mod_rewrite is set to Yes, and Add suffix to URLs is also set to Yes. When this is done, the site URLs will look something like this:

<pre>
http://domain/sports.html
http://domain/sports.feed
http://domain/sports/rowing.html
http://domain/sports/rowing.pdf
</pre>
The exact URL will vary depending on how you set up your site but the point here is to show that sports.html will use the category view's view.html.php file to, and that sports.feed will display the RSS feed for the category using view.feed.php. It should be noted that you cannot currently customise feed or PDF output types. However, you can customise the html output type and this is where layouts come into play.

=== Layouts ===
Under the view directory there is a /tmpl/ directory in which the layout files reside. Each PHP file in this directory represents a layout. For example, article/tmpl/default.php is the default layout for an article whereas article/tmpl/form.php is the edit form for an article; category/tmpl/default.php is the default layout for a category whereas category/tmpl/blog.php displays the list of article differently.

The relationship between component views and layout is most plainly seen when adding a new menu item. The next screenshot represents the typical display of the New Menu Item page. Having clicked on Articles (which represents com_content), the tree expands to show the list of views and each layout within the view.

[[Image:Menu_item_type_articles.png|Screenshot of creating a new menu item fro an article.]]

You will notice that while there are extra files in some of the /tmpl/ directories (like pagebreak.php in the article view), they are missing from the list. This is due to instructions in the XML file for the layout (for example, pagebreak.xml) to hide the layout (or even the view) from the menu item list. However, this is another broad topic which will be covered in another tutorial.

Armed with all that knowledge of how all the parts relate to each other, we are now ready to actually create our layout overrides.

=== Copying or Creating Layout Files ===

Layout overrides only work within the active template and are located under the /html/ directory in the template. For example, the overrides for rhuk_milkyway are located under /templates/rhuk_milkyway/html/, for the JA Purity template under /templates/ja_purity/html/ and for Beez under /templates/beez/html/.

It is important to understand that if you create overrides in one template, they will not be available in other templates. For example, rhuk_milkyway has no component layout overrides at all. When you use this template you are seeing the raw output from all components. When you use the Beez template, almost every piece of component output is being controlled by the layout overrides in the template. JA Purity is in between having overrides for some components and only some views of those components.

The layout overrides must be placed in particular way. Using Beez as an example you will see the following structure:
<pre>
/templates
/beez
/html
/com_content (this directory matches the component directory name)
/articles (this directory matches the view directory name)
default.php (this file matches the layout file name)
form.php
</pre>

The structure for component overrides is quite simple: /html/com_component_name/view_name/layout_file_name.php. Let's look at a few examples.

The rhuk_milkyway template does not have any layout overrides for any components. If we want to override the default layout for an article, first we need to copy this file:

/components/com_content/views/article/tmpl/default.php

to this location, creating the appropriate directories in the event they don't already exist:

/templates/rhuk_milkyway/html/com_content/article/default.php

If we wanted to override the blog layout in the category view, we would copy this file:

/components/com_content/views/category/tmpl/blog.php

to:

/templates/rhuk_milkyway/html/com_content/category/blog.php

Once the files are copied, you are free to customise these files as much or as little as required or desired. You do not have to honour parameter settings if you don't want to.
=== Overriding Sub-Layouts ===

In some views you will see that some of the layouts have a group of files that start with the same name. The category view has an example of this. The blog layout actually has three parts: the main layout file blog.php and two sub-layout files, blog_item.php and blog_links.php. You can see where these sub-layouts are loaded in the blog.php file using the loadTemplate method, for example:
<source lang="php">
echo $this->loadTemplate('item');
// or
echo $this->loadTemplate('links');
</source>
When loading sub-layouts, the view already knows what layout you are in, so you don't have to provide the prefix (that is, you load just 'item', not 'blog_item').

What is important to note here is that it is possible to override just a sub-layout without copying the whole set of files. For example, if you were happy with the "Joomla!" default output for the blog layout, but just wanted to customise the item sub-layout, you could just copy:

/components/com_content/views/category/tmpl/blog_item.php

to:

/templates/rhuk_milkyway/html/com_content/category/blog_item.php

When "Joomla!" is parsing the view, it will automatically know to load blog.php from com_content natively and blog_item.php from your template overrides.
== Module Layout Overrides ==

Modules, like components, are set up in a particular directory structure.
<pre>
/modules
/mod_latest_news
/tmpl
default.php (the layout)
helper.php (a helper file containing data logic)
mod_latest_news.php (the main module file)
mod_latest_news.xml (the installation XML file)
</pre>
Similar to components, under the main module directory (in the example, mod_latest_news) there is a /tmpl/ directory. There is usually only one layout file but depending on who wrote the module, and how it is written, there could be more.

As for components, the layout override for a module must be placed in particular way. Using Beez as an example again, you will see the following structure:
<pre>
/templates
/beez
/html
/mod_latest_news.php (this directory matches the module directory name)
default.php (this file matches the layout file name)
</pre>
The structure for module overrides is again quite simple: /html/mod_module_name/layout_file_name.php.
=== Copying or Creating Layout Files ===

The rhuk_milkyway template does not have any layout overrides for any modules. If we want to override the default layout for Latest News module, we need to copy this file:

/components/mod_latest_news/default.php

to this location, creating the approriate directories in the event they don't already exist:

/templates/rhuk_milkyway/html/mod_latest_news/default.php

You need to take a little care with overriding module layout because there are a number of different ways that modules can or have been designed so you need to treat each one individually.
== Module Chrome ==

"Joomla!" 1.0 had a number of fixed styles that could display a list of modules in a particular position. These where represented by numbers:

* 0 (the default) displayed modules in a vertical table
* 1 displayed them in a horizontal table
* -1 displayed the raw module output
* -2 displayed the modules in a XHTML compatible format with the title in a H3 tag.
* -3 displayed modules in a set of nested DIVs that allowed for rounded-corner techniques

It was a great system except for two things:

# Nobody could remember which number was which, and
# You couldn't expand on the styles.

Well, in 1.5, the numbers are still recognised, but more commonly the style is represented as a word. As well as that, the syntax for displaying a module position was changed. For example, this snippet displays each module in the left position in the xhtml style:
<source lang="php">
<jdoc:include type="modules" name="left" style="xhtml" />
</source>
The built-in styles that are now available are:

* table (was 0 and is the default)
* horz (was 1)
* none (was -1)
* xhtml (was -2)
* rounded (was -3)
* outline (new - used to preview module positions - see screenshot above)

In the source code, these styles are actually referred to ask "chrome". The default chrome can actually be found in the system template provided in the default "Joomla!" install:

/templates/system/html/modules.php

This file is maintained by the project so you should never modify it directly otherwise there is a risk that you will loose your changes if and when you upgrade your "Joomla!" installation.

To create your own chrome, or module styles, all you need to do is create or edit modules.php under the templates /html/ directory (this is the same directory we have been talking about for component and module layout overrides).

The rhuk_milkyway template actually does provide some extra chrome as an example (it provides and new example style called "slider"). This can be found in the following file:

/templates/rhuk_milkyway/html/modules.php

To create your own chrome is really easy. Let's look at ficticious example that displays the module in a Definition List (a set of DL's, DT's and DD's).

Just add the following function to the /html/modules.php file in your default template directory (create it if it does not exist):
<source lang="php">
/*
* Module chrome that wraps the module in a definition list
*/
function modChrome_dlist($module, &$params, &$attribs)
{ ?>
<dl class="<?php echo $params->get('moduleclass_sfx'); ?>">
<?php if ($module->showtitle != 0) : ?>
<dt>
<?php echo $module->title; ?>
</dt>
<?php endif; ?>
<dd>
<?php echo $module->content; ?>
</dd>
</dl>
<?php
}
</source>
We will be calling the style "dlist", so the name of the function needs to be modChrome_dlist.

The function must take the three arguments as shown for the module object, the module parameters, and lastly the $attribs is an array of all the attributes in the jdoc XML tag.

There are three main properties in the module object to be concerned with:

* showtitle tells you whether to show the title of the module of not
* title is the title of the module
* content is the output of the module (from its layout)

This is a very simple case and you can of course design more complex styles, possibly using custom atrributes in the XML tag.
== Pagination Links Overrides ==

The final override we will look at is the pagination override. This override can control the display of items-per-page and the pagination links that are used with lists of information, as shown in the following screenshot.

[[Image:Article_list_pagination.png|Typical Joomla! page showing a paginated list.]]

The rhuk_milkyway template provides a well commented example for this override. The file is found here:

/templates/rhuk_milkyway/html/pagination.php

When the pagination list is required, "Joomla!" will look for this file in the default templates. If it is found it will be loaded and the display functions it contains will be used.

There are four functions that can be used:

pagination_list_footer

This function is responsible for showing the select list for the number of items to display per page.

pagination_list_render

This function is responsible for showing the list of page number links as well at the Start, End, Previous and Next links.

pagination_item_active

This function displays the links to other page numbers other than the "current" page.

pagination_item_active

This function displays the current page number, usually not hyperlinked.

== Cheat Sheet ==

Using the rhuk_milkyway template as an example, here is a brief summary of the priniciples we've looked at.
=== Customise the Component Output ===

To override a component layout (for example the default layout in the article view), copy:

/components/com_content/views/article/tmpl/default.php

to:

/templates/rhuk_milkyway/html/com_content/article/default.php

Read more about component output.
=== Customise the Module Output ===

To override a module layout (for example the Latest News module using the rhuk_milkyway template), copy:

/components/mod_latest_news/default.php

to:

/templates/rhuk_milkyway/html/mod_latest_news/default.php

Read more about module output.
=== Add New Module Styles ===

To add new module styles (chrome), add them to the following file:

/templates/rhuk_milkyway/html/modules.php

Read more about module styles.
=== Customise the Pagination Links ===

To customise the way the items-per-page selector and pagination links display, edit the following file:

/templates/rhuk_milkyway/html/pagination.php

Read more about pagination.
== Conclusion ==

"Joomla!" 1.5, through the use of an MVC paradigm has greatly improved the flexibility that is afforded to Web site designers. By way of a few simple principles, like copying certain files to certain places in your template, the designer is able to override almost all of the output generated by "Joomla!".

If you have any questions relating to output overrides please let us know so that we can improve this tutorial.

If you have translated this article into another language, please let us know.

File:Article list pagination.png

2008-07-05T14:20:24Z

Instance: screenshot: List of articles with pagination elements highlighted.

== Summary ==
screenshot: List of articles with pagination elements highlighted.
== Licensing ==
{{JEDL}}

Understanding Output Overrides

2008-07-05T14:14:31Z

Instance: /* Layouts */

= Understanding Output Overrides in "Joomla!" 1.5 =
Written by Andrew Eddie

This was Developer Blog post by Andrew, initially copied to the wiki with minor edits by Alan Langford. This is still a work in progress.
== Introduction ==
There are many competing requirements for web designers ranging from accessibility to legislative to personal preferences. Rather than trying to over-parameterise views, or trying to aim for some sort of line of best fit, or worse, sticking its head in the sand, "Joomla!" has added the potential for the designer to take over control of virtually all of the output that is generated.

"Joomla!" has been criticized by some for not giving due attention to accessibility or being archaic in their approach to web standards. However with 1.5, the responsibility, but more importantly the power is back in the designer's hands.

In addition, except for files that are provided in the "Joomla!" distribution itself, these methods for customisation eliminate the need for designers and developers to "hack" core files that could change when the site is updated to a new version. Because they are contained within the template, they can be deployed to the Web site without having to worry about changes being accidentally overwritten when your System Administrator upgrades the site.

The aim of this tutorial is to introduce the how fours areas of the output of "Joomla!" are able to be customised by the template designer.

Not interested in all the theory? Jump straight to the cheat sheet.
== MVC 101 ==
MVC can be a scary acronym. It stands for Model-View-Controller and the concepts behind MVC are responsible for the extra flexibility that is now afforded to the designer. While parts of the theory can be rather involved and complicated, the only part that the designer need worry about is the V for View. This is the part that is concerned with output.

Different extensions display output in different ways.

Components, as you would already know, are fairly complex and have the ability to display different information in different ways. For example, the Articles Component (com_content) is able to display a single article, or articles in a category, or categories in a section. Each of the ways of representing the different types of data (an article, or a category, or a section) is called a "view" (this comes from our MVC terminology). Most components will have many views. However, the view doesn't actually display the output. This is left up to what we call a "layout" and it is possible for a view to have a variety of layouts.

The main thing to remember here is that components can have multiple views, and each view can have one or more layouts. Each view assembles a fixed set of information, but each layout can display that information in different ways. For example, the Category view in the Articles component assembles a number of articles. These articles could be displayed in a list or in a table (and probably other ways as well). So this view may have a "list" layout and a "table" layout to choose from.

Modules, on the other hand, are very simple. They generally display one thing one way. Modules don't really have views but they do support a layout. Some developers might even support a choice of layout through module parameters.
=== Template versus Layout ===

It is very important to distinguish between the role of template and the role of layouts. The template sets up a structural framework for the page of the Web site. Within this framework are positions for modules and a component to display. What actually gets displayed is governed by the module layout, or the combination of view and layout in the case of the component.

The following image shows the structural layout of a typical "Joomla!" template (rhuk_milkyway, the default for 1.5). The module positions are displayed by adding tp=1 to the URL (eg, index.php?tp=1). You can clearly see where the module output is contained within the overall template, as well as the main component output starting in the lower-centre region. However, what is actually output in those regions, is controlled by the layouts.

[[Image:FrontpageTemplatePositions.png|Typical Joomla! screenshot with template positions shown.]]

=== Ancillary Customisation ===

While not strictly related to the MVC, there are two other important areas to consider when looking at customising the output of "Joomla!".

In addition to layouts, modules have what we call "chrome". Chrome is the style with which a module is to display. Most developers, designers and probably some end-users will be familiar with the different built-in styles for modules (raw, xhtml, etc). It is also possible to define your own chrome styles for modules depending on the designer result. For example, you could design a chrome to display all the modules in a particular position in a fancy Javascript collapsing blind arrangement.

In the screenshot above, you can just make out the names of some of the built-in module chrome used (rounded, none and xhtml).

The second area has to do with controlling the pagination controls when viewing lists of data. We will look at that in more detail later.
== Component Output Types and Layout Overrides ==

To understand layout overrides we must first understand the file structure of a component. While there are many parts to a component, all fulfilling different roles and responsibilities, we want to look just in the /views/ directory. Here is the partial structure for two of the com_content views:
<pre>
/components
/com_content
/views
/articles
/tmpl
default.php (this is a layout)
form.php (this is a layout)
view.html.php (this is the view that outputs the HTML)
view.pdf.php (this is the view that outputs the PDF)
/category
/tmpl
blog.php (layout)
blog_items.php (a sub-layout
default.php (layout)
view.html.php (HTML view)
view.feed.php (RSS feed)
</pre>
So what you see here is that under the /views/ directory, each view is placed in a directory of its own. The content component actually has three other views not shown: archive, frontpage and section.
=== Output Types ===
Under the /articles/ directory we have a number of files. There is almost always a file called view.html.php. This is what we call the view file, but there can be more than one depending on the type of output to produce. It has a specific naming convention, view.output_type.php, where the output type can be html, feed, pdf, raw or error (for more information see JDocument in the API reference and look in the directory /libraries/joomla/document/). What this means is when we want html output for this particular view, the view.html.php file is used. When we want the RSS output, the view.feed.php file is used.

The affect of these different output types is most apparent when the Global Configuration setting for Search Engine Friendly URLs is set to Yes, Use Apache mod_rewrite is set to Yes, and Add suffix to URLs is also set to Yes. When this is done, the site URLs will look something like this:

<pre>
http://domain/sports.html
http://domain/sports.feed
http://domain/sports/rowing.html
http://domain/sports/rowing.pdf
</pre>
The exact URL will vary depending on how you set up your site but the point here is to show that sports.html will use the category view's view.html.php file to, and that sports.feed will display the RSS feed for the category using view.feed.php. It should be noted that you cannot currently customise feed or PDF output types. However, you can customise the html output type and this is where layouts come into play.

=== Layouts ===
Under the view directory there is a /tmpl/ directory in which the layout files reside. Each PHP file in this directory represents a layout. For example, article/tmpl/default.php is the default layout for an article whereas article/tmpl/form.php is the edit form for an article; category/tmpl/default.php is the default layout for a category whereas category/tmpl/blog.php displays the list of article differently.

The relationship between component views and layout is most plainly seen when adding a new menu item. The next screenshot represents the typical display of the New Menu Item page. Having clicked on Articles (which represents com_content), the tree expands to show the list of views and each layout within the view.

[[Image:Menu_item_type_articles.png|Screenshot of creating a new menu item fro an article.]]

You will notice that while there are extra files in some of the /tmpl/ directories (like pagebreak.php in the article view), they are missing from the list. This is due to instructions in the XML file for the layout (for example, pagebreak.xml) to hide the layout (or even the view) from the menu item list. However, this is another broad topic which will be covered in another tutorial.

Armed with all that knowledge of how all the parts relate to each other, we are now ready to actually create our layout overrides.

=== Copying or Creating Layout Files ===

Layout overrides only work within the active template and are located under the /html/ directory in the template. For example, the overrides for rhuk_milkyway are located under /templates/rhuk_milkyway/html/, for the JA Purity template under /templates/ja_purity/html/ and for Beez under /templates/beez/html/.

It is important to understand that if you create overrides in one template, they will not be available in other templates. For example, rhuk_milkyway has no component layout overrides at all. When you use this template you are seeing the raw output from all components. When you use the Beez template, almost every piece of component output is being controlled by the layout overrides in the template. JA Purity is in between having overrides for some components and only some views of those components.

The layout overrides must be placed in particular way. Using Beez as an example you will see the following structure:
<pre>
/templates
/beez
/html
/com_content (this directory matches the component directory name)
/articles (this directory matches the view directory name)
default.php (this file matches the layout file name)
form.php
</pre>

The structure for component overrides is quite simple: /html/com_component_name/view_name/layout_file_name.php. Let's look at a few examples.

The rhuk_milkyway template does not have any layout overrides for any components. If we want to override the default layout for an article, first we need to copy this file:

/components/com_content/views/article/tmpl/default.php

to this location, creating the appropriate directories in the event they don't already exist:

/templates/rhuk_milkyway/html/com_content/article/default.php

If we wanted to override the blog layout in the category view, we would copy this file:

/components/com_content/views/category/tmpl/blog.php

to:

/templates/rhuk_milkyway/html/com_content/category/blog.php

Once the files are copied, you are free to customise these files as much or as little as required or desired. You do not have to honour parameter settings if you don't want to.
=== Overriding Sub-Layouts ===

In some views you will see that some of the layouts have a group of files that start with the same name. The category view has an example of this. The blog layout actually has three parts: the main layout file blog.php and two sub-layout files, blog_item.php and blog_links.php. You can see where these sub-layouts are loaded in the blog.php file using the loadTemplate method, for example:
<source lang="php">
echo $this->loadTemplate('item');
// or
echo $this->loadTemplate('links');
</source>
When loading sub-layouts, the view already knows what layout you are in, so you don't have to provide the prefix (that is, you load just 'item', not 'blog_item').

What is important to note here is that it is possible to override just a sub-layout without copying the whole set of files. For example, if you were happy with the "Joomla!" default output for the blog layout, but just wanted to customise the item sub-layout, you could just copy:

/components/com_content/views/category/tmpl/blog_item.php

to:

/templates/rhuk_milkyway/html/com_content/category/blog_item.php

When "Joomla!" is parsing the view, it will automatically know to load blog.php from com_content natively and blog_item.php from your template overrides.
== Module Layout Overrides ==

Modules, like components, are set up in a particular directory structure.
<pre>
/modules
/mod_latest_news
/tmpl
default.php (the layout)
helper.php (a helper file containing data logic)
mod_latest_news.php (the main module file)
mod_latest_news.xml (the installation XML file)
</pre>
Similar to components, under the main module directory (in the example, mod_latest_news) there is a /tmpl/ directory. There is usually only one layout file but depending on who wrote the module, and how it is written, there could be more.

As for components, the layout override for a module must be placed in particular way. Using Beez as an example again, you will see the following structure:
<pre>
/templates
/beez
/html
/mod_latest_news.php (this directory matches the module directory name)
default.php (this file matches the layout file name)
</pre>
The structure for module overrides is again quite simple: /html/mod_module_name/layout_file_name.php.
=== Copying or Creating Layout Files ===

The rhuk_milkyway template does not have any layout overrides for any modules. If we want to override the default layout for Latest News module, we need to copy this file:

/components/mod_latest_news/default.php

to this location, creating the approriate directories in the event they don't already exist:

/templates/rhuk_milkyway/html/mod_latest_news/default.php

You need to take a little care with overriding module layout because there are a number of different ways that modules can or have been designed so you need to treat each one individually.
== Module Chrome ==

"Joomla!" 1.0 had a number of fixed styles that could display a list of modules in a particular position. These where represented by numbers:

* 0 (the default) displayed modules in a vertical table
* 1 displayed them in a horizontal table
* -1 displayed the raw module output
* -2 displayed the modules in a XHTML compatible format with the title in a H3 tag.
* -3 displayed modules in a set of nested DIVs that allowed for rounded-corner techniques

It was a great system except for two things:

# Nobody could remember which number was which, and
# You couldn't expand on the styles.

Well, in 1.5, the numbers are still recognised, but more commonly the style is represented as a word. As well as that, the syntax for displaying a module position was changed. For example, this snippet displays each module in the left position in the xhtml style:
<source lang="php">
<jdoc:include type="modules" name="left" style="xhtml" />
</source>
The built-in styles that are now available are:

* table (was 0 and is the default)
* horz (was 1)
* none (was -1)
* xhtml (was -2)
* rounded (was -3)
* outline (new - used to preview module positions - see screenshot above)

In the source code, these styles are actually referred to ask "chrome". The default chrome can actually be found in the system template provided in the default "Joomla!" install:

/templates/system/html/modules.php

This file is maintained by the project so you should never modify it directly otherwise there is a risk that you will loose your changes if and when you upgrade your "Joomla!" installation.

To create your own chrome, or module styles, all you need to do is create or edit modules.php under the templates /html/ directory (this is the same directory we have been talking about for component and module layout overrides).

The rhuk_milkyway template actually does provide some extra chrome as an example (it provides and new example style called "slider"). This can be found in the following file:

/templates/rhuk_milkyway/html/modules.php

To create your own chrome is really easy. Let's look at ficticious example that displays the module in a Definition List (a set of DL's, DT's and DD's).

Just add the following function to the /html/modules.php file in your default template directory (create it if it does not exist):
<source lang="php">
/*
* Module chrome that wraps the module in a definition list
*/
function modChrome_dlist($module, &$params, &$attribs)
{ ?>
<dl class="<?php echo $params->get('moduleclass_sfx'); ?>">
<?php if ($module->showtitle != 0) : ?>
<dt>
<?php echo $module->title; ?>
</dt>
<?php endif; ?>
<dd>
<?php echo $module->content; ?>
</dd>
</dl>
<?php
}
</source>
We will be calling the style "dlist", so the name of the function needs to be modChrome_dlist.

The function must take the three arguments as shown for the module object, the module parameters, and lastly the $attribs is an array of all the attributes in the jdoc XML tag.

There are three main properties in the module object to be concerned with:

* showtitle tells you whether to show the title of the module of not
* title is the title of the module
* content is the output of the module (from its layout)

This is a very simple case and you can of course design more complex styles, possibly using custom atrributes in the XML tag.
== Pagination Links Overrides ==

The final override we will look at is the pagination override. This override can control the display of items-per-page and the pagination links that are used with lists of information, as shown in the following screenshot.

http://developer.joomla.org/images/tutorials/understanding_output/pagination_links.png

The rhuk_milkyway template provides a well commented example for this override. The file is found here:

/templates/rhuk_milkyway/html/pagination.php

When the pagination list is required, "Joomla!" will look for this file in the default templates. If it is found it will be loaded and the display functions it contains will be used.

There are four functions that can be used:

pagination_list_footer

This function is responsible for showing the select list for the number of items to display per page.

pagination_list_render

This function is responsible for showing the list of page number links as well at the Start, End, Previous and Next links.

pagination_item_active

This function displays the links to other page numbers other than the "current" page.

pagination_item_active

This function displays the current page number, usually not hyperlinked.
== Cheat Sheet ==

Using the rhuk_milkyway template as an example, here is a brief summary of the priniciples we've looked at.
=== Customise the Component Output ===

To override a component layout (for example the default layout in the article view), copy:

/components/com_content/views/article/tmpl/default.php

to:

/templates/rhuk_milkyway/html/com_content/article/default.php

Read more about component output.
=== Customise the Module Output ===

To override a module layout (for example the Latest News module using the rhuk_milkyway template), copy:

/components/mod_latest_news/default.php

to:

/templates/rhuk_milkyway/html/mod_latest_news/default.php

Read more about module output.
=== Add New Module Styles ===

To add new module styles (chrome), add them to the following file:

/templates/rhuk_milkyway/html/modules.php

Read more about module styles.
=== Customise the Pagination Links ===

To customise the way the items-per-page selector and pagination links display, edit the following file:

/templates/rhuk_milkyway/html/pagination.php

Read more about pagination.
== Conclusion ==

"Joomla!" 1.5, through the use of an MVC paradigm has greatly improved the flexibility that is afforded to Web site designers. By way of a few simple principles, like copying certain files to certain places in your template, the designer is able to override almost all of the output generated by "Joomla!".

If you have any questions relating to output overrides please let us know so that we can improve this tutorial.

If you have translated this article into another language, please let us know.

Understanding Output Overrides

2008-07-05T14:09:23Z

Instance: /* Template versus Layout */

= Understanding Output Overrides in "Joomla!" 1.5 =
Written by Andrew Eddie

This was Developer Blog post by Andrew, initially copied to the wiki with minor edits by Alan Langford. This is still a work in progress.
== Introduction ==
There are many competing requirements for web designers ranging from accessibility to legislative to personal preferences. Rather than trying to over-parameterise views, or trying to aim for some sort of line of best fit, or worse, sticking its head in the sand, "Joomla!" has added the potential for the designer to take over control of virtually all of the output that is generated.

"Joomla!" has been criticized by some for not giving due attention to accessibility or being archaic in their approach to web standards. However with 1.5, the responsibility, but more importantly the power is back in the designer's hands.

In addition, except for files that are provided in the "Joomla!" distribution itself, these methods for customisation eliminate the need for designers and developers to "hack" core files that could change when the site is updated to a new version. Because they are contained within the template, they can be deployed to the Web site without having to worry about changes being accidentally overwritten when your System Administrator upgrades the site.

The aim of this tutorial is to introduce the how fours areas of the output of "Joomla!" are able to be customised by the template designer.

Not interested in all the theory? Jump straight to the cheat sheet.
== MVC 101 ==
MVC can be a scary acronym. It stands for Model-View-Controller and the concepts behind MVC are responsible for the extra flexibility that is now afforded to the designer. While parts of the theory can be rather involved and complicated, the only part that the designer need worry about is the V for View. This is the part that is concerned with output.

Different extensions display output in different ways.

Components, as you would already know, are fairly complex and have the ability to display different information in different ways. For example, the Articles Component (com_content) is able to display a single article, or articles in a category, or categories in a section. Each of the ways of representing the different types of data (an article, or a category, or a section) is called a "view" (this comes from our MVC terminology). Most components will have many views. However, the view doesn't actually display the output. This is left up to what we call a "layout" and it is possible for a view to have a variety of layouts.

The main thing to remember here is that components can have multiple views, and each view can have one or more layouts. Each view assembles a fixed set of information, but each layout can display that information in different ways. For example, the Category view in the Articles component assembles a number of articles. These articles could be displayed in a list or in a table (and probably other ways as well). So this view may have a "list" layout and a "table" layout to choose from.

Modules, on the other hand, are very simple. They generally display one thing one way. Modules don't really have views but they do support a layout. Some developers might even support a choice of layout through module parameters.
=== Template versus Layout ===

It is very important to distinguish between the role of template and the role of layouts. The template sets up a structural framework for the page of the Web site. Within this framework are positions for modules and a component to display. What actually gets displayed is governed by the module layout, or the combination of view and layout in the case of the component.

The following image shows the structural layout of a typical "Joomla!" template (rhuk_milkyway, the default for 1.5). The module positions are displayed by adding tp=1 to the URL (eg, index.php?tp=1). You can clearly see where the module output is contained within the overall template, as well as the main component output starting in the lower-centre region. However, what is actually output in those regions, is controlled by the layouts.

[[Image:FrontpageTemplatePositions.png|Typical Joomla! screenshot with template positions shown.]]

=== Ancillary Customisation ===

While not strictly related to the MVC, there are two other important areas to consider when looking at customising the output of "Joomla!".

In addition to layouts, modules have what we call "chrome". Chrome is the style with which a module is to display. Most developers, designers and probably some end-users will be familiar with the different built-in styles for modules (raw, xhtml, etc). It is also possible to define your own chrome styles for modules depending on the designer result. For example, you could design a chrome to display all the modules in a particular position in a fancy Javascript collapsing blind arrangement.

In the screenshot above, you can just make out the names of some of the built-in module chrome used (rounded, none and xhtml).

The second area has to do with controlling the pagination controls when viewing lists of data. We will look at that in more detail later.
== Component Output Types and Layout Overrides ==

To understand layout overrides we must first understand the file structure of a component. While there are many parts to a component, all fulfilling different roles and responsibilities, we want to look just in the /views/ directory. Here is the partial structure for two of the com_content views:
<pre>
/components
/com_content
/views
/articles
/tmpl
default.php (this is a layout)
form.php (this is a layout)
view.html.php (this is the view that outputs the HTML)
view.pdf.php (this is the view that outputs the PDF)
/category
/tmpl
blog.php (layout)
blog_items.php (a sub-layout
default.php (layout)
view.html.php (HTML view)
view.feed.php (RSS feed)
</pre>
So what you see here is that under the /views/ directory, each view is placed in a directory of its own. The content component actually has three other views not shown: archive, frontpage and section.
=== Output Types ===
Under the /articles/ directory we have a number of files. There is almost always a file called view.html.php. This is what we call the view file, but there can be more than one depending on the type of output to produce. It has a specific naming convention, view.output_type.php, where the output type can be html, feed, pdf, raw or error (for more information see JDocument in the API reference and look in the directory /libraries/joomla/document/). What this means is when we want html output for this particular view, the view.html.php file is used. When we want the RSS output, the view.feed.php file is used.

The affect of these different output types is most apparent when the Global Configuration setting for Search Engine Friendly URLs is set to Yes, Use Apache mod_rewrite is set to Yes, and Add suffix to URLs is also set to Yes. When this is done, the site URLs will look something like this:

<pre>
http://domain/sports.html
http://domain/sports.feed
http://domain/sports/rowing.html
http://domain/sports/rowing.pdf
</pre>
The exact URL will vary depending on how you set up your site but the point here is to show that sports.html will use the category view's view.html.php file to, and that sports.feed will display the RSS feed for the category using view.feed.php. It should be noted that you cannot currently customise feed or PDF output types. However, you can customise the html output type and this is where layouts come into play.

=== Layouts ===
Under the view directory there is a /tmpl/ directory in which the layout files reside. Each PHP file in this directory represents a layout. For example, article/tmpl/default.php is the default layout for an article whereas article/tmpl/form.php is the edit form for an article; category/tmpl/default.php is the default layout for a category whereas category/tmpl/blog.php displays the list of article differently.

The relationship between component views and layout is most plainly seen when adding a new menu item. The next screenshot represents the typical display of the New Menu Item page. Having clicked on Articles (which represents com_content), the tree expands to show the list of views and each layout within the view.

http://developer.joomla.org/images/tutorials/understanding_output/menu_item_new.png

You will notice that while there are extra files in some of the /tmpl/ directories (like pagebreak.php in the article view), they are missing from the list. This is due to instructions in the XML file for the layout (for example, pagebreak.xml) to hide the layout (or even the view) from the menu item list. However, this is another broad topic which will be covered in another tutorial.

Armed with all that knowledge of how all the parts relate to each other, we are now ready to actually create our layout overrides.
=== Copying or Creating Layout Files ===

Layout overrides only work within the active template and are located under the /html/ directory in the template. For example, the overrides for rhuk_milkyway are located under /templates/rhuk_milkyway/html/, for the JA Purity template under /templates/ja_purity/html/ and for Beez under /templates/beez/html/.

It is important to understand that if you create overrides in one template, they will not be available in other templates. For example, rhuk_milkyway has no component layout overrides at all. When you use this template you are seeing the raw output from all components. When you use the Beez template, almost every piece of component output is being controlled by the layout overrides in the template. JA Purity is in between having overrides for some components and only some views of those components.

The layout overrides must be placed in particular way. Using Beez as an example you will see the following structure:
<pre>
/templates
/beez
/html
/com_content (this directory matches the component directory name)
/articles (this directory matches the view directory name)
default.php (this file matches the layout file name)
form.php
</pre>

The structure for component overrides is quite simple: /html/com_component_name/view_name/layout_file_name.php. Let's look at a few examples.

The rhuk_milkyway template does not have any layout overrides for any components. If we want to override the default layout for an article, first we need to copy this file:

/components/com_content/views/article/tmpl/default.php

to this location, creating the appropriate directories in the event they don't already exist:

/templates/rhuk_milkyway/html/com_content/article/default.php

If we wanted to override the blog layout in the category view, we would copy this file:

/components/com_content/views/category/tmpl/blog.php

to:

/templates/rhuk_milkyway/html/com_content/category/blog.php

Once the files are copied, you are free to customise these files as much or as little as required or desired. You do not have to honour parameter settings if you don't want to.
=== Overriding Sub-Layouts ===

In some views you will see that some of the layouts have a group of files that start with the same name. The category view has an example of this. The blog layout actually has three parts: the main layout file blog.php and two sub-layout files, blog_item.php and blog_links.php. You can see where these sub-layouts are loaded in the blog.php file using the loadTemplate method, for example:
<source lang="php">
echo $this->loadTemplate('item');
// or
echo $this->loadTemplate('links');
</source>
When loading sub-layouts, the view already knows what layout you are in, so you don't have to provide the prefix (that is, you load just 'item', not 'blog_item').

What is important to note here is that it is possible to override just a sub-layout without copying the whole set of files. For example, if you were happy with the "Joomla!" default output for the blog layout, but just wanted to customise the item sub-layout, you could just copy:

/components/com_content/views/category/tmpl/blog_item.php

to:

/templates/rhuk_milkyway/html/com_content/category/blog_item.php

When "Joomla!" is parsing the view, it will automatically know to load blog.php from com_content natively and blog_item.php from your template overrides.
== Module Layout Overrides ==

Modules, like components, are set up in a particular directory structure.
<pre>
/modules
/mod_latest_news
/tmpl
default.php (the layout)
helper.php (a helper file containing data logic)
mod_latest_news.php (the main module file)
mod_latest_news.xml (the installation XML file)
</pre>
Similar to components, under the main module directory (in the example, mod_latest_news) there is a /tmpl/ directory. There is usually only one layout file but depending on who wrote the module, and how it is written, there could be more.

As for components, the layout override for a module must be placed in particular way. Using Beez as an example again, you will see the following structure:
<pre>
/templates
/beez
/html
/mod_latest_news.php (this directory matches the module directory name)
default.php (this file matches the layout file name)
</pre>
The structure for module overrides is again quite simple: /html/mod_module_name/layout_file_name.php.
=== Copying or Creating Layout Files ===

The rhuk_milkyway template does not have any layout overrides for any modules. If we want to override the default layout for Latest News module, we need to copy this file:

/components/mod_latest_news/default.php

to this location, creating the approriate directories in the event they don't already exist:

/templates/rhuk_milkyway/html/mod_latest_news/default.php

You need to take a little care with overriding module layout because there are a number of different ways that modules can or have been designed so you need to treat each one individually.
== Module Chrome ==

"Joomla!" 1.0 had a number of fixed styles that could display a list of modules in a particular position. These where represented by numbers:

* 0 (the default) displayed modules in a vertical table
* 1 displayed them in a horizontal table
* -1 displayed the raw module output
* -2 displayed the modules in a XHTML compatible format with the title in a H3 tag.
* -3 displayed modules in a set of nested DIVs that allowed for rounded-corner techniques

It was a great system except for two things:

# Nobody could remember which number was which, and
# You couldn't expand on the styles.

Well, in 1.5, the numbers are still recognised, but more commonly the style is represented as a word. As well as that, the syntax for displaying a module position was changed. For example, this snippet displays each module in the left position in the xhtml style:
<source lang="php">
<jdoc:include type="modules" name="left" style="xhtml" />
</source>
The built-in styles that are now available are:

* table (was 0 and is the default)
* horz (was 1)
* none (was -1)
* xhtml (was -2)
* rounded (was -3)
* outline (new - used to preview module positions - see screenshot above)

In the source code, these styles are actually referred to ask "chrome". The default chrome can actually be found in the system template provided in the default "Joomla!" install:

/templates/system/html/modules.php

This file is maintained by the project so you should never modify it directly otherwise there is a risk that you will loose your changes if and when you upgrade your "Joomla!" installation.

To create your own chrome, or module styles, all you need to do is create or edit modules.php under the templates /html/ directory (this is the same directory we have been talking about for component and module layout overrides).

The rhuk_milkyway template actually does provide some extra chrome as an example (it provides and new example style called "slider"). This can be found in the following file:

/templates/rhuk_milkyway/html/modules.php

To create your own chrome is really easy. Let's look at ficticious example that displays the module in a Definition List (a set of DL's, DT's and DD's).

Just add the following function to the /html/modules.php file in your default template directory (create it if it does not exist):
<source lang="php">
/*
* Module chrome that wraps the module in a definition list
*/
function modChrome_dlist($module, &$params, &$attribs)
{ ?>
<dl class="<?php echo $params->get('moduleclass_sfx'); ?>">
<?php if ($module->showtitle != 0) : ?>
<dt>
<?php echo $module->title; ?>
</dt>
<?php endif; ?>
<dd>
<?php echo $module->content; ?>
</dd>
</dl>
<?php
}
</source>
We will be calling the style "dlist", so the name of the function needs to be modChrome_dlist.

The function must take the three arguments as shown for the module object, the module parameters, and lastly the $attribs is an array of all the attributes in the jdoc XML tag.

There are three main properties in the module object to be concerned with:

* showtitle tells you whether to show the title of the module of not
* title is the title of the module
* content is the output of the module (from its layout)

This is a very simple case and you can of course design more complex styles, possibly using custom atrributes in the XML tag.
== Pagination Links Overrides ==

The final override we will look at is the pagination override. This override can control the display of items-per-page and the pagination links that are used with lists of information, as shown in the following screenshot.

http://developer.joomla.org/images/tutorials/understanding_output/pagination_links.png

The rhuk_milkyway template provides a well commented example for this override. The file is found here:

/templates/rhuk_milkyway/html/pagination.php

When the pagination list is required, "Joomla!" will look for this file in the default templates. If it is found it will be loaded and the display functions it contains will be used.

There are four functions that can be used:

pagination_list_footer

This function is responsible for showing the select list for the number of items to display per page.

pagination_list_render

This function is responsible for showing the list of page number links as well at the Start, End, Previous and Next links.

pagination_item_active

This function displays the links to other page numbers other than the "current" page.

pagination_item_active

This function displays the current page number, usually not hyperlinked.
== Cheat Sheet ==

Using the rhuk_milkyway template as an example, here is a brief summary of the priniciples we've looked at.
=== Customise the Component Output ===

To override a component layout (for example the default layout in the article view), copy:

/components/com_content/views/article/tmpl/default.php

to:

/templates/rhuk_milkyway/html/com_content/article/default.php

Read more about component output.
=== Customise the Module Output ===

To override a module layout (for example the Latest News module using the rhuk_milkyway template), copy:

/components/mod_latest_news/default.php

to:

/templates/rhuk_milkyway/html/mod_latest_news/default.php

Read more about module output.
=== Add New Module Styles ===

To add new module styles (chrome), add them to the following file:

/templates/rhuk_milkyway/html/modules.php

Read more about module styles.
=== Customise the Pagination Links ===

To customise the way the items-per-page selector and pagination links display, edit the following file:

/templates/rhuk_milkyway/html/pagination.php

Read more about pagination.
== Conclusion ==

"Joomla!" 1.5, through the use of an MVC paradigm has greatly improved the flexibility that is afforded to Web site designers. By way of a few simple principles, like copying certain files to certain places in your template, the designer is able to override almost all of the output generated by "Joomla!".

If you have any questions relating to output overrides please let us know so that we can improve this tutorial.

If you have translated this article into another language, please let us know.

Understanding Output Overrides

2008-07-05T14:08:45Z

Instance: /* Template versus Layout */

= Understanding Output Overrides in "Joomla!" 1.5 =
Written by Andrew Eddie

This was Developer Blog post by Andrew, initially copied to the wiki with minor edits by Alan Langford. This is still a work in progress.
== Introduction ==
There are many competing requirements for web designers ranging from accessibility to legislative to personal preferences. Rather than trying to over-parameterise views, or trying to aim for some sort of line of best fit, or worse, sticking its head in the sand, "Joomla!" has added the potential for the designer to take over control of virtually all of the output that is generated.

"Joomla!" has been criticized by some for not giving due attention to accessibility or being archaic in their approach to web standards. However with 1.5, the responsibility, but more importantly the power is back in the designer's hands.

In addition, except for files that are provided in the "Joomla!" distribution itself, these methods for customisation eliminate the need for designers and developers to "hack" core files that could change when the site is updated to a new version. Because they are contained within the template, they can be deployed to the Web site without having to worry about changes being accidentally overwritten when your System Administrator upgrades the site.

The aim of this tutorial is to introduce the how fours areas of the output of "Joomla!" are able to be customised by the template designer.

Not interested in all the theory? Jump straight to the cheat sheet.
== MVC 101 ==
MVC can be a scary acronym. It stands for Model-View-Controller and the concepts behind MVC are responsible for the extra flexibility that is now afforded to the designer. While parts of the theory can be rather involved and complicated, the only part that the designer need worry about is the V for View. This is the part that is concerned with output.

Different extensions display output in different ways.

Components, as you would already know, are fairly complex and have the ability to display different information in different ways. For example, the Articles Component (com_content) is able to display a single article, or articles in a category, or categories in a section. Each of the ways of representing the different types of data (an article, or a category, or a section) is called a "view" (this comes from our MVC terminology). Most components will have many views. However, the view doesn't actually display the output. This is left up to what we call a "layout" and it is possible for a view to have a variety of layouts.

The main thing to remember here is that components can have multiple views, and each view can have one or more layouts. Each view assembles a fixed set of information, but each layout can display that information in different ways. For example, the Category view in the Articles component assembles a number of articles. These articles could be displayed in a list or in a table (and probably other ways as well). So this view may have a "list" layout and a "table" layout to choose from.

Modules, on the other hand, are very simple. They generally display one thing one way. Modules don't really have views but they do support a layout. Some developers might even support a choice of layout through module parameters.
=== Template versus Layout ===

It is very important to distinguish between the role of template and the role of layouts. The template sets up a structural framework for the page of the Web site. Within this framework are positions for modules and a component to display. What actually gets displayed is governed by the module layout, or the combination of view and layout in the case of the component.

The following image shows the structural layout of a typical "Joomla!" template (rhuk_milkyway, the default for 1.5). The module positions are displayed by adding tp=1 to the URL (eg, index.php?tp=1). You can clearly see where the module output is contained within the overall template, as well as the main component output starting in the lower-centre region. However, what is actually output in those regions, is controlled by the layouts.

[[Image:ForntpageTemplatePositions.png|Typical Joomla! screenshot with template positions shown.]]

=== Ancillary Customisation ===

While not strictly related to the MVC, there are two other important areas to consider when looking at customising the output of "Joomla!".

In addition to layouts, modules have what we call "chrome". Chrome is the style with which a module is to display. Most developers, designers and probably some end-users will be familiar with the different built-in styles for modules (raw, xhtml, etc). It is also possible to define your own chrome styles for modules depending on the designer result. For example, you could design a chrome to display all the modules in a particular position in a fancy Javascript collapsing blind arrangement.

In the screenshot above, you can just make out the names of some of the built-in module chrome used (rounded, none and xhtml).

The second area has to do with controlling the pagination controls when viewing lists of data. We will look at that in more detail later.
== Component Output Types and Layout Overrides ==

To understand layout overrides we must first understand the file structure of a component. While there are many parts to a component, all fulfilling different roles and responsibilities, we want to look just in the /views/ directory. Here is the partial structure for two of the com_content views:
<pre>
/components
/com_content
/views
/articles
/tmpl
default.php (this is a layout)
form.php (this is a layout)
view.html.php (this is the view that outputs the HTML)
view.pdf.php (this is the view that outputs the PDF)
/category
/tmpl
blog.php (layout)
blog_items.php (a sub-layout
default.php (layout)
view.html.php (HTML view)
view.feed.php (RSS feed)
</pre>
So what you see here is that under the /views/ directory, each view is placed in a directory of its own. The content component actually has three other views not shown: archive, frontpage and section.
=== Output Types ===
Under the /articles/ directory we have a number of files. There is almost always a file called view.html.php. This is what we call the view file, but there can be more than one depending on the type of output to produce. It has a specific naming convention, view.output_type.php, where the output type can be html, feed, pdf, raw or error (for more information see JDocument in the API reference and look in the directory /libraries/joomla/document/). What this means is when we want html output for this particular view, the view.html.php file is used. When we want the RSS output, the view.feed.php file is used.

The affect of these different output types is most apparent when the Global Configuration setting for Search Engine Friendly URLs is set to Yes, Use Apache mod_rewrite is set to Yes, and Add suffix to URLs is also set to Yes. When this is done, the site URLs will look something like this:

<pre>
http://domain/sports.html
http://domain/sports.feed
http://domain/sports/rowing.html
http://domain/sports/rowing.pdf
</pre>
The exact URL will vary depending on how you set up your site but the point here is to show that sports.html will use the category view's view.html.php file to, and that sports.feed will display the RSS feed for the category using view.feed.php. It should be noted that you cannot currently customise feed or PDF output types. However, you can customise the html output type and this is where layouts come into play.

=== Layouts ===
Under the view directory there is a /tmpl/ directory in which the layout files reside. Each PHP file in this directory represents a layout. For example, article/tmpl/default.php is the default layout for an article whereas article/tmpl/form.php is the edit form for an article; category/tmpl/default.php is the default layout for a category whereas category/tmpl/blog.php displays the list of article differently.

The relationship between component views and layout is most plainly seen when adding a new menu item. The next screenshot represents the typical display of the New Menu Item page. Having clicked on Articles (which represents com_content), the tree expands to show the list of views and each layout within the view.

http://developer.joomla.org/images/tutorials/understanding_output/menu_item_new.png

You will notice that while there are extra files in some of the /tmpl/ directories (like pagebreak.php in the article view), they are missing from the list. This is due to instructions in the XML file for the layout (for example, pagebreak.xml) to hide the layout (or even the view) from the menu item list. However, this is another broad topic which will be covered in another tutorial.

Armed with all that knowledge of how all the parts relate to each other, we are now ready to actually create our layout overrides.
=== Copying or Creating Layout Files ===

Layout overrides only work within the active template and are located under the /html/ directory in the template. For example, the overrides for rhuk_milkyway are located under /templates/rhuk_milkyway/html/, for the JA Purity template under /templates/ja_purity/html/ and for Beez under /templates/beez/html/.

It is important to understand that if you create overrides in one template, they will not be available in other templates. For example, rhuk_milkyway has no component layout overrides at all. When you use this template you are seeing the raw output from all components. When you use the Beez template, almost every piece of component output is being controlled by the layout overrides in the template. JA Purity is in between having overrides for some components and only some views of those components.

The layout overrides must be placed in particular way. Using Beez as an example you will see the following structure:
<pre>
/templates
/beez
/html
/com_content (this directory matches the component directory name)
/articles (this directory matches the view directory name)
default.php (this file matches the layout file name)
form.php
</pre>

The structure for component overrides is quite simple: /html/com_component_name/view_name/layout_file_name.php. Let's look at a few examples.

The rhuk_milkyway template does not have any layout overrides for any components. If we want to override the default layout for an article, first we need to copy this file:

/components/com_content/views/article/tmpl/default.php

to this location, creating the appropriate directories in the event they don't already exist:

/templates/rhuk_milkyway/html/com_content/article/default.php

If we wanted to override the blog layout in the category view, we would copy this file:

/components/com_content/views/category/tmpl/blog.php

to:

/templates/rhuk_milkyway/html/com_content/category/blog.php

Once the files are copied, you are free to customise these files as much or as little as required or desired. You do not have to honour parameter settings if you don't want to.
=== Overriding Sub-Layouts ===

In some views you will see that some of the layouts have a group of files that start with the same name. The category view has an example of this. The blog layout actually has three parts: the main layout file blog.php and two sub-layout files, blog_item.php and blog_links.php. You can see where these sub-layouts are loaded in the blog.php file using the loadTemplate method, for example:
<source lang="php">
echo $this->loadTemplate('item');
// or
echo $this->loadTemplate('links');
</source>
When loading sub-layouts, the view already knows what layout you are in, so you don't have to provide the prefix (that is, you load just 'item', not 'blog_item').

What is important to note here is that it is possible to override just a sub-layout without copying the whole set of files. For example, if you were happy with the "Joomla!" default output for the blog layout, but just wanted to customise the item sub-layout, you could just copy:

/components/com_content/views/category/tmpl/blog_item.php

to:

/templates/rhuk_milkyway/html/com_content/category/blog_item.php

When "Joomla!" is parsing the view, it will automatically know to load blog.php from com_content natively and blog_item.php from your template overrides.
== Module Layout Overrides ==

Modules, like components, are set up in a particular directory structure.
<pre>
/modules
/mod_latest_news
/tmpl
default.php (the layout)
helper.php (a helper file containing data logic)
mod_latest_news.php (the main module file)
mod_latest_news.xml (the installation XML file)
</pre>
Similar to components, under the main module directory (in the example, mod_latest_news) there is a /tmpl/ directory. There is usually only one layout file but depending on who wrote the module, and how it is written, there could be more.

As for components, the layout override for a module must be placed in particular way. Using Beez as an example again, you will see the following structure:
<pre>
/templates
/beez
/html
/mod_latest_news.php (this directory matches the module directory name)
default.php (this file matches the layout file name)
</pre>
The structure for module overrides is again quite simple: /html/mod_module_name/layout_file_name.php.
=== Copying or Creating Layout Files ===

The rhuk_milkyway template does not have any layout overrides for any modules. If we want to override the default layout for Latest News module, we need to copy this file:

/components/mod_latest_news/default.php

to this location, creating the approriate directories in the event they don't already exist:

/templates/rhuk_milkyway/html/mod_latest_news/default.php

You need to take a little care with overriding module layout because there are a number of different ways that modules can or have been designed so you need to treat each one individually.
== Module Chrome ==

"Joomla!" 1.0 had a number of fixed styles that could display a list of modules in a particular position. These where represented by numbers:

* 0 (the default) displayed modules in a vertical table
* 1 displayed them in a horizontal table
* -1 displayed the raw module output
* -2 displayed the modules in a XHTML compatible format with the title in a H3 tag.
* -3 displayed modules in a set of nested DIVs that allowed for rounded-corner techniques

It was a great system except for two things:

# Nobody could remember which number was which, and
# You couldn't expand on the styles.

Well, in 1.5, the numbers are still recognised, but more commonly the style is represented as a word. As well as that, the syntax for displaying a module position was changed. For example, this snippet displays each module in the left position in the xhtml style:
<source lang="php">
<jdoc:include type="modules" name="left" style="xhtml" />
</source>
The built-in styles that are now available are:

* table (was 0 and is the default)
* horz (was 1)
* none (was -1)
* xhtml (was -2)
* rounded (was -3)
* outline (new - used to preview module positions - see screenshot above)

In the source code, these styles are actually referred to ask "chrome". The default chrome can actually be found in the system template provided in the default "Joomla!" install:

/templates/system/html/modules.php

This file is maintained by the project so you should never modify it directly otherwise there is a risk that you will loose your changes if and when you upgrade your "Joomla!" installation.

To create your own chrome, or module styles, all you need to do is create or edit modules.php under the templates /html/ directory (this is the same directory we have been talking about for component and module layout overrides).

The rhuk_milkyway template actually does provide some extra chrome as an example (it provides and new example style called "slider"). This can be found in the following file:

/templates/rhuk_milkyway/html/modules.php

To create your own chrome is really easy. Let's look at ficticious example that displays the module in a Definition List (a set of DL's, DT's and DD's).

Just add the following function to the /html/modules.php file in your default template directory (create it if it does not exist):
<source lang="php">
/*
* Module chrome that wraps the module in a definition list
*/
function modChrome_dlist($module, &$params, &$attribs)
{ ?>
<dl class="<?php echo $params->get('moduleclass_sfx'); ?>">
<?php if ($module->showtitle != 0) : ?>
<dt>
<?php echo $module->title; ?>
</dt>
<?php endif; ?>
<dd>
<?php echo $module->content; ?>
</dd>
</dl>
<?php
}
</source>
We will be calling the style "dlist", so the name of the function needs to be modChrome_dlist.

The function must take the three arguments as shown for the module object, the module parameters, and lastly the $attribs is an array of all the attributes in the jdoc XML tag.

There are three main properties in the module object to be concerned with:

* showtitle tells you whether to show the title of the module of not
* title is the title of the module
* content is the output of the module (from its layout)

This is a very simple case and you can of course design more complex styles, possibly using custom atrributes in the XML tag.
== Pagination Links Overrides ==

The final override we will look at is the pagination override. This override can control the display of items-per-page and the pagination links that are used with lists of information, as shown in the following screenshot.

http://developer.joomla.org/images/tutorials/understanding_output/pagination_links.png

The rhuk_milkyway template provides a well commented example for this override. The file is found here:

/templates/rhuk_milkyway/html/pagination.php

When the pagination list is required, "Joomla!" will look for this file in the default templates. If it is found it will be loaded and the display functions it contains will be used.

There are four functions that can be used:

pagination_list_footer

This function is responsible for showing the select list for the number of items to display per page.

pagination_list_render

This function is responsible for showing the list of page number links as well at the Start, End, Previous and Next links.

pagination_item_active

This function displays the links to other page numbers other than the "current" page.

pagination_item_active

This function displays the current page number, usually not hyperlinked.
== Cheat Sheet ==

Using the rhuk_milkyway template as an example, here is a brief summary of the priniciples we've looked at.
=== Customise the Component Output ===

To override a component layout (for example the default layout in the article view), copy:

/components/com_content/views/article/tmpl/default.php

to:

/templates/rhuk_milkyway/html/com_content/article/default.php

Read more about component output.
=== Customise the Module Output ===

To override a module layout (for example the Latest News module using the rhuk_milkyway template), copy:

/components/mod_latest_news/default.php

to:

/templates/rhuk_milkyway/html/mod_latest_news/default.php

Read more about module output.
=== Add New Module Styles ===

To add new module styles (chrome), add them to the following file:

/templates/rhuk_milkyway/html/modules.php

Read more about module styles.
=== Customise the Pagination Links ===

To customise the way the items-per-page selector and pagination links display, edit the following file:

/templates/rhuk_milkyway/html/pagination.php

Read more about pagination.
== Conclusion ==

"Joomla!" 1.5, through the use of an MVC paradigm has greatly improved the flexibility that is afforded to Web site designers. By way of a few simple principles, like copying certain files to certain places in your template, the designer is able to override almost all of the output generated by "Joomla!".

If you have any questions relating to output overrides please let us know so that we can improve this tutorial.

If you have translated this article into another language, please let us know.

File:FrontpageTemplatePositions.png

2008-07-05T14:05:37Z

Instance: Typical "Joomla!" screenshot with template positions shown.

== Summary ==
Typical "Joomla!" screenshot with template positions shown.
== Licensing ==
{{JEDL}}

Understanding Output Overrides

2008-07-05T13:57:29Z

Instance: Wikification of Andrew's blog post.

= Understanding Output Overrides in "Joomla!" 1.5 =
Written by Andrew Eddie

This was Developer Blog post by Andrew, initially copied to the wiki with minor edits by Alan Langford. This is still a work in progress.
== Introduction ==
There are many competing requirements for web designers ranging from accessibility to legislative to personal preferences. Rather than trying to over-parameterise views, or trying to aim for some sort of line of best fit, or worse, sticking its head in the sand, "Joomla!" has added the potential for the designer to take over control of virtually all of the output that is generated.

"Joomla!" has been criticized by some for not giving due attention to accessibility or being archaic in their approach to web standards. However with 1.5, the responsibility, but more importantly the power is back in the designer's hands.

In addition, except for files that are provided in the "Joomla!" distribution itself, these methods for customisation eliminate the need for designers and developers to "hack" core files that could change when the site is updated to a new version. Because they are contained within the template, they can be deployed to the Web site without having to worry about changes being accidentally overwritten when your System Administrator upgrades the site.

The aim of this tutorial is to introduce the how fours areas of the output of "Joomla!" are able to be customised by the template designer.

Not interested in all the theory? Jump straight to the cheat sheet.
== MVC 101 ==
MVC can be a scary acronym. It stands for Model-View-Controller and the concepts behind MVC are responsible for the extra flexibility that is now afforded to the designer. While parts of the theory can be rather involved and complicated, the only part that the designer need worry about is the V for View. This is the part that is concerned with output.

Different extensions display output in different ways.

Components, as you would already know, are fairly complex and have the ability to display different information in different ways. For example, the Articles Component (com_content) is able to display a single article, or articles in a category, or categories in a section. Each of the ways of representing the different types of data (an article, or a category, or a section) is called a "view" (this comes from our MVC terminology). Most components will have many views. However, the view doesn't actually display the output. This is left up to what we call a "layout" and it is possible for a view to have a variety of layouts.

The main thing to remember here is that components can have multiple views, and each view can have one or more layouts. Each view assembles a fixed set of information, but each layout can display that information in different ways. For example, the Category view in the Articles component assembles a number of articles. These articles could be displayed in a list or in a table (and probably other ways as well). So this view may have a "list" layout and a "table" layout to choose from.

Modules, on the other hand, are very simple. They generally display one thing one way. Modules don't really have views but they do support a layout. Some developers might even support a choice of layout through module parameters.
=== Template versus Layout ===

It is very important to distinguish between the role of template and the role of layouts. The template sets up a structural framework for the page of the Web site. Within this framework are positions for modules and a component to display. What actually gets displayed is governed by the module layout, or the combination of view and layout in the case of the component.

The following image shows the structural layout of a typical "Joomla!" template (rhuk_milkyway, the default for 1.5). The module positions are displayed by adding tp=1 to the URL (eg, index.php?tp=1). You can clearly see where the module output is contained within the overall template, as well as the main component output starting in the lower-centre region. However, what is actually output in those regions, is controlled by the layouts.

http://developer.joomla.org/images/tutorials/understanding_output/frontpage_tp1.png
=== Ancillary Customisation ===

While not strictly related to the MVC, there are two other important areas to consider when looking at customising the output of "Joomla!".

In addition to layouts, modules have what we call "chrome". Chrome is the style with which a module is to display. Most developers, designers and probably some end-users will be familiar with the different built-in styles for modules (raw, xhtml, etc). It is also possible to define your own chrome styles for modules depending on the designer result. For example, you could design a chrome to display all the modules in a particular position in a fancy Javascript collapsing blind arrangement.

In the screenshot above, you can just make out the names of some of the built-in module chrome used (rounded, none and xhtml).

The second area has to do with controlling the pagination controls when viewing lists of data. We will look at that in more detail later.
== Component Output Types and Layout Overrides ==

To understand layout overrides we must first understand the file structure of a component. While there are many parts to a component, all fulfilling different roles and responsibilities, we want to look just in the /views/ directory. Here is the partial structure for two of the com_content views:
<pre>
/components
/com_content
/views
/articles
/tmpl
default.php (this is a layout)
form.php (this is a layout)
view.html.php (this is the view that outputs the HTML)
view.pdf.php (this is the view that outputs the PDF)
/category
/tmpl
blog.php (layout)
blog_items.php (a sub-layout
default.php (layout)
view.html.php (HTML view)
view.feed.php (RSS feed)
</pre>
So what you see here is that under the /views/ directory, each view is placed in a directory of its own. The content component actually has three other views not shown: archive, frontpage and section.
=== Output Types ===
Under the /articles/ directory we have a number of files. There is almost always a file called view.html.php. This is what we call the view file, but there can be more than one depending on the type of output to produce. It has a specific naming convention, view.output_type.php, where the output type can be html, feed, pdf, raw or error (for more information see JDocument in the API reference and look in the directory /libraries/joomla/document/). What this means is when we want html output for this particular view, the view.html.php file is used. When we want the RSS output, the view.feed.php file is used.

The affect of these different output types is most apparent when the Global Configuration setting for Search Engine Friendly URLs is set to Yes, Use Apache mod_rewrite is set to Yes, and Add suffix to URLs is also set to Yes. When this is done, the site URLs will look something like this:

<pre>
http://domain/sports.html
http://domain/sports.feed
http://domain/sports/rowing.html
http://domain/sports/rowing.pdf
</pre>
The exact URL will vary depending on how you set up your site but the point here is to show that sports.html will use the category view's view.html.php file to, and that sports.feed will display the RSS feed for the category using view.feed.php. It should be noted that you cannot currently customise feed or PDF output types. However, you can customise the html output type and this is where layouts come into play.

=== Layouts ===
Under the view directory there is a /tmpl/ directory in which the layout files reside. Each PHP file in this directory represents a layout. For example, article/tmpl/default.php is the default layout for an article whereas article/tmpl/form.php is the edit form for an article; category/tmpl/default.php is the default layout for a category whereas category/tmpl/blog.php displays the list of article differently.

The relationship between component views and layout is most plainly seen when adding a new menu item. The next screenshot represents the typical display of the New Menu Item page. Having clicked on Articles (which represents com_content), the tree expands to show the list of views and each layout within the view.

http://developer.joomla.org/images/tutorials/understanding_output/menu_item_new.png

You will notice that while there are extra files in some of the /tmpl/ directories (like pagebreak.php in the article view), they are missing from the list. This is due to instructions in the XML file for the layout (for example, pagebreak.xml) to hide the layout (or even the view) from the menu item list. However, this is another broad topic which will be covered in another tutorial.

Armed with all that knowledge of how all the parts relate to each other, we are now ready to actually create our layout overrides.
=== Copying or Creating Layout Files ===

Layout overrides only work within the active template and are located under the /html/ directory in the template. For example, the overrides for rhuk_milkyway are located under /templates/rhuk_milkyway/html/, for the JA Purity template under /templates/ja_purity/html/ and for Beez under /templates/beez/html/.

It is important to understand that if you create overrides in one template, they will not be available in other templates. For example, rhuk_milkyway has no component layout overrides at all. When you use this template you are seeing the raw output from all components. When you use the Beez template, almost every piece of component output is being controlled by the layout overrides in the template. JA Purity is in between having overrides for some components and only some views of those components.

The layout overrides must be placed in particular way. Using Beez as an example you will see the following structure:
<pre>
/templates
/beez
/html
/com_content (this directory matches the component directory name)
/articles (this directory matches the view directory name)
default.php (this file matches the layout file name)
form.php
</pre>

The structure for component overrides is quite simple: /html/com_component_name/view_name/layout_file_name.php. Let's look at a few examples.

The rhuk_milkyway template does not have any layout overrides for any components. If we want to override the default layout for an article, first we need to copy this file:

/components/com_content/views/article/tmpl/default.php

to this location, creating the appropriate directories in the event they don't already exist:

/templates/rhuk_milkyway/html/com_content/article/default.php

If we wanted to override the blog layout in the category view, we would copy this file:

/components/com_content/views/category/tmpl/blog.php

to:

/templates/rhuk_milkyway/html/com_content/category/blog.php

Once the files are copied, you are free to customise these files as much or as little as required or desired. You do not have to honour parameter settings if you don't want to.
=== Overriding Sub-Layouts ===

In some views you will see that some of the layouts have a group of files that start with the same name. The category view has an example of this. The blog layout actually has three parts: the main layout file blog.php and two sub-layout files, blog_item.php and blog_links.php. You can see where these sub-layouts are loaded in the blog.php file using the loadTemplate method, for example:
<source lang="php">
echo $this->loadTemplate('item');
// or
echo $this->loadTemplate('links');
</source>
When loading sub-layouts, the view already knows what layout you are in, so you don't have to provide the prefix (that is, you load just 'item', not 'blog_item').

What is important to note here is that it is possible to override just a sub-layout without copying the whole set of files. For example, if you were happy with the "Joomla!" default output for the blog layout, but just wanted to customise the item sub-layout, you could just copy:

/components/com_content/views/category/tmpl/blog_item.php

to:

/templates/rhuk_milkyway/html/com_content/category/blog_item.php

When "Joomla!" is parsing the view, it will automatically know to load blog.php from com_content natively and blog_item.php from your template overrides.
== Module Layout Overrides ==

Modules, like components, are set up in a particular directory structure.
<pre>
/modules
/mod_latest_news
/tmpl
default.php (the layout)
helper.php (a helper file containing data logic)
mod_latest_news.php (the main module file)
mod_latest_news.xml (the installation XML file)
</pre>
Similar to components, under the main module directory (in the example, mod_latest_news) there is a /tmpl/ directory. There is usually only one layout file but depending on who wrote the module, and how it is written, there could be more.

As for components, the layout override for a module must be placed in particular way. Using Beez as an example again, you will see the following structure:
<pre>
/templates
/beez
/html
/mod_latest_news.php (this directory matches the module directory name)
default.php (this file matches the layout file name)
</pre>
The structure for module overrides is again quite simple: /html/mod_module_name/layout_file_name.php.
=== Copying or Creating Layout Files ===

The rhuk_milkyway template does not have any layout overrides for any modules. If we want to override the default layout for Latest News module, we need to copy this file:

/components/mod_latest_news/default.php

to this location, creating the approriate directories in the event they don't already exist:

/templates/rhuk_milkyway/html/mod_latest_news/default.php

You need to take a little care with overriding module layout because there are a number of different ways that modules can or have been designed so you need to treat each one individually.
== Module Chrome ==

"Joomla!" 1.0 had a number of fixed styles that could display a list of modules in a particular position. These where represented by numbers:

* 0 (the default) displayed modules in a vertical table
* 1 displayed them in a horizontal table
* -1 displayed the raw module output
* -2 displayed the modules in a XHTML compatible format with the title in a H3 tag.
* -3 displayed modules in a set of nested DIVs that allowed for rounded-corner techniques

It was a great system except for two things:

# Nobody could remember which number was which, and
# You couldn't expand on the styles.

Well, in 1.5, the numbers are still recognised, but more commonly the style is represented as a word. As well as that, the syntax for displaying a module position was changed. For example, this snippet displays each module in the left position in the xhtml style:
<source lang="php">
<jdoc:include type="modules" name="left" style="xhtml" />
</source>
The built-in styles that are now available are:

* table (was 0 and is the default)
* horz (was 1)
* none (was -1)
* xhtml (was -2)
* rounded (was -3)
* outline (new - used to preview module positions - see screenshot above)

In the source code, these styles are actually referred to ask "chrome". The default chrome can actually be found in the system template provided in the default "Joomla!" install:

/templates/system/html/modules.php

This file is maintained by the project so you should never modify it directly otherwise there is a risk that you will loose your changes if and when you upgrade your "Joomla!" installation.

To create your own chrome, or module styles, all you need to do is create or edit modules.php under the templates /html/ directory (this is the same directory we have been talking about for component and module layout overrides).

The rhuk_milkyway template actually does provide some extra chrome as an example (it provides and new example style called "slider"). This can be found in the following file:

/templates/rhuk_milkyway/html/modules.php

To create your own chrome is really easy. Let's look at ficticious example that displays the module in a Definition List (a set of DL's, DT's and DD's).

Just add the following function to the /html/modules.php file in your default template directory (create it if it does not exist):
<source lang="php">
/*
* Module chrome that wraps the module in a definition list
*/
function modChrome_dlist($module, &$params, &$attribs)
{ ?>
<dl class="<?php echo $params->get('moduleclass_sfx'); ?>">
<?php if ($module->showtitle != 0) : ?>
<dt>
<?php echo $module->title; ?>
</dt>
<?php endif; ?>
<dd>
<?php echo $module->content; ?>
</dd>
</dl>
<?php
}
</source>
We will be calling the style "dlist", so the name of the function needs to be modChrome_dlist.

The function must take the three arguments as shown for the module object, the module parameters, and lastly the $attribs is an array of all the attributes in the jdoc XML tag.

There are three main properties in the module object to be concerned with:

* showtitle tells you whether to show the title of the module of not
* title is the title of the module
* content is the output of the module (from its layout)

This is a very simple case and you can of course design more complex styles, possibly using custom atrributes in the XML tag.
== Pagination Links Overrides ==

The final override we will look at is the pagination override. This override can control the display of items-per-page and the pagination links that are used with lists of information, as shown in the following screenshot.

http://developer.joomla.org/images/tutorials/understanding_output/pagination_links.png

The rhuk_milkyway template provides a well commented example for this override. The file is found here:

/templates/rhuk_milkyway/html/pagination.php

When the pagination list is required, "Joomla!" will look for this file in the default templates. If it is found it will be loaded and the display functions it contains will be used.

There are four functions that can be used:

pagination_list_footer

This function is responsible for showing the select list for the number of items to display per page.

pagination_list_render

This function is responsible for showing the list of page number links as well at the Start, End, Previous and Next links.

pagination_item_active

This function displays the links to other page numbers other than the "current" page.

pagination_item_active

This function displays the current page number, usually not hyperlinked.
== Cheat Sheet ==

Using the rhuk_milkyway template as an example, here is a brief summary of the priniciples we've looked at.
=== Customise the Component Output ===

To override a component layout (for example the default layout in the article view), copy:

/components/com_content/views/article/tmpl/default.php

to:

/templates/rhuk_milkyway/html/com_content/article/default.php

Read more about component output.
=== Customise the Module Output ===

To override a module layout (for example the Latest News module using the rhuk_milkyway template), copy:

/components/mod_latest_news/default.php

to:

/templates/rhuk_milkyway/html/mod_latest_news/default.php

Read more about module output.
=== Add New Module Styles ===

To add new module styles (chrome), add them to the following file:

/templates/rhuk_milkyway/html/modules.php

Read more about module styles.
=== Customise the Pagination Links ===

To customise the way the items-per-page selector and pagination links display, edit the following file:

/templates/rhuk_milkyway/html/pagination.php

Read more about pagination.
== Conclusion ==

"Joomla!" 1.5, through the use of an MVC paradigm has greatly improved the flexibility that is afforded to Web site designers. By way of a few simple principles, like copying certain files to certain places in your template, the designer is able to override almost all of the output generated by "Joomla!".

If you have any questions relating to output overrides please let us know so that we can improve this tutorial.

If you have translated this article into another language, please let us know.

J1.5:Template FAQs

2008-07-02T18:05:30Z

Instance: /* CSS Text/Font Resizing (A+ A-) on Joomla Template */

{{review}}

===What is a template?===

The [[Template]] controls the overall look and layout of your site. It provides the framework that brings together common elements, [[Modules|modules]] and [[Components|components]] as well as providing the [[CSS|cascading style sheet]] for your site. Both the [[Front-end]] (Site) and the [[Back-end]] (Administrator) of your site have templates.

When Joomla! is installed several templates are automatically included. You can find many more templates at other websites. Some are available without charge under various licenses, and some are for sale. In addition, there are many designers available who can make custom templates. You can also [[Joomla! 1.5 Template Tutorials Project|make your own template]].

Templates are managed with the [[Template Manager]], which is located on the site menu on the Back-end of your site.

The following may be helpful in understanding templates:
* http://help.joomla.org/content/view/474/153/

===How do I install a new template?===
'''1.0'''

In the [[Back-end]] of the site, go to [[Installer]]s>>Templates-Site (or Templates-Administrator if you are installing an administrator template).

Browse for the template zip file and click ''Upload File'' and ''Install''.

Alternatively, you can install from a directory.

To make the new template the default template for your site, go to the [[Template Manager]] (Site>>Template Manager>>Site Templates).
You should see the name of your new template on the list of templates.

Select it and click on the default icon if you want it to be the default icon for your site.

'''1.5'''

In the [[Back-end]] of the site, go to [[Extension]]s>>Install/Uninstall.

Browse for the template zip file and click Upload File and Install.

Alternatively, you can install from a directory.

To make the new template the default template for your site, select it and click the default icon (star).

===How do I modify a template?===
Templates are just a series of xml, php, html and image files that are stored in the templates directory of your site.
You can edit these files or you can use the editing interface available in the [[Template Manager]].

'''1.0'''

In the [[Back-end]], select Site>>Template Manager>>Site Templates.

Select the template you wish to modify.

'''1.5'''

In the [[Back-end]], select Site>>[[Extension]]s>>Templates.
Select the template you wish to modify.
Click the edit icon.

'''both'''
You are given the choice of editing "html" and "css."

[[CSS]] stands for cascading style sheets. This controls many elements of the look and feel of your site.
[[HTML]] is the file that controls where positions are defined and positioned. Other than that, it should be noted that, with a few exceptions, what is in the .css and what is in the HTML files largely depends on the approach of the tempate designer.

One common change is to use your own graphic/image. Graphics are linked to in the HTML file. Simply change the reference to the image of your choice. Keep in mind that it if it is a different size than the original image this may change the appearance of the site in unexpected ways.

===How do I assign a template to a specific page?===

In Joomla! there is a default template, but you can assign other templates to specific "pages" that are defined by menu links.

To assign a template to a page, you must first make sure that there is a direct menu link to the page.

'''1.0'''
* Go to Site>>[[Template Manager]]>>Site Templates
* Select the template you wish to assign.
* Click on the assign icon.
* On the right, there will be a list with all of the possible pages the template can be assigned to. Select one or more pages and save.

'''1.5'''

* Go to [[Extension]]s>>[[Template Manager]]
* Select the Template and click the edit icon (or click the template name)
* In the left column, change "None" to "Select from List."
* Select the links you want to apply the template to.
* Save

Note that you cannot assign the default template to individual pages.

'''Understanding'''

The templating system uses the [[ItemID]] to determine which template to show. ItemIDs are created when you create a menu link. This is why only menu items are shown in the list of pages to which you can assign templates.

===What are the base Joomla! CSS styles?===

'''1.0'''

Provided by Haaris

/**com_contact**/
.componentheading
.contentpane
.contentdescription
.sectiontableheader
.category
.small
.contentpane
.contentheading
.contact_email
.inputbox
.button

/**com_content**/
.componentheading
.contentpane
.contentdescription
.inputbox
.sectiontableheader
.sectiontableentry1
.sectiontableentry2
.sectiontablefooter
.blogsection
.contentpaneopen
.article_seperator
.contentheading
.contentpagetitle
.buttonheading
.small
.createdate
.modifydate
.readon
.pagenav_prev
.pagenav_next
.adminform
.button
.text_area
.blog
.blog_more

/**com_login**/
.contentpane
.componentheading
.inputbox
.button

/**com_newsfeeds**/
.componentheading
.contentpane
.contentdescription
.sectiontableheader
.category
.small
.contentheading

/**com_poll**/
.componentheading
.contentpane
.pollstableborder
.sectiontableheader
.smalldark
.button
.inputbox

/**com_registration**/
.componentheading
.contentpane
.inputbox
.button

/**com_search**/
.componentheading
.contentpaneopen
.inputbox
.button
.searchintro
.small
.highlight

/**com_user**/
.componentheading
.inputbox
.button
.row1
.row2

/**com_weblinks**/
.componentheading
.contentpane
.contentdescription
.sectiontableheader
.tabclass1
.tabclass2
.small
.category
.inputbox

/**com_wrapper**/
.contentpane
.componentheading
.wrapper

/**includes/frontend**/
.moduletable
.newsfeed
.module
.message

/**includes\HTML_toolbar .php**/
.toolbar

/**includes\joomla .php**/
.profiler
.item
.small
.back_button
.buttonheading
.tab-page
.tab
.inputbox

/**includes\joomla .xml .php**/
.paramlist
.editlinktip
.text_area
.inputbox

/**includes\pageNavigation .php**/
.inputbox
.pagenav

/**includes\pathway .php**/
.pathway

/**includes\js\dtree\dtree .js**/
.dtree
.dTreeNode
.node
.clip

/**includes\patTemplate\tmpl\forms .html**/
.message
.tooltip
.tab-page
.tab
.expander

/**mambots\content\mosimage .php**/
.mosimage_caption
.mosimage

/**mambots\content\mospaging .php**/
.pagenavcounter
.pagenavbar
.contenttoc
.toclink

/**mambots\content\mosvote .php**/
.content_rating
.content_vote
.button

/**modules\mod_latestnews .php**/
.latestnews

/**modules\mod_login .php**/
.button
.inputbox

/**modules\mod_mostread .php**/
.mostread

/**modules\mod_mostread .php**/
.poll
.pollstableborder
.button

/**modules\mod_mostread .php**/
.syndicate
.syndicate_text

/**modules\mod_search .php**/
.inputbox
.button
.search

Provided by Compass:

#active_menu
#blockrandom
#contact_email_copy
#contact_text
#emailForm
#mod_login_password
#mod_login_remember
#mod_login_username
#poll
#search_ordering
#search_searchword
#searchphraseall
#searchphraseany
#searchphraseexact
#voteid1, #voteid2
.adminform
.article_seperator
.back_button
.blog
.blog_more
.blogsection
.button
.buttonheading
.category
.clr
.componentheading
.contact_email
.content_rating
.content_vote
.contentdescription
.contentheading
.contentpagetitle
.contentpane
.contentpaneopen
.contenttoc
.createdate
.fase4rdf
.footer
.frontpageheader
.inputbox
.latestnews
.mainlevel
.message
.modifydate
.module
.moduletable
.mostread
.newsfeed
.newsfeeddate
.newsfeedheading
.pagenav
.pagenav_next
.pagenav_prev
.pagenavbar
.pagenavcounter
.pathway
.polls
.pollsborder
.pollstableborder
.readon
.readon:hover
.search
.searchintro
.sectionentry1
.sectionentry2
.sectionheader
.sitetitle
.small
.smalldark
.sublevel
.syndicate
.syndicate_text
.text_area
.toclink
.weblinks
.wrapper

===What are module switches? (or -1 -2 and -3) ===
This is how you apply the switches:

; <nowiki>switch: -1</nowiki>
: Strips all surrounding code from the module.

<source lang="php">
<?php mosLoadModules ( 'user1', -1 ); ?>
</source>

The outputted html code looks like this:
<source lang="html4strict">
<div class="user1_inner">
<ul class="latestnews">
<li class="latestnews">
<a href="http://localhost/projects/1112rc2/index.php?option=com_content&task=view&id=3&Itemid=9"
class="latestnews">Newsflash 2
</a>
</li>
<li class="latestnews">
<a href="http://localhost/projects/1112rc2/index.php?option=com_content&task=view&id=4&Itemid=9"
class="latestnews">Newsflash 3
</a>
</li>
<li class="latestnews">
<a href="http://localhost/projects/1112rc2/index.php?option=com_content&task=view&id=2&Itemid=9"
class="latestnews">Newsflash 1
</a>
</li>
<li class="latestnews">
<a href="http://localhost/projects/1112rc2/index.php?option=com_content&task=view&id=9&Itemid=2"
class="latestnews">
Example News Item 4
</a>
</li>
<li class="latestnews">
<a href="http://localhost/projects/1112rc2/index.php?option=com_content&task=view&id=7&Itemid=2"
class="latestnews">
Example News Item 2
</a>
</li>
</ul>
</div>
</source>

; <nowiki>switch: -2</nowiki>
: Puts the module's title in a h3, and wraps the entire thing in a

<source lang="php">
<?php mosLoadModules ( 'user1', -2 ); ?>
</source>
The outputted html code looks like this:
<source lang="html4strict">
<div class="moduletable">
<h3>Latest News</h3>
<ul class="latestnews">
<li class="latestnews">
<a href="http://localhost/projects/1112rc2/index.php?option=com_content&task=view&id=4&Itemid=9"
class="latestnews">Newsflash 3
</a>
</li>
<li class="latestnews">
<a href="http://localhost/projects/1112rc2/index.php?option=com_content&task=view&id=2&Itemid=9"
class="latestnews">Newsflash 1
</a>
</li>
<li class="latestnews">
<a href="http://localhost/projects/1112rc2/index.php?option=com_content&task=view&id=3&Itemid=9"
class="latestnews">Newsflash 2
</a>
</li>
<li class="latestnews">
<a href="http://localhost/projects/1112rc2/index.php?option=com_content&task=view&id=6&Itemid=2"
class="latestnews">Example News Item 1
</a>
</li>
<li class="latestnews">
<a href="http://localhost/projects/1112rc2/index.php?option=com_content&task=view&id=9&Itemid=2"
class="latestnews">Example News Item 4
</a>
</li>
</ul>
</div>
</source>

;<nowiki>switch: -3</nowiki>
:Puts the module's title in a h3, and ads several layers of divs that can be used to apply [[CSS]] techniques with [[Rounded corners|rounded corners]]

<source lang="php">
<?php mosLoadModules ( 'user1', -3 ); ?>
</source>
The outputted code looks like this:
<source lang="html4strict">
<div class="module">
<div>
<div>
<div>
<h3>Latest News</h3>
<ul class="latestnews">
<li class="latestnews">
<a href="http://localhost/projects/1112rc2/index.php?option=com_content&task=view&id=4&Itemid=9"
class="latestnews">Newsflash 3
</a>
</li>
<li class="latestnews">
<a href="http://localhost/projects/1112rc2/index.php?option=com_content&task=view&id=2&Itemid=9"
class="latestnews">Newsflash 1
</a>
</li>
<li class="latestnews">
<a href="http://localhost/projects/1112rc2/index.php?option=com_content&task=view&id=3&Itemid=9"
class="latestnews">
Newsflash 2 </a> </li>
<li class="latestnews">
<a href="http://localhost/projects/1112rc2/index.php?option=com_content&task=view&id=6&Itemid=2"
class="latestnews">
Example News Item 1
</a>
</li>
<li class="latestnews">
<a href="http://localhost/projects/1112rc2/index.php?option=com_content&task=view&id=9&Itemid=2"
class="latestnews">
Example News Item 4
</a>
</li>
</ul>
</div>
</div>
</div>
</div>
</source>

If there is no switch at all:
<source lang="php">
<?php mosLoadModules ( 'user1'); ?>
</source>

The outputted code looks like this:
<source lang="html4strict">
<table class="moduletable" border="0" cellpadding="0" cellspacing="0">
<tbody>
<tr>
<th valign="top">
Latest News
</th>
</tr>
<tr>
<td>
<ul class="latestnews">
<li class="latestnews">
<a href="http://localhost/projects/1112rc2/index.php?option=com_content&task=view&id=4&Itemid=9"
class="latestnews">Newsflash 3
</a>
</li>
<li class="latestnews">
<a href="http://localhost/projects/1112rc2/index.php?option=com_content&task=view&id=2&Itemid=9"
class="latestnews">
Newsflash 1
</a>
</li>
<li class="latestnews">
<a href="http://localhost/projects/1112rc2/index.php?option=com_content&task=view&id=3&Itemid=9"
class="latestnews">Newsflash 2
</a>
</li>
<li class="latestnews">
<a href="http://localhost/projects/1112rc2/index.php?option=com_content&task=view&id=6&Itemid=2"
class="latestnews">
Example News Item 1
</a>
</li>
<li class="latestnews">
<a href="http://localhost/projects/1112rc2/index.php?option=com_content&task=view&id=9&Itemid=2"
class="latestnews">
Example News Item 4
</a>
</li>
</ul>
</td>
</tr>
</tbody>
</table>
</div>
</source>

In Joomla! 1.5 each switch has a style associated with it.

switch -3: $style = 'rounded';
switch -2: $style = 'xhtml
switch -1: $stylle = 'raw';
switch 0 :$style = 'table';

===How do I add a position to a template?===
To create a "new" position chose one of the names from the list of positions shown in
Site>[[Template Manager]]>Module Positions

'''1.0'''

In your template add
<source lang="php">
<?php mosLoadModules ('position_name'); ?>
</source>

You will want to surround it with approprate html so that it appears where you want it to and with the formatting you want.

'''1.5'''

===How do I change the image(s) in my template?===
One common [[Template|template]] change is to use your own graphic/image. Simple graphics (not [[Banner|banners]]) are linked in the [[HTML]] file. Simply change the reference to the image of your choice in the HTML file of your template. Do this by, in the [[Back-end|adminsitrative interface]], going to Site>>[[Template Manager]] and then selecting your template. Click the icon for html.

Keep in mind that if it is a different size than the original image this may change the appearance of the site in unexpected ways.

The images for a given template are generally located in this folder:
/templates/''templatename''/images
(where you substitute the name of the template you are using.)

===How do I collapse an empty position in a template?===
Very often the question is asked on how to collapse a position in any template. Note collapse here means "not show" if no modules are published to these columns.

'''1.0'''

Here is a method on how to do this as an example with the tremendous popular [[rhuk_solarflare]] template:

open <tt>../templates/rhuk_solarflare_ii/index.php</tt> and find and replace this:
<source lang="php">
<div id="left_outer">
<div id="left_inner">
<?php mosLoadModules ( 'left', -2 ); ?>
</div>
</div>
<div id="content_outer">
</source>
with this :
<source lang="php">
<?php
if ( !(mosCountModules( 'left' )) ) {
?>
<div id="content_outer2">
<?
}
else {
?>
<div id="left_outer">
<div id="left_inner">
<?php mosLoadModules ( 'left', -2 ); ?>
</div>
</div>
<div id="content_outer">
<?
}
?>
</source>
and save the file.

Then open <tt>../templates/rhuk_solarflare_ii/css/template_css.css</tt> file and add:
<source lang="css">
#content_outer2 {
padding: 0px;
margin-top: 0px;
margin-left: 0px;
/** border: 1px solid #cccccc; **/
float: left;
width: 800px;
}
</source>

Save and your left column now will collapse when you don't publish anything to it!

This method you can multiply to any template if you try to follow the logic of the code!

'''1.5'''

===CSS Text/Font Resizing (A+ A-) on Joomla Template===

'''1.0'''

I recognize that there are some of you who are sort of scratching your heads wondering how to get from where your site is now to where joomla.org's is. So for those of you wanting it laid out all the way, here's a more detailed instruction set that summarizes and extends what has already been said through the course of this thread:

Step 1 - download joomla.org's font style switcher file ( http://forum.joomla.org/Themes/joomla/md_stylechanger.js )
Step 2 - put that file somewhere in the folder of the template you are using
Step 3 - put A+, A-, and Reset images in your template's image folder
Step 4 - paste the following code snippet somewhere in your template's index.php file


<source lang="php">
<?php
// shortcut of template URL used in src attributes
$template_url = $mosConfig_live_site .'/templates/'. $mainframe->getTemplate();
?>
<script type="text/javascript" language="javascript"
src="<?php echo $template_url; ?>/____1____"></script>
<a href="index.php" title="Increase size" onclick="changeFontSize(1);return false;">
<img src="<?php echo $template_url; ?>/images/____2____" alt="" border="0" />
</a>
<a href="index.php" title="Decrease size" onclick="changeFontSize(-1);return false;">
<img src="<?php echo $template_url; ?>/images/____3____" alt="" border="0" />
</a>
<a href="index.php" title="Revert styles to default" onclick="revertStyles(); return false;">
<img src="<?php echo $template_url; ?>/images/____4____" alt="" border="0" />
</a>
</source>

Step 5: Do all of the following:

* Replace ____1____ with the location in your template folder where you saved the .js file
* Replace ____2____ with the name of your A+ image
* Replace ____3____ with the name of your A- image
* Replace ____4____ with the name of your Reset image

Step 6: Do one of the following:

* Bask in the awesomeness that is session font resizing
* Start figuring out why the buttons do nothing (either because your site doesn't use style classes, or because I messed up somewhere)

===Can I remove the "Powered by Joomla!" message?===

Yes. You may remove that message, which is in <tt>footer.php</tt>. You may however '''not''' remove copyright and license information from the source code.

===How do I make it so my modules are laid out horizontally?===

See [[Administration_FAQs#How_do_I_control_whether_modules_are_vertically_or_horizontally_arranged.3F | How do I control whether modules are vertically or horizontally arranged?]]

Unit Testing

2008-06-24T22:01:27Z

Instance: /* Writing Unit Tests */

{{cookiejar}}
== News and Updates ==
2008 06 24: Update to reflect move of PHPUnit code from branch to trunk (former trunk now in /branches/old_simpletest).

2008 06 22: Add information on limiting tests by version.

2008 06 21: Added --class-exclude, --sequence-exclude, and --test-exclude options.

2008 06 21: PHPUnit has been updated to version 3.2.21 with SVN rev 10436. Please update.

== Unit Testing ==
Unit testing is an essential part of a good Quality Control program.
For a good general discussion of unit testing, visit the [http://en.wikipedia.org/wiki/Unit_test Wikipedia article].

=== Unit Testing in Open Source ===
Open source projects, with multiple developers working in parallel around the world, can greatly benefit from unit testing. The main benefits are:
* Unit tests help highlight cases where seemingly minor changes cause unexpected breakage.
* Unit tests help clearly specify how a class should behave.
* Unit tests can expose design flaws very early in development.
* Unit tests make great examples. They are a great place for developers to learn how to use the code.

=== The Testing Hierarchy: Unit, Subsystem, Integrated ===
Software testing systems usually run through a spectrum from "pure" unit tests through to fully integrated systems tests. We've described low level unit tests above. Integrated testing typically involves some sort of script that simulates user actions and then verifies that the result matches what's expected. This sort of "end to end" test verifies that all parts of the system are working correctly.

It's unfortunate that there is no clear nomenclature to describe all the intermediate stages of testing. The next stage beyond testing a single unit of code is subsystem testing. A subsystem test verifies that two or more units of code are interacting correctly to produce the desired result. In the simplest case, a subsystem test can be created simply by replacing mock objects with real objects and running unit tests on the top level module. In practise, this tends to not work as well as expected, because the original unit test data wasn't designed for a subsystem test, or because the nature of the test cases needs to be changed in order to fully test the subsystem. After all there is little point in simply repeating the unit test cases; the objective of a subsystem test should be to test boundary conditions and special cases that would be difficult to duplicate in unit tests.

Once a subsystem has been tested, it can be integrated into a larger system, which is still a subset of the whole product. Tests can be written for larger and larger subsystems, but at each stage the complexity of the tests increases. At some point, the effort required to hand craft tests exceeds the benefits of running them. This is where integrated testing comes in.

Integrated testing involves recording a user's interaction with the system into a script that can be replayed. The testing framework then compares the system's response with the expected response and passes or fails the test. The PHPUnit testing framework that we use has the ability to work with Selenium, a browser based test automation tool.

==== Test Objects ====
The purpose of unit tests is to isolate a module of code. A test that tests only one thing provides better information than a test that involves several object interactions. But how do we isolate an object from its dependencies? By writing stub classes. [http://xunitpatterns.com/Mocks,%20Fakes,%20Stubs%20and%20Dummies.html xUnit Patterns] defines a the hierarchy of dummy classes, ranging from simple to complex:
* Dummy - Defines attributes and methods of a dummy class (not particularly useful in PHP).
* Fake - Provides canned responses to method calls and fixed attribute values. Good for speed.
* Stub - Allows the test to define responses to method calls (return values, exceptions) to simulate the dependent object.
* Spy - A Fake or Stub that records method calls and parameters for later analysis.
* Mock - A Fake or Stub with a set of expectations -- method calls and parameters -- that are automatically verified for correctness.

=== Unit Testing in Joomla! ===
Unit testing capabilities in Joomla are still at an early stage. The intention is to define more standards for developing tests, and then to expand the scope of available tests.

For an overview of unit testing status in Joomla visit the [[Unit_Testing_Status]] page.

The SVN repository contains code under the /testing path. /testing/trunk contains code based on the SimpleTest framework. In early December 2007, the development team elected to move to the [http://www.phpunit.de PHPUnit] framework.

The PHPUnit tests are available from '''/testing/trunk'''. Some new tests have been added, any remaining tests from the SimpleTest days are completely broken. See /testing/branches/old-simpletest if you need to run something from that suite.

At this point, PHPUnit based tests only run in a command line environment.

==== The Unit Test Team ====
If you can commit to the Joomla code base, then you should consider yourself part of the unit test team!

Writing tests concurrently with code (or even before) is a good way to not only save development time, but a great tool for defending against regressions. Writing tests early in the development cycle also helps identify and resolve design issues sooner, which reduces refactoring.

If you want to get started on unit testing, get in touch with Alan Langford (instance) or Ray Tsai (mihu). Either of us will be happy to help out.
==== Current Work ====
* There is no longer any need to patch the main code to enable unit tests.
* Basic techniques for mock objects are defined.
* Strategies for dealing with local configuration is not yet complete, but there is a plan.
* Files of the form class-sequence-type-test.php, for example JObject-0000-class-test.php use PHPUnit.
* The JDate tests present a good example of a data-driven test, but they won't run on the current 1.5 code base (there are some proposed API changes as a result of unit test development).
* Previously functional tests, such as JFTP, haven't been moved to the PHPUnit environment yet.

==== Writing Unit Tests ====
At risk of stating the obvious, in the "purest" case the purpose of a unit test is to ''isolate a unit of code from its environment and to test the operation of that code''.

This isolation is usually achieved by writing dummy classes that emulate the code unit's environment. These dummy objects can be passive, by simply simulating the environment, or they can be more active, keeping track of how they are being used by the test unit and reporting any variations from the expected behaviour. See [[Unit_Testing_Mock_Objects|Mock Objects in Joomla]] for a detailed example.

An interesting aspect of writing tests is that they become ''de facto'' detailed technical specifications of the interfaces between units of code. The fact that these specifications can be verified in an automated way makes them a superb resource when refactoring code.

The test code has a few templates designed to kick-start a test. They are:

/unittest/sample-datatest-php.txt
/unittest/sample-simpletest.php.txt

Here are some example tests: [[Unit_Testing_--_a_Simple_Example|Simple Example]], [[Unit_Testing_--_Data_Driven_Example|Data Driven Example]], [[Unit_Testing_--_Plugin_Example|Plugin Example]], [[Unit_Testing_--_UI_Example|UI Example]].

==== Running Unit Tests ====
Test files follow the form class-sequence-type-test.php, for example JObject-0000-class-test.php. For tests that are not class based, the first element refers to the object being tested. An example of this is the e-mail cloaking plugin test, which is called emailcloak-0000-mode1-test.php.

Joomla unit tests use a customized test "runner". Every test directory should have a "runtests.php" file. Runtests has a few options, mostly to allow the selection of specific tests. The command line options are:

'''--class-exclude ''regex'''''

e.g. --class-exclude /JDate.*/ Skips tests that have a class part that match the regular expression.

'''--class-filter ''regex'''''

e.g. --class-filter /JDate/ Selects only tests that have a class part that match the regular expression.

'''--debug'''

Turns on additional debugging output.

'''--help'''

Prints information on options and exits.

'''--sequence-exclude ''regex'''''

Skips tests that have a sequence part that match the regular expression.

'''--sequence-filter ''regex'''''

Selects only tests that have a sequence part that matches the regular expression.

'''--test-exclude ''regex'''''

Skips tests that have a test part that match the regular expression.

'''--test-filter ''regex'''''

Selects only tests that have a test part that match the regular expression.

'''TODO:''' Expand command line parsing to add other features of the PHPUnit framework, such as output formats, code metrics reports, etc.

== How to Get it Running ==

Before you start make sure you have installed PHPUnit and of course PHP (5!) properly...

To get the unit tests to run on your Joomla! installation, perform the following steps:
* Create an instance of your Joomla! installation
* In the root checkout (or export) the latest version of the unit test code from SVN ''"/testing/trunk"'' to your installation base. This will create a ''"/unittest"'' sub-folder under your joomla installation.
* Create a ''"TestConfiguration.php"'' file. You can copy a the file from ''"TestConfiguration-dist.php"'' that is part of the package you just have checked out.
* If you want to run a subset of the commands, change to the directory that contains those tests.
* Run the unit test from the command using the following command:

php runtests.php

The unit test will the run, and the results are rendered.

== Troubleshooting ==

The provided configurations should work out of the box. We have seen problems with it (currently the cause is unknown). If you get an error like blow, the solution is pretty easy.

file=/var/www/unittest/runtests.php
posn=17
base=runtests.php
/var/www
JPATH_BASE does not point to a valid Joomla! installation:
JPATH_BASE = /var/www
Please modify your copy of "TestConfiguration.php"

Modify the ''"TestConfiguration.php"'' file and change the definition of the JPATH_BASE so it points to the path of you Joomla! installation, in the example below the Joomla! installation is installed at "''/var/www/update''".

define('JPATH_BASE', '/var/www/update');

== Frequently Asked Questions ==
'''Why can't I use "phpunit ''testname.php''" to run my tests?'''

The test facility has to do some work to be able to load the "Joomla!" framework and to be able to inject mock classes. It's difficult to do this from the PHPUnit test runner, so we built our own. Also, the Joomla test runner has specific options designed to make it easy to select specific tests. Over time we will add more functionality to the test runner so it has many of the capabilities of the phpunit command.

==See also==
[http://www.phpunit.de/pocket_guide/3.2/en/index.html PHPUnit Pocket Guide]

[[Category:Development]]

Unit Testing

2008-06-24T22:01:05Z

Instance: /* Writing Unit Tests */ add ink to UI exampe

{{cookiejar}}
== News and Updates ==
2008 06 24: Update to reflect move of PHPUnit code from branch to trunk (former trunk now in /branches/old_simpletest).

2008 06 22: Add information on limiting tests by version.

2008 06 21: Added --class-exclude, --sequence-exclude, and --test-exclude options.

2008 06 21: PHPUnit has been updated to version 3.2.21 with SVN rev 10436. Please update.

== Unit Testing ==
Unit testing is an essential part of a good Quality Control program.
For a good general discussion of unit testing, visit the [http://en.wikipedia.org/wiki/Unit_test Wikipedia article].

=== Unit Testing in Open Source ===
Open source projects, with multiple developers working in parallel around the world, can greatly benefit from unit testing. The main benefits are:
* Unit tests help highlight cases where seemingly minor changes cause unexpected breakage.
* Unit tests help clearly specify how a class should behave.
* Unit tests can expose design flaws very early in development.
* Unit tests make great examples. They are a great place for developers to learn how to use the code.

=== The Testing Hierarchy: Unit, Subsystem, Integrated ===
Software testing systems usually run through a spectrum from "pure" unit tests through to fully integrated systems tests. We've described low level unit tests above. Integrated testing typically involves some sort of script that simulates user actions and then verifies that the result matches what's expected. This sort of "end to end" test verifies that all parts of the system are working correctly.

It's unfortunate that there is no clear nomenclature to describe all the intermediate stages of testing. The next stage beyond testing a single unit of code is subsystem testing. A subsystem test verifies that two or more units of code are interacting correctly to produce the desired result. In the simplest case, a subsystem test can be created simply by replacing mock objects with real objects and running unit tests on the top level module. In practise, this tends to not work as well as expected, because the original unit test data wasn't designed for a subsystem test, or because the nature of the test cases needs to be changed in order to fully test the subsystem. After all there is little point in simply repeating the unit test cases; the objective of a subsystem test should be to test boundary conditions and special cases that would be difficult to duplicate in unit tests.

Once a subsystem has been tested, it can be integrated into a larger system, which is still a subset of the whole product. Tests can be written for larger and larger subsystems, but at each stage the complexity of the tests increases. At some point, the effort required to hand craft tests exceeds the benefits of running them. This is where integrated testing comes in.

Integrated testing involves recording a user's interaction with the system into a script that can be replayed. The testing framework then compares the system's response with the expected response and passes or fails the test. The PHPUnit testing framework that we use has the ability to work with Selenium, a browser based test automation tool.

==== Test Objects ====
The purpose of unit tests is to isolate a module of code. A test that tests only one thing provides better information than a test that involves several object interactions. But how do we isolate an object from its dependencies? By writing stub classes. [http://xunitpatterns.com/Mocks,%20Fakes,%20Stubs%20and%20Dummies.html xUnit Patterns] defines a the hierarchy of dummy classes, ranging from simple to complex:
* Dummy - Defines attributes and methods of a dummy class (not particularly useful in PHP).
* Fake - Provides canned responses to method calls and fixed attribute values. Good for speed.
* Stub - Allows the test to define responses to method calls (return values, exceptions) to simulate the dependent object.
* Spy - A Fake or Stub that records method calls and parameters for later analysis.
* Mock - A Fake or Stub with a set of expectations -- method calls and parameters -- that are automatically verified for correctness.

=== Unit Testing in Joomla! ===
Unit testing capabilities in Joomla are still at an early stage. The intention is to define more standards for developing tests, and then to expand the scope of available tests.

For an overview of unit testing status in Joomla visit the [[Unit_Testing_Status]] page.

The SVN repository contains code under the /testing path. /testing/trunk contains code based on the SimpleTest framework. In early December 2007, the development team elected to move to the [http://www.phpunit.de PHPUnit] framework.

The PHPUnit tests are available from '''/testing/trunk'''. Some new tests have been added, any remaining tests from the SimpleTest days are completely broken. See /testing/branches/old-simpletest if you need to run something from that suite.

At this point, PHPUnit based tests only run in a command line environment.

==== The Unit Test Team ====
If you can commit to the Joomla code base, then you should consider yourself part of the unit test team!

Writing tests concurrently with code (or even before) is a good way to not only save development time, but a great tool for defending against regressions. Writing tests early in the development cycle also helps identify and resolve design issues sooner, which reduces refactoring.

If you want to get started on unit testing, get in touch with Alan Langford (instance) or Ray Tsai (mihu). Either of us will be happy to help out.
==== Current Work ====
* There is no longer any need to patch the main code to enable unit tests.
* Basic techniques for mock objects are defined.
* Strategies for dealing with local configuration is not yet complete, but there is a plan.
* Files of the form class-sequence-type-test.php, for example JObject-0000-class-test.php use PHPUnit.
* The JDate tests present a good example of a data-driven test, but they won't run on the current 1.5 code base (there are some proposed API changes as a result of unit test development).
* Previously functional tests, such as JFTP, haven't been moved to the PHPUnit environment yet.

==== Writing Unit Tests ====
At risk of stating the obvious, in the "purest" case the purpose of a unit test is to ''isolate a unit of code from its environment and to test the operation of that code''.

This isolation is usually achieved by writing dummy classes that emulate the code unit's environment. These dummy objects can be passive, by simply simulating the environment, or they can be more active, keeping track of how they are being used by the test unit and reporting any variations from the expected behaviour. See [[Unit_Testing_Mock_Objects|Mock Objects in Joomla]] for a detailed example.

An interesting aspect of writing tests is that they become ''de facto'' detailed technical specifications of the interfaces between units of code. The fact that these specifications can be verified in an automated way makes them a superb resource when refactoring code.

The test code has a few templates designed to kick-start a test. They are:

/unittest/sample-datatest-php.txt
/unittest/sample-simpletest.php.txt

Here are some example tests: [[Unit_Testing_--_a_Simple_Example|Simple Example]], [[Unit_Testing_--_Data_Driven_Example|Data Driven Example]], [[Unit_Testing_--_Plugin_Example|Plugin Example]]., [[Unit_Testing_--_UI_Example|UI Example]]

==== Running Unit Tests ====
Test files follow the form class-sequence-type-test.php, for example JObject-0000-class-test.php. For tests that are not class based, the first element refers to the object being tested. An example of this is the e-mail cloaking plugin test, which is called emailcloak-0000-mode1-test.php.

Joomla unit tests use a customized test "runner". Every test directory should have a "runtests.php" file. Runtests has a few options, mostly to allow the selection of specific tests. The command line options are:

'''--class-exclude ''regex'''''

e.g. --class-exclude /JDate.*/ Skips tests that have a class part that match the regular expression.

'''--class-filter ''regex'''''

e.g. --class-filter /JDate/ Selects only tests that have a class part that match the regular expression.

'''--debug'''

Turns on additional debugging output.

'''--help'''

Prints information on options and exits.

'''--sequence-exclude ''regex'''''

Skips tests that have a sequence part that match the regular expression.

'''--sequence-filter ''regex'''''

Selects only tests that have a sequence part that matches the regular expression.

'''--test-exclude ''regex'''''

Skips tests that have a test part that match the regular expression.

'''--test-filter ''regex'''''

Selects only tests that have a test part that match the regular expression.

'''TODO:''' Expand command line parsing to add other features of the PHPUnit framework, such as output formats, code metrics reports, etc.

== How to Get it Running ==

Before you start make sure you have installed PHPUnit and of course PHP (5!) properly...

To get the unit tests to run on your Joomla! installation, perform the following steps:
* Create an instance of your Joomla! installation
* In the root checkout (or export) the latest version of the unit test code from SVN ''"/testing/trunk"'' to your installation base. This will create a ''"/unittest"'' sub-folder under your joomla installation.
* Create a ''"TestConfiguration.php"'' file. You can copy a the file from ''"TestConfiguration-dist.php"'' that is part of the package you just have checked out.
* If you want to run a subset of the commands, change to the directory that contains those tests.
* Run the unit test from the command using the following command:

php runtests.php

The unit test will the run, and the results are rendered.

== Troubleshooting ==

The provided configurations should work out of the box. We have seen problems with it (currently the cause is unknown). If you get an error like blow, the solution is pretty easy.

file=/var/www/unittest/runtests.php
posn=17
base=runtests.php
/var/www
JPATH_BASE does not point to a valid Joomla! installation:
JPATH_BASE = /var/www
Please modify your copy of "TestConfiguration.php"

Modify the ''"TestConfiguration.php"'' file and change the definition of the JPATH_BASE so it points to the path of you Joomla! installation, in the example below the Joomla! installation is installed at "''/var/www/update''".

define('JPATH_BASE', '/var/www/update');

== Frequently Asked Questions ==
'''Why can't I use "phpunit ''testname.php''" to run my tests?'''

The test facility has to do some work to be able to load the "Joomla!" framework and to be able to inject mock classes. It's difficult to do this from the PHPUnit test runner, so we built our own. Also, the Joomla test runner has specific options designed to make it easy to select specific tests. Over time we will add more functionality to the test runner so it has many of the capabilities of the phpunit command.

==See also==
[http://www.phpunit.de/pocket_guide/3.2/en/index.html PHPUnit Pocket Guide]

[[Category:Development]]

Unit Testing

2008-06-24T16:00:43Z

Instance: Record move of PHPUnit branch into the trunk.

{{cookiejar}}
== News and Updates ==
2008 06 24: Update to reflect move of PHPUnit code from branch to trunk (former trunk now in /branches/old_simpletest).

2008 06 22: Add information on limiting tests by version.

2008 06 21: Added --class-exclude, --sequence-exclude, and --test-exclude options.

2008 06 21: PHPUnit has been updated to version 3.2.21 with SVN rev 10436. Please update.

== Unit Testing ==
Unit testing is an essential part of a good Quality Control program.
For a good general discussion of unit testing, visit the [http://en.wikipedia.org/wiki/Unit_test Wikipedia article].

=== Unit Testing in Open Source ===
Open source projects, with multiple developers working in parallel around the world, can greatly benefit from unit testing. The main benefits are:
* Unit tests help highlight cases where seemingly minor changes cause unexpected breakage.
* Unit tests help clearly specify how a class should behave.
* Unit tests can expose design flaws very early in development.
* Unit tests make great examples. They are a great place for developers to learn how to use the code.

=== The Testing Hierarchy: Unit, Subsystem, Integrated ===
Software testing systems usually run through a spectrum from "pure" unit tests through to fully integrated systems tests. We've described low level unit tests above. Integrated testing typically involves some sort of script that simulates user actions and then verifies that the result matches what's expected. This sort of "end to end" test verifies that all parts of the system are working correctly.

It's unfortunate that there is no clear nomenclature to describe all the intermediate stages of testing. The next stage beyond testing a single unit of code is subsystem testing. A subsystem test verifies that two or more units of code are interacting correctly to produce the desired result. In the simplest case, a subsystem test can be created simply by replacing mock objects with real objects and running unit tests on the top level module. In practise, this tends to not work as well as expected, because the original unit test data wasn't designed for a subsystem test, or because the nature of the test cases needs to be changed in order to fully test the subsystem. After all there is little point in simply repeating the unit test cases; the objective of a subsystem test should be to test boundary conditions and special cases that would be difficult to duplicate in unit tests.

Once a subsystem has been tested, it can be integrated into a larger system, which is still a subset of the whole product. Tests can be written for larger and larger subsystems, but at each stage the complexity of the tests increases. At some point, the effort required to hand craft tests exceeds the benefits of running them. This is where integrated testing comes in.

Integrated testing involves recording a user's interaction with the system into a script that can be replayed. The testing framework then compares the system's response with the expected response and passes or fails the test. The PHPUnit testing framework that we use has the ability to work with Selenium, a browser based test automation tool.

==== Test Objects ====
The purpose of unit tests is to isolate a module of code. A test that tests only one thing provides better information than a test that involves several object interactions. But how do we isolate an object from its dependencies? By writing stub classes. [http://xunitpatterns.com/Mocks,%20Fakes,%20Stubs%20and%20Dummies.html xUnit Patterns] defines a the hierarchy of dummy classes, ranging from simple to complex:
* Dummy - Defines attributes and methods of a dummy class (not particularly useful in PHP).
* Fake - Provides canned responses to method calls and fixed attribute values. Good for speed.
* Stub - Allows the test to define responses to method calls (return values, exceptions) to simulate the dependent object.
* Spy - A Fake or Stub that records method calls and parameters for later analysis.
* Mock - A Fake or Stub with a set of expectations -- method calls and parameters -- that are automatically verified for correctness.

=== Unit Testing in Joomla! ===
Unit testing capabilities in Joomla are still at an early stage. The intention is to define more standards for developing tests, and then to expand the scope of available tests.

For an overview of unit testing status in Joomla visit the [[Unit_Testing_Status]] page.

The SVN repository contains code under the /testing path. /testing/trunk contains code based on the SimpleTest framework. In early December 2007, the development team elected to move to the [http://www.phpunit.de PHPUnit] framework.

The PHPUnit tests are available from '''/testing/trunk'''. Some new tests have been added, any remaining tests from the SimpleTest days are completely broken. See /testing/branches/old-simpletest if you need to run something from that suite.

At this point, PHPUnit based tests only run in a command line environment.

==== The Unit Test Team ====
If you can commit to the Joomla code base, then you should consider yourself part of the unit test team!

Writing tests concurrently with code (or even before) is a good way to not only save development time, but a great tool for defending against regressions. Writing tests early in the development cycle also helps identify and resolve design issues sooner, which reduces refactoring.

If you want to get started on unit testing, get in touch with Alan Langford (instance) or Ray Tsai (mihu). Either of us will be happy to help out.
==== Current Work ====
* There is no longer any need to patch the main code to enable unit tests.
* Basic techniques for mock objects are defined.
* Strategies for dealing with local configuration is not yet complete, but there is a plan.
* Files of the form class-sequence-type-test.php, for example JObject-0000-class-test.php use PHPUnit.
* The JDate tests present a good example of a data-driven test, but they won't run on the current 1.5 code base (there are some proposed API changes as a result of unit test development).
* Previously functional tests, such as JFTP, haven't been moved to the PHPUnit environment yet.

==== Writing Unit Tests ====
At risk of stating the obvious, in the "purest" case the purpose of a unit test is to ''isolate a unit of code from its environment and to test the operation of that code''.

This isolation is usually achieved by writing dummy classes that emulate the code unit's environment. These dummy objects can be passive, by simply simulating the environment, or they can be more active, keeping track of how they are being used by the test unit and reporting any variations from the expected behaviour. See [[Unit_Testing_Mock_Objects|Mock Objects in Joomla]] for a detailed example.

An interesting aspect of writing tests is that they become ''de facto'' detailed technical specifications of the interfaces between units of code. The fact that these specifications can be verified in an automated way makes them a superb resource when refactoring code.

The test code has a few templates designed to kick-start a test. They are:

/unittest/sample-datatest-php.txt
/unittest/sample-simpletest.php.txt

Here are some example tests: [[Unit_Testing_--_a_Simple_Example|Simple Example]], [[Unit_Testing_--_Data_Driven_Example|Data Driven Example]], [[Unit_Testing_--_Plugin_Example|Plugin Example]].

==== Running Unit Tests ====
Test files follow the form class-sequence-type-test.php, for example JObject-0000-class-test.php. For tests that are not class based, the first element refers to the object being tested. An example of this is the e-mail cloaking plugin test, which is called emailcloak-0000-mode1-test.php.

Joomla unit tests use a customized test "runner". Every test directory should have a "runtests.php" file. Runtests has a few options, mostly to allow the selection of specific tests. The command line options are:

'''--class-exclude ''regex'''''

e.g. --class-exclude /JDate.*/ Skips tests that have a class part that match the regular expression.

'''--class-filter ''regex'''''

e.g. --class-filter /JDate/ Selects only tests that have a class part that match the regular expression.

'''--debug'''

Turns on additional debugging output.

'''--help'''

Prints information on options and exits.

'''--sequence-exclude ''regex'''''

Skips tests that have a sequence part that match the regular expression.

'''--sequence-filter ''regex'''''

Selects only tests that have a sequence part that matches the regular expression.

'''--test-exclude ''regex'''''

Skips tests that have a test part that match the regular expression.

'''--test-filter ''regex'''''

Selects only tests that have a test part that match the regular expression.

'''TODO:''' Expand command line parsing to add other features of the PHPUnit framework, such as output formats, code metrics reports, etc.

== How to Get it Running ==

Before you start make sure you have installed PHPUnit and of course PHP (5!) properly...

To get the unit tests to run on your Joomla! installation, perform the following steps:
* Create an instance of your Joomla! installation
* In the root checkout (or export) the latest version of the unit test code from SVN ''"/testing/trunk"'' to your installation base. This will create a ''"/unittest"'' sub-folder under your joomla installation.
* Create a ''"TestConfiguration.php"'' file. You can copy a the file from ''"TestConfiguration-dist.php"'' that is part of the package you just have checked out.
* If you want to run a subset of the commands, change to the directory that contains those tests.
* Run the unit test from the command using the following command:

php runtests.php

The unit test will the run, and the results are rendered.

== Troubleshooting ==

The provided configurations should work out of the box. We have seen problems with it (currently the cause is unknown). If you get an error like blow, the solution is pretty easy.

file=/var/www/unittest/runtests.php
posn=17
base=runtests.php
/var/www
JPATH_BASE does not point to a valid Joomla! installation:
JPATH_BASE = /var/www
Please modify your copy of "TestConfiguration.php"

Modify the ''"TestConfiguration.php"'' file and change the definition of the JPATH_BASE so it points to the path of you Joomla! installation, in the example below the Joomla! installation is installed at "''/var/www/update''".

define('JPATH_BASE', '/var/www/update');

== Frequently Asked Questions ==
'''Why can't I use "phpunit ''testname.php''" to run my tests?'''

The test facility has to do some work to be able to load the "Joomla!" framework and to be able to inject mock classes. It's difficult to do this from the PHPUnit test runner, so we built our own. Also, the Joomla test runner has specific options designed to make it easy to select specific tests. Over time we will add more functionality to the test runner so it has many of the capabilities of the phpunit command.

==See also==
[http://www.phpunit.de/pocket_guide/3.2/en/index.html PHPUnit Pocket Guide]

[[Category:Development]]

Unit Testing

2008-06-22T19:34:50Z

Instance: /* News and Updates */

{{cookiejar}}
== News and Updates ==
2008 06 22: Add information on limiting tests by version.

2008 06 21: Added --class-exclude, --sequence-exclude, and --test-exclude options.

2008 06 21: PHPUnit has been updated to version 3.2.21 with SVN rev 10436. Please update.

== Unit Testing ==
Unit testing is an essential part of a good Quality Control program.
For a good general discussion of unit testing, visit the [http://en.wikipedia.org/wiki/Unit_test Wikipedia article].

=== Unit Testing in Open Source ===
Open source projects, with multiple developers working in parallel around the world, can greatly benefit from unit testing. The main benefits are:
* Unit tests help highlight cases where seemingly minor changes cause unexpected breakage.
* Unit tests help clearly specify how a class should behave.
* Unit tests can expose design flaws very early in development.
* Unit tests make great examples. They are a great place for developers to learn how to use the code.

=== The Testing Hierarchy: Unit, Subsystem, Integrated ===
Software testing systems usually run through a spectrum from "pure" unit tests through to fully integrated systems tests. We've described low level unit tests above. Integrated testing typically involves some sort of script that simulates user actions and then verifies that the result matches what's expected. This sort of "end to end" test verifies that all parts of the system are working correctly.

It's unfortunate that there is no clear nomenclature to describe all the intermediate stages of testing. The next stage beyond testing a single unit of code is subsystem testing. A subsystem test verifies that two or more units of code are interacting correctly to produce the desired result. In the simplest case, a subsystem test can be created simply by replacing mock objects with real objects and running unit tests on the top level module. In practise, this tends to not work as well as expected, because the original unit test data wasn't designed for a subsystem test, or because the nature of the test cases needs to be changed in order to fully test the subsystem. After all there is little point in simply repeating the unit test cases; the objective of a subsystem test should be to test boundary conditions and special cases that would be difficult to duplicate in unit tests.

Once a subsystem has been tested, it can be integrated into a larger system, which is still a subset of the whole product. Tests can be written for larger and larger subsystems, but at each stage the complexity of the tests increases. At some point, the effort required to hand craft tests exceeds the benefits of running them. This is where integrated testing comes in.

Integrated testing involves recording a user's interaction with the system into a script that can be replayed. The testing framework then compares the system's response with the expected response and passes or fails the test. The PHPUnit testing framework that we use has the ability to work with Selenium, a browser based test automation tool.

==== Test Objects ====
The purpose of unit tests is to isolate a module of code. A test that tests only one thing provides better information than a test that involves several object interactions. But how do we isolate an object from its dependencies? By writing stub classes. [http://xunitpatterns.com/Mocks,%20Fakes,%20Stubs%20and%20Dummies.html xUnit Patterns] defines a the hierarchy of dummy classes, ranging from simple to complex:
* Dummy - Defines attributes and methods of a dummy class (not particularly useful in PHP).
* Fake - Provides canned responses to method calls and fixed attribute values. Good for speed.
* Stub - Allows the test to define responses to method calls (return values, exceptions) to simulate the dependent object.
* Spy - A Fake or Stub that records method calls and parameters for later analysis.
* Mock - A Fake or Stub with a set of expectations -- method calls and parameters -- that are automatically verified for correctness.

=== Unit Testing in Joomla! ===
Unit testing capabilities in Joomla are still at an early stage. The intention is to define more standards for developing tests, and then to expand the scope of available tests.

For an overview of unit testing status in Joomla visit the [[Unit_Testing_Status]] page.

The SVN repository contains code under the /testing path. /testing/trunk contains code based on the SimpleTest framework. In early December 2007, the development team elected to move to the [http://www.phpunit.de PHPUnit] framework.

Work on using PHPUnit has been done in '''/testing/branches/2007-12-17'''. Some new tests have been added, many old tests from the SimpleTest days are completely broken.

At this point, PHPUnit based tests only run in a command line environment.

==== The Unit Test Team ====
If you can commit to the Joomla code base, then you should consider yourself part of the unit test team!

Writing tests concurrently with code (or even before) is a good way to not only save development time, but a great tool for defending against regressions. Writing tests early in the development cycle also helps identify and resolve design issues sooner, which reduces refactoring.

If you want to get started on unit testing, get in touch with Alan Langford (instance) or Ray Tsai (mihu). Either of us will be happy to help out.
==== Current Work ====
* There is no longer any need to patch the main code to enable unit tests.
* Basic techniques for mock objects are defined.
* Strategies for dealing with local configuration is not yet complete, but there is a plan.
* Files of the form class-sequence-type-test.php, for example JObject-0000-class-test.php use PHPUnit.
* The JDate tests present a good example of a data-driven test, but they won't run on the current 1.5 code base (there are some proposed API changes as a result of unit test development).
* Previously functional tests, such as JFTP, haven't been moved to the PHPUnit environment yet.

==== Writing Unit Tests ====
At risk of stating the obvious, in the "purest" case the purpose of a unit test is to ''isolate a unit of code from its environment and to test the operation of that code''.

This isolation is usually achieved by writing dummy classes that emulate the code unit's environment. These dummy objects can be passive, by simply simulating the environment, or they can be more active, keeping track of how they are being used by the test unit and reporting any variations from the expected behaviour. See [[Unit_Testing_Mock_Objects|Mock Objects in Joomla]] for a detailed example.

An interesting aspect of writing tests is that they become ''de facto'' detailed technical specifications of the interfaces between units of code. The fact that these specifications can be verified in an automated way makes them a superb resource when refactoring code.

The test code has a few templates designed to kick-start a test. They are:

/unittest/sample-datatest-php.txt
/unittest/sample-simpletest.php.txt

Here are some example tests: [[Unit_Testing_--_a_Simple_Example|Simple Example]], [[Unit_Testing_--_Data_Driven_Example|Data Driven Example]], [[Unit_Testing_--_Plugin_Example|Plugin Example]].

==== Running Unit Tests ====
Test files follow the form class-sequence-type-test.php, for example JObject-0000-class-test.php. For tests that are not class based, the first element refers to the object being tested. An example of this is the e-mail cloaking plugin test, which is called emailcloak-0000-mode1-test.php.

Joomla unit tests use a customized test "runner". Every test directory should have a "runtests.php" file. Runtests has a few options, mostly to allow the selection of specific tests. The command line options are:

'''--class-exclude ''regex'''''

e.g. --class-exclude /JDate.*/ Skips tests that have a class part that match the regular expression.

'''--class-filter ''regex'''''

e.g. --class-filter /JDate/ Selects only tests that have a class part that match the regular expression.

'''--debug'''

Turns on additional debugging output.

'''--help'''

Prints information on options and exits.

'''--sequence-exclude ''regex'''''

Skips tests that have a sequence part that match the regular expression.

'''--sequence-filter ''regex'''''

Selects only tests that have a sequence part that matches the regular expression.

'''--test-exclude ''regex'''''

Skips tests that have a test part that match the regular expression.

'''--test-filter ''regex'''''

Selects only tests that have a test part that match the regular expression.

'''TODO:''' Expand command line parsing to add other features of the PHPUnit framework, such as output formats, code metrics reports, etc.

== How to Get it Running ==

Before you start make sure you have installed PHPUnit and of course PHP (5!) properly...

To get the unit tests to run on your Joomla! installation, perform the following steps:
* Create an instance of your Joomla! installation
* In the root checkout (or export) the latest version of the unit test code from SVN ''"/testing/branches/2007-12-17"'' to your installation base. This will create a ''"/unittest"'' sub-folder under your joomla installation.
* Create a ''"TestConfiguration.php"'' file. You can copy a the file from ''"TestConfiguration-dist.php"'' that is part of the package you just have checked out.
* If you want to run a subset of the commands, change to the directory that contains those tests.
* Run the unit test from the command using the following command:

php runtests.php

The unit test will the run, and the results are rendered.

== Troubleshooting ==

The provided configurations should work out of the box. We have seen problems with it (currently the cause is unknown). If you get an error like blow, the solution is pretty easy.

file=/var/www/unittest/runtests.php
posn=17
base=runtests.php
/var/www
JPATH_BASE does not point to a valid Joomla! installation:
JPATH_BASE = /var/www
Please modify your copy of "TestConfiguration.php"

Modify the ''"TestConfiguration.php"'' file and change the definition of the JPATH_BASE so it points to the path of you Joomla! installation, in the example below the Joomla! installation is installed at "''/var/www/update''".

define('JPATH_BASE', '/var/www/update');

== Frequently Asked Questions ==
'''Why can't I use "phpunit ''testname.php''" to run my tests?'''

The test facility has to do some work to be able to load the "Joomla!" framework and to be able to inject mock classes. It's difficult to do this from the PHPUnit test runner, so we built our own. Also, the Joomla test runner has specific options designed to make it easy to select specific tests. Over time we will add more functionality to the test runner so it has many of the capabilities of the phpunit command.

==See also==
[http://www.phpunit.de/pocket_guide/3.2/en/index.html PHPUnit Pocket Guide]

[[Category:Development]]

Unit Testing

2008-06-22T16:10:55Z

Instance: Added a FAQ

{{cookiejar}}
== News and Updates ==
2008 06 21: Added --class-exclude, --sequence-exclude, and --test-exclude options.

2008 06 21: PHPUnit has been updated to version 3.2.21 with SVN rev 10436. Please update.

== Unit Testing ==
Unit testing is an essential part of a good Quality Control program.
For a good general discussion of unit testing, visit the [http://en.wikipedia.org/wiki/Unit_test Wikipedia article].

=== Unit Testing in Open Source ===
Open source projects, with multiple developers working in parallel around the world, can greatly benefit from unit testing. The main benefits are:
* Unit tests help highlight cases where seemingly minor changes cause unexpected breakage.
* Unit tests help clearly specify how a class should behave.
* Unit tests can expose design flaws very early in development.
* Unit tests make great examples. They are a great place for developers to learn how to use the code.

=== The Testing Hierarchy: Unit, Subsystem, Integrated ===
Software testing systems usually run through a spectrum from "pure" unit tests through to fully integrated systems tests. We've described low level unit tests above. Integrated testing typically involves some sort of script that simulates user actions and then verifies that the result matches what's expected. This sort of "end to end" test verifies that all parts of the system are working correctly.

It's unfortunate that there is no clear nomenclature to describe all the intermediate stages of testing. The next stage beyond testing a single unit of code is subsystem testing. A subsystem test verifies that two or more units of code are interacting correctly to produce the desired result. In the simplest case, a subsystem test can be created simply by replacing mock objects with real objects and running unit tests on the top level module. In practise, this tends to not work as well as expected, because the original unit test data wasn't designed for a subsystem test, or because the nature of the test cases needs to be changed in order to fully test the subsystem. After all there is little point in simply repeating the unit test cases; the objective of a subsystem test should be to test boundary conditions and special cases that would be difficult to duplicate in unit tests.

Once a subsystem has been tested, it can be integrated into a larger system, which is still a subset of the whole product. Tests can be written for larger and larger subsystems, but at each stage the complexity of the tests increases. At some point, the effort required to hand craft tests exceeds the benefits of running them. This is where integrated testing comes in.

Integrated testing involves recording a user's interaction with the system into a script that can be replayed. The testing framework then compares the system's response with the expected response and passes or fails the test. The PHPUnit testing framework that we use has the ability to work with Selenium, a browser based test automation tool.

==== Test Objects ====
The purpose of unit tests is to isolate a module of code. A test that tests only one thing provides better information than a test that involves several object interactions. But how do we isolate an object from its dependencies? By writing stub classes. [http://xunitpatterns.com/Mocks,%20Fakes,%20Stubs%20and%20Dummies.html xUnit Patterns] defines a the hierarchy of dummy classes, ranging from simple to complex:
* Dummy - Defines attributes and methods of a dummy class (not particularly useful in PHP).
* Fake - Provides canned responses to method calls and fixed attribute values. Good for speed.
* Stub - Allows the test to define responses to method calls (return values, exceptions) to simulate the dependent object.
* Spy - A Fake or Stub that records method calls and parameters for later analysis.
* Mock - A Fake or Stub with a set of expectations -- method calls and parameters -- that are automatically verified for correctness.

=== Unit Testing in Joomla! ===
Unit testing capabilities in Joomla are still at an early stage. The intention is to define more standards for developing tests, and then to expand the scope of available tests.

For an overview of unit testing status in Joomla visit the [[Unit_Testing_Status]] page.

The SVN repository contains code under the /testing path. /testing/trunk contains code based on the SimpleTest framework. In early December 2007, the development team elected to move to the [http://www.phpunit.de PHPUnit] framework.

Work on using PHPUnit has been done in '''/testing/branches/2007-12-17'''. Some new tests have been added, many old tests from the SimpleTest days are completely broken.

At this point, PHPUnit based tests only run in a command line environment.

==== The Unit Test Team ====
If you can commit to the Joomla code base, then you should consider yourself part of the unit test team!

Writing tests concurrently with code (or even before) is a good way to not only save development time, but a great tool for defending against regressions. Writing tests early in the development cycle also helps identify and resolve design issues sooner, which reduces refactoring.

If you want to get started on unit testing, get in touch with Alan Langford (instance) or Ray Tsai (mihu). Either of us will be happy to help out.
==== Current Work ====
* There is no longer any need to patch the main code to enable unit tests.
* Basic techniques for mock objects are defined.
* Strategies for dealing with local configuration is not yet complete, but there is a plan.
* Files of the form class-sequence-type-test.php, for example JObject-0000-class-test.php use PHPUnit.
* The JDate tests present a good example of a data-driven test, but they won't run on the current 1.5 code base (there are some proposed API changes as a result of unit test development).
* Previously functional tests, such as JFTP, haven't been moved to the PHPUnit environment yet.

==== Writing Unit Tests ====
At risk of stating the obvious, in the "purest" case the purpose of a unit test is to ''isolate a unit of code from its environment and to test the operation of that code''.

This isolation is usually achieved by writing dummy classes that emulate the code unit's environment. These dummy objects can be passive, by simply simulating the environment, or they can be more active, keeping track of how they are being used by the test unit and reporting any variations from the expected behaviour. See [[Unit_Testing_Mock_Objects|Mock Objects in Joomla]] for a detailed example.

An interesting aspect of writing tests is that they become ''de facto'' detailed technical specifications of the interfaces between units of code. The fact that these specifications can be verified in an automated way makes them a superb resource when refactoring code.

The test code has a few templates designed to kick-start a test. They are:

/unittest/sample-datatest-php.txt
/unittest/sample-simpletest.php.txt

Here are some example tests: [[Unit_Testing_--_a_Simple_Example|Simple Example]], [[Unit_Testing_--_Data_Driven_Example|Data Driven Example]], [[Unit_Testing_--_Plugin_Example|Plugin Example]].

==== Running Unit Tests ====
Test files follow the form class-sequence-type-test.php, for example JObject-0000-class-test.php. For tests that are not class based, the first element refers to the object being tested. An example of this is the e-mail cloaking plugin test, which is called emailcloak-0000-mode1-test.php.

Joomla unit tests use a customized test "runner". Every test directory should have a "runtests.php" file. Runtests has a few options, mostly to allow the selection of specific tests. The command line options are:

'''--class-exclude ''regex'''''

e.g. --class-exclude /JDate.*/ Skips tests that have a class part that match the regular expression.

'''--class-filter ''regex'''''

e.g. --class-filter /JDate/ Selects only tests that have a class part that match the regular expression.

'''--debug'''

Turns on additional debugging output.

'''--help'''

Prints information on options and exits.

'''--sequence-exclude ''regex'''''

Skips tests that have a sequence part that match the regular expression.

'''--sequence-filter ''regex'''''

Selects only tests that have a sequence part that matches the regular expression.

'''--test-exclude ''regex'''''

Skips tests that have a test part that match the regular expression.

'''--test-filter ''regex'''''

Selects only tests that have a test part that match the regular expression.

'''TODO:''' Expand command line parsing to add other features of the PHPUnit framework, such as output formats, code metrics reports, etc.

== How to Get it Running ==

Before you start make sure you have installed PHPUnit and of course PHP (5!) properly...

To get the unit tests to run on your Joomla! installation, perform the following steps:
* Create an instance of your Joomla! installation
* In the root checkout (or export) the latest version of the unit test code from SVN ''"/testing/branches/2007-12-17"'' to your installation base. This will create a ''"/unittest"'' sub-folder under your joomla installation.
* Create a ''"TestConfiguration.php"'' file. You can copy a the file from ''"TestConfiguration-dist.php"'' that is part of the package you just have checked out.
* If you want to run a subset of the commands, change to the directory that contains those tests.
* Run the unit test from the command using the following command:

php runtests.php

The unit test will the run, and the results are rendered.

== Troubleshooting ==

The provided configurations should work out of the box. We have seen problems with it (currently the cause is unknown). If you get an error like blow, the solution is pretty easy.

file=/var/www/unittest/runtests.php
posn=17
base=runtests.php
/var/www
JPATH_BASE does not point to a valid Joomla! installation:
JPATH_BASE = /var/www
Please modify your copy of "TestConfiguration.php"

Modify the ''"TestConfiguration.php"'' file and change the definition of the JPATH_BASE so it points to the path of you Joomla! installation, in the example below the Joomla! installation is installed at "''/var/www/update''".

define('JPATH_BASE', '/var/www/update');

== Frequently Asked Questions ==
'''Why can't I use "phpunit ''testname.php''" to run my tests?'''

The test facility has to do some work to be able to load the "Joomla!" framework and to be able to inject mock classes. It's difficult to do this from the PHPUnit test runner, so we built our own. Also, the Joomla test runner has specific options designed to make it easy to select specific tests. Over time we will add more functionality to the test runner so it has many of the capabilities of the phpunit command.

==See also==
[http://www.phpunit.de/pocket_guide/3.2/en/index.html PHPUnit Pocket Guide]

[[Category:Development]]

Unit Testing

2008-06-21T14:05:09Z

Instance: /* Running Unit Tests */ bold options to improve readability

{{cookiejar}}
== News and Updates ==
2008 06 21: Added --class-exclude, --sequence-exclude, and --test-exclude options.

2008 06 21: PHPUnit has been updated to version 3.2.21 with SVN rev 10436. Please update.

== Unit Testing ==
Unit testing is an essential part of a good Quality Control program.
For a good general discussion of unit testing, visit the [http://en.wikipedia.org/wiki/Unit_test Wikipedia article].

=== Unit Testing in Open Source ===
Open source projects, with multiple developers working in parallel around the world, can greatly benefit from unit testing. The main benefits are:
* Unit tests help highlight cases where seemingly minor changes cause unexpected breakage.
* Unit tests help clearly specify how a class should behave.
* Unit tests can expose design flaws very early in development.
* Unit tests make great examples. They are a great place for developers to learn how to use the code.

=== The Testing Hierarchy: Unit, Subsystem, Integrated ===
Software testing systems usually run through a spectrum from "pure" unit tests through to fully integrated systems tests. We've described low level unit tests above. Integrated testing typically involves some sort of script that simulates user actions and then verifies that the result matches what's expected. This sort of "end to end" test verifies that all parts of the system are working correctly.

It's unfortunate that there is no clear nomenclature to describe all the intermediate stages of testing. The next stage beyond testing a single unit of code is subsystem testing. A subsystem test verifies that two or more units of code are interacting correctly to produce the desired result. In the simplest case, a subsystem test can be created simply by replacing mock objects with real objects and running unit tests on the top level module. In practise, this tends to not work as well as expected, because the original unit test data wasn't designed for a subsystem test, or because the nature of the test cases needs to be changed in order to fully test the subsystem. After all there is little point in simply repeating the unit test cases; the objective of a subsystem test should be to test boundary conditions and special cases that would be difficult to duplicate in unit tests.

Once a subsystem has been tested, it can be integrated into a larger system, which is still a subset of the whole product. Tests can be written for larger and larger subsystems, but at each stage the complexity of the tests increases. At some point, the effort required to hand craft tests exceeds the benefits of running them. This is where integrated testing comes in.

Integrated testing involves recording a user's interaction with the system into a script that can be replayed. The testing framework then compares the system's response with the expected response and passes or fails the test. The PHPUnit testing framework that we use has the ability to work with Selenium, a browser based test automation tool.

==== Test Objects ====
The purpose of unit tests is to isolate a module of code. A test that tests only one thing provides better information than a test that involves several object interactions. But how do we isolate an object from its dependencies? By writing stub classes. [http://xunitpatterns.com/Mocks,%20Fakes,%20Stubs%20and%20Dummies.html xUnit Patterns] defines a the hierarchy of dummy classes, ranging from simple to complex:
* Dummy - Defines attributes and methods of a dummy class (not particularly useful in PHP).
* Fake - Provides canned responses to method calls and fixed attribute values. Good for speed.
* Stub - Allows the test to define responses to method calls (return values, exceptions) to simulate the dependent object.
* Spy - A Fake or Stub that records method calls and parameters for later analysis.
* Mock - A Fake or Stub with a set of expectations -- method calls and parameters -- that are automatically verified for correctness.

=== Unit Testing in Joomla! ===
Unit testing capabilities in Joomla are still at an early stage. The intention is to define more standards for developing tests, and then to expand the scope of available tests.

For an overview of unit testing status in Joomla visit the [[Unit_Testing_Status]] page.

The SVN repository contains code under the /testing path. /testing/trunk contains code based on the SimpleTest framework. In early December 2007, the development team elected to move to the [http://www.phpunit.de PHPUnit] framework.

Work on using PHPUnit has been done in '''/testing/branches/2007-12-17'''. Some new tests have been added, many old tests from the SimpleTest days are completely broken.

At this point, PHPUnit based tests only run in a command line environment.

==== The Unit Test Team ====
If you can commit to the Joomla code base, then you should consider yourself part of the unit test team!

Writing tests concurrently with code (or even before) is a good way to not only save development time, but a great tool for defending against regressions. Writing tests early in the development cycle also helps identify and resolve design issues sooner, which reduces refactoring.

If you want to get started on unit testing, get in touch with Alan Langford (instance) or Ray Tsai (mihu). Either of us will be happy to help out.
==== Current Work ====
* There is no longer any need to patch the main code to enable unit tests.
* Basic techniques for mock objects are defined.
* Strategies for dealing with local configuration is not yet complete, but there is a plan.
* Files of the form class-sequence-type-test.php, for example JObject-0000-class-test.php use PHPUnit.
* The JDate tests present a good example of a data-driven test, but they won't run on the current 1.5 code base (there are some proposed API changes as a result of unit test development).
* Previously functional tests, such as JFTP, haven't been moved to the PHPUnit environment yet.

==== Writing Unit Tests ====
At risk of stating the obvious, in the "purest" case the purpose of a unit test is to ''isolate a unit of code from its environment and to test the operation of that code''.

This isolation is usually achieved by writing dummy classes that emulate the code unit's environment. These dummy objects can be passive, by simply simulating the environment, or they can be more active, keeping track of how they are being used by the test unit and reporting any variations from the expected behaviour. See [[Unit_Testing_Mock_Objects|Mock Objects in Joomla]] for a detailed example.

An interesting aspect of writing tests is that they become ''de facto'' detailed technical specifications of the interfaces between units of code. The fact that these specifications can be verified in an automated way makes them a superb resource when refactoring code.

The test code has a few templates designed to kick-start a test. They are:

/unittest/sample-datatest-php.txt
/unittest/sample-simpletest.php.txt

Here are some example tests: [[Unit_Testing_--_a_Simple_Example|Simple Example]], [[Unit_Testing_--_Data_Driven_Example|Data Driven Example]], [[Unit_Testing_--_Plugin_Example|Plugin Example]].

==== Running Unit Tests ====
Test files follow the form class-sequence-type-test.php, for example JObject-0000-class-test.php. For tests that are not class based, the first element refers to the object being tested. An example of this is the e-mail cloaking plugin test, which is called emailcloak-0000-mode1-test.php.

Joomla unit tests use a customized test "runner". Every test directory should have a "runtests.php" file. Runtests has a few options, mostly to allow the selection of specific tests. The command line options are:

'''--class-exclude ''regex'''''

e.g. --class-exclude /JDate.*/ Skips tests that have a class part that match the regular expression.

'''--class-filter ''regex'''''

e.g. --class-filter /JDate/ Selects only tests that have a class part that match the regular expression.

'''--debug'''

Turns on additional debugging output.

'''--help'''

Prints information on options and exits.

'''--sequence-exclude ''regex'''''

Skips tests that have a sequence part that match the regular expression.

'''--sequence-filter ''regex'''''

Selects only tests that have a sequence part that matches the regular expression.

'''--test-exclude ''regex'''''

Skips tests that have a test part that match the regular expression.

'''--test-filter ''regex'''''

Selects only tests that have a test part that match the regular expression.

'''TODO:''' Expand command line parsing to add other features of the PHPUnit framework, such as output formats, code metrics reports, etc.

== How to Get it Running ==

Before you start make sure you have installed PHPUnit and of course PHP (5!) properly...

To get the unit tests to run on your Joomla! installation, perform the following steps:
* Create an instance of your Joomla! installation
* In the root checkout (or export) the latest version of the unit test code from SVN ''"/testing/branches/2007-12-17"'' to your installation base. This will create a ''"/unittest"'' sub-folder under your joomla installation.
* Create a ''"TestConfiguration.php"'' file. You can copy a the file from ''"TestConfiguration-dist.php"'' that is part of the package you just have checked out.
* If you want to run a subset of the commands, change to the directory that contains those tests.
* Run the unit test from the command using the following command:

php runtests.php

The unit test will the run, and the results are rendered.

== Trouble shooting ==

The provided configurations should work out of the box. We have seen problems with it (currently the cause is unknown). If you get an error like blow, the solution is pretty easy.

file=/var/www/unittest/runtests.php
posn=17
base=runtests.php
/var/www
JPATH_BASE does not point to a valid Joomla! installation:
JPATH_BASE = /var/www
Please modify your copy of "TestConfiguration.php"

Modify the ''"TestConfiguration.php"'' file and change the definition of the JPATH_BASE so it points to the path of you Joomla! installation, in the example below the Joomla! installation is installed at "''/var/www/update''".

define('JPATH_BASE', '/var/www/update');

==See also==
[http://www.phpunit.de/pocket_guide/3.2/en/index.html PHPUnit Pocket Guide]

[[Category:Development]]

Unit Testing

2008-06-21T14:02:12Z

Instance: /* News and Updates */

{{cookiejar}}
== News and Updates ==
2008 06 21: Added --class-exclude, --sequence-exclude, and --test-exclude options.

2008 06 21: PHPUnit has been updated to version 3.2.21 with SVN rev 10436. Please update.

== Unit Testing ==
Unit testing is an essential part of a good Quality Control program.
For a good general discussion of unit testing, visit the [http://en.wikipedia.org/wiki/Unit_test Wikipedia article].

=== Unit Testing in Open Source ===
Open source projects, with multiple developers working in parallel around the world, can greatly benefit from unit testing. The main benefits are:
* Unit tests help highlight cases where seemingly minor changes cause unexpected breakage.
* Unit tests help clearly specify how a class should behave.
* Unit tests can expose design flaws very early in development.
* Unit tests make great examples. They are a great place for developers to learn how to use the code.

=== The Testing Hierarchy: Unit, Subsystem, Integrated ===
Software testing systems usually run through a spectrum from "pure" unit tests through to fully integrated systems tests. We've described low level unit tests above. Integrated testing typically involves some sort of script that simulates user actions and then verifies that the result matches what's expected. This sort of "end to end" test verifies that all parts of the system are working correctly.

It's unfortunate that there is no clear nomenclature to describe all the intermediate stages of testing. The next stage beyond testing a single unit of code is subsystem testing. A subsystem test verifies that two or more units of code are interacting correctly to produce the desired result. In the simplest case, a subsystem test can be created simply by replacing mock objects with real objects and running unit tests on the top level module. In practise, this tends to not work as well as expected, because the original unit test data wasn't designed for a subsystem test, or because the nature of the test cases needs to be changed in order to fully test the subsystem. After all there is little point in simply repeating the unit test cases; the objective of a subsystem test should be to test boundary conditions and special cases that would be difficult to duplicate in unit tests.

Once a subsystem has been tested, it can be integrated into a larger system, which is still a subset of the whole product. Tests can be written for larger and larger subsystems, but at each stage the complexity of the tests increases. At some point, the effort required to hand craft tests exceeds the benefits of running them. This is where integrated testing comes in.

Integrated testing involves recording a user's interaction with the system into a script that can be replayed. The testing framework then compares the system's response with the expected response and passes or fails the test. The PHPUnit testing framework that we use has the ability to work with Selenium, a browser based test automation tool.

==== Test Objects ====
The purpose of unit tests is to isolate a module of code. A test that tests only one thing provides better information than a test that involves several object interactions. But how do we isolate an object from its dependencies? By writing stub classes. [http://xunitpatterns.com/Mocks,%20Fakes,%20Stubs%20and%20Dummies.html xUnit Patterns] defines a the hierarchy of dummy classes, ranging from simple to complex:
* Dummy - Defines attributes and methods of a dummy class (not particularly useful in PHP).
* Fake - Provides canned responses to method calls and fixed attribute values. Good for speed.
* Stub - Allows the test to define responses to method calls (return values, exceptions) to simulate the dependent object.
* Spy - A Fake or Stub that records method calls and parameters for later analysis.
* Mock - A Fake or Stub with a set of expectations -- method calls and parameters -- that are automatically verified for correctness.

=== Unit Testing in Joomla! ===
Unit testing capabilities in Joomla are still at an early stage. The intention is to define more standards for developing tests, and then to expand the scope of available tests.

For an overview of unit testing status in Joomla visit the [[Unit_Testing_Status]] page.

The SVN repository contains code under the /testing path. /testing/trunk contains code based on the SimpleTest framework. In early December 2007, the development team elected to move to the [http://www.phpunit.de PHPUnit] framework.

Work on using PHPUnit has been done in '''/testing/branches/2007-12-17'''. Some new tests have been added, many old tests from the SimpleTest days are completely broken.

At this point, PHPUnit based tests only run in a command line environment.

==== The Unit Test Team ====
If you can commit to the Joomla code base, then you should consider yourself part of the unit test team!

Writing tests concurrently with code (or even before) is a good way to not only save development time, but a great tool for defending against regressions. Writing tests early in the development cycle also helps identify and resolve design issues sooner, which reduces refactoring.

If you want to get started on unit testing, get in touch with Alan Langford (instance) or Ray Tsai (mihu). Either of us will be happy to help out.
==== Current Work ====
* There is no longer any need to patch the main code to enable unit tests.
* Basic techniques for mock objects are defined.
* Strategies for dealing with local configuration is not yet complete, but there is a plan.
* Files of the form class-sequence-type-test.php, for example JObject-0000-class-test.php use PHPUnit.
* The JDate tests present a good example of a data-driven test, but they won't run on the current 1.5 code base (there are some proposed API changes as a result of unit test development).
* Previously functional tests, such as JFTP, haven't been moved to the PHPUnit environment yet.

==== Writing Unit Tests ====
At risk of stating the obvious, in the "purest" case the purpose of a unit test is to ''isolate a unit of code from its environment and to test the operation of that code''.

This isolation is usually achieved by writing dummy classes that emulate the code unit's environment. These dummy objects can be passive, by simply simulating the environment, or they can be more active, keeping track of how they are being used by the test unit and reporting any variations from the expected behaviour. See [[Unit_Testing_Mock_Objects|Mock Objects in Joomla]] for a detailed example.

An interesting aspect of writing tests is that they become ''de facto'' detailed technical specifications of the interfaces between units of code. The fact that these specifications can be verified in an automated way makes them a superb resource when refactoring code.

The test code has a few templates designed to kick-start a test. They are:

/unittest/sample-datatest-php.txt
/unittest/sample-simpletest.php.txt

Here are some example tests: [[Unit_Testing_--_a_Simple_Example|Simple Example]], [[Unit_Testing_--_Data_Driven_Example|Data Driven Example]], [[Unit_Testing_--_Plugin_Example|Plugin Example]].

==== Running Unit Tests ====
Test files follow the form class-sequence-type-test.php, for example JObject-0000-class-test.php. For tests that are not class based, the first element refers to the object being tested. An example of this is the e-mail cloaking plugin test, which is called emailcloak-0000-mode1-test.php.

Joomla unit tests use a customized test "runner". Every test directory should have a "runtests.php" file. Runtests has a few options, mostly to allow the selection of specific tests. The command line options are:

--class-exclude ''regex''

e.g. --class-exclude /JDate.*/ Skips tests that have a class part that match the regular expression.

--class-filter ''regex''

e.g. --class-filter /JDate/ Selects only tests that have a class part that match the regular expression.

--debug

Turns on additional debugging output.

--help

Prints information on options and exits.

--sequence-exclude ''regex''

Skips tests that have a sequence part that match the regular expression.

--sequence-filter ''regex''

Selects only tests that have a sequence part that matches the regular expression.

--test-exclude ''regex''

Skips tests that have a test part that match the regular expression.

--test-filter ''regex''

Selects only tests that have a test part that match the regular expression.

'''TODO:''' Expand command line parsing to add other features of the PHPUnit framework, such as output formats, code metrics reports, etc.

== How to Get it Running ==

Before you start make sure you have installed PHPUnit and of course PHP (5!) properly...

To get the unit tests to run on your Joomla! installation, perform the following steps:
* Create an instance of your Joomla! installation
* In the root checkout (or export) the latest version of the unit test code from SVN ''"/testing/branches/2007-12-17"'' to your installation base. This will create a ''"/unittest"'' sub-folder under your joomla installation.
* Create a ''"TestConfiguration.php"'' file. You can copy a the file from ''"TestConfiguration-dist.php"'' that is part of the package you just have checked out.
* If you want to run a subset of the commands, change to the directory that contains those tests.
* Run the unit test from the command using the following command:

php runtests.php

The unit test will the run, and the results are rendered.

== Trouble shooting ==

The provided configurations should work out of the box. We have seen problems with it (currently the cause is unknown). If you get an error like blow, the solution is pretty easy.

file=/var/www/unittest/runtests.php
posn=17
base=runtests.php
/var/www
JPATH_BASE does not point to a valid Joomla! installation:
JPATH_BASE = /var/www
Please modify your copy of "TestConfiguration.php"

Modify the ''"TestConfiguration.php"'' file and change the definition of the JPATH_BASE so it points to the path of you Joomla! installation, in the example below the Joomla! installation is installed at "''/var/www/update''".

define('JPATH_BASE', '/var/www/update');

==See also==
[http://www.phpunit.de/pocket_guide/3.2/en/index.html PHPUnit Pocket Guide]

[[Category:Development]]

Unit Testing

2008-06-21T13:59:41Z

Instance: /* Running Unit Tests */ Added docs for the new exclude filters.

{{cookiejar}}
== News and Updates ==
2008 06 21: PHPUnit has been updated to version 3.2.21 with SVN rev 10436. Please update.

== Unit Testing ==
Unit testing is an essential part of a good Quality Control program.
For a good general discussion of unit testing, visit the [http://en.wikipedia.org/wiki/Unit_test Wikipedia article].

=== Unit Testing in Open Source ===
Open source projects, with multiple developers working in parallel around the world, can greatly benefit from unit testing. The main benefits are:
* Unit tests help highlight cases where seemingly minor changes cause unexpected breakage.
* Unit tests help clearly specify how a class should behave.
* Unit tests can expose design flaws very early in development.
* Unit tests make great examples. They are a great place for developers to learn how to use the code.

=== The Testing Hierarchy: Unit, Subsystem, Integrated ===
Software testing systems usually run through a spectrum from "pure" unit tests through to fully integrated systems tests. We've described low level unit tests above. Integrated testing typically involves some sort of script that simulates user actions and then verifies that the result matches what's expected. This sort of "end to end" test verifies that all parts of the system are working correctly.

It's unfortunate that there is no clear nomenclature to describe all the intermediate stages of testing. The next stage beyond testing a single unit of code is subsystem testing. A subsystem test verifies that two or more units of code are interacting correctly to produce the desired result. In the simplest case, a subsystem test can be created simply by replacing mock objects with real objects and running unit tests on the top level module. In practise, this tends to not work as well as expected, because the original unit test data wasn't designed for a subsystem test, or because the nature of the test cases needs to be changed in order to fully test the subsystem. After all there is little point in simply repeating the unit test cases; the objective of a subsystem test should be to test boundary conditions and special cases that would be difficult to duplicate in unit tests.

Once a subsystem has been tested, it can be integrated into a larger system, which is still a subset of the whole product. Tests can be written for larger and larger subsystems, but at each stage the complexity of the tests increases. At some point, the effort required to hand craft tests exceeds the benefits of running them. This is where integrated testing comes in.

Integrated testing involves recording a user's interaction with the system into a script that can be replayed. The testing framework then compares the system's response with the expected response and passes or fails the test. The PHPUnit testing framework that we use has the ability to work with Selenium, a browser based test automation tool.

==== Test Objects ====
The purpose of unit tests is to isolate a module of code. A test that tests only one thing provides better information than a test that involves several object interactions. But how do we isolate an object from its dependencies? By writing stub classes. [http://xunitpatterns.com/Mocks,%20Fakes,%20Stubs%20and%20Dummies.html xUnit Patterns] defines a the hierarchy of dummy classes, ranging from simple to complex:
* Dummy - Defines attributes and methods of a dummy class (not particularly useful in PHP).
* Fake - Provides canned responses to method calls and fixed attribute values. Good for speed.
* Stub - Allows the test to define responses to method calls (return values, exceptions) to simulate the dependent object.
* Spy - A Fake or Stub that records method calls and parameters for later analysis.
* Mock - A Fake or Stub with a set of expectations -- method calls and parameters -- that are automatically verified for correctness.

=== Unit Testing in Joomla! ===
Unit testing capabilities in Joomla are still at an early stage. The intention is to define more standards for developing tests, and then to expand the scope of available tests.

For an overview of unit testing status in Joomla visit the [[Unit_Testing_Status]] page.

The SVN repository contains code under the /testing path. /testing/trunk contains code based on the SimpleTest framework. In early December 2007, the development team elected to move to the [http://www.phpunit.de PHPUnit] framework.

Work on using PHPUnit has been done in '''/testing/branches/2007-12-17'''. Some new tests have been added, many old tests from the SimpleTest days are completely broken.

At this point, PHPUnit based tests only run in a command line environment.

==== The Unit Test Team ====
If you can commit to the Joomla code base, then you should consider yourself part of the unit test team!

Writing tests concurrently with code (or even before) is a good way to not only save development time, but a great tool for defending against regressions. Writing tests early in the development cycle also helps identify and resolve design issues sooner, which reduces refactoring.

If you want to get started on unit testing, get in touch with Alan Langford (instance) or Ray Tsai (mihu). Either of us will be happy to help out.
==== Current Work ====
* There is no longer any need to patch the main code to enable unit tests.
* Basic techniques for mock objects are defined.
* Strategies for dealing with local configuration is not yet complete, but there is a plan.
* Files of the form class-sequence-type-test.php, for example JObject-0000-class-test.php use PHPUnit.
* The JDate tests present a good example of a data-driven test, but they won't run on the current 1.5 code base (there are some proposed API changes as a result of unit test development).
* Previously functional tests, such as JFTP, haven't been moved to the PHPUnit environment yet.

==== Writing Unit Tests ====
At risk of stating the obvious, in the "purest" case the purpose of a unit test is to ''isolate a unit of code from its environment and to test the operation of that code''.

This isolation is usually achieved by writing dummy classes that emulate the code unit's environment. These dummy objects can be passive, by simply simulating the environment, or they can be more active, keeping track of how they are being used by the test unit and reporting any variations from the expected behaviour. See [[Unit_Testing_Mock_Objects|Mock Objects in Joomla]] for a detailed example.

An interesting aspect of writing tests is that they become ''de facto'' detailed technical specifications of the interfaces between units of code. The fact that these specifications can be verified in an automated way makes them a superb resource when refactoring code.

The test code has a few templates designed to kick-start a test. They are:

/unittest/sample-datatest-php.txt
/unittest/sample-simpletest.php.txt

Here are some example tests: [[Unit_Testing_--_a_Simple_Example|Simple Example]], [[Unit_Testing_--_Data_Driven_Example|Data Driven Example]], [[Unit_Testing_--_Plugin_Example|Plugin Example]].

==== Running Unit Tests ====
Test files follow the form class-sequence-type-test.php, for example JObject-0000-class-test.php. For tests that are not class based, the first element refers to the object being tested. An example of this is the e-mail cloaking plugin test, which is called emailcloak-0000-mode1-test.php.

Joomla unit tests use a customized test "runner". Every test directory should have a "runtests.php" file. Runtests has a few options, mostly to allow the selection of specific tests. The command line options are:

--class-exclude ''regex''

e.g. --class-exclude /JDate.*/ Skips tests that have a class part that match the regular expression.

--class-filter ''regex''

e.g. --class-filter /JDate/ Selects only tests that have a class part that match the regular expression.

--debug

Turns on additional debugging output.

--help

Prints information on options and exits.

--sequence-exclude ''regex''

Skips tests that have a sequence part that match the regular expression.

--sequence-filter ''regex''

Selects only tests that have a sequence part that matches the regular expression.

--test-exclude ''regex''

Skips tests that have a test part that match the regular expression.

--test-filter ''regex''

Selects only tests that have a test part that match the regular expression.

'''TODO:''' Expand command line parsing to add other features of the PHPUnit framework, such as output formats, code metrics reports, etc.

== How to Get it Running ==

Before you start make sure you have installed PHPUnit and of course PHP (5!) properly...

To get the unit tests to run on your Joomla! installation, perform the following steps:
* Create an instance of your Joomla! installation
* In the root checkout (or export) the latest version of the unit test code from SVN ''"/testing/branches/2007-12-17"'' to your installation base. This will create a ''"/unittest"'' sub-folder under your joomla installation.
* Create a ''"TestConfiguration.php"'' file. You can copy a the file from ''"TestConfiguration-dist.php"'' that is part of the package you just have checked out.
* If you want to run a subset of the commands, change to the directory that contains those tests.
* Run the unit test from the command using the following command:

php runtests.php

The unit test will the run, and the results are rendered.

== Trouble shooting ==

The provided configurations should work out of the box. We have seen problems with it (currently the cause is unknown). If you get an error like blow, the solution is pretty easy.

file=/var/www/unittest/runtests.php
posn=17
base=runtests.php
/var/www
JPATH_BASE does not point to a valid Joomla! installation:
JPATH_BASE = /var/www
Please modify your copy of "TestConfiguration.php"

Modify the ''"TestConfiguration.php"'' file and change the definition of the JPATH_BASE so it points to the path of you Joomla! installation, in the example below the Joomla! installation is installed at "''/var/www/update''".

define('JPATH_BASE', '/var/www/update');

==See also==
[http://www.phpunit.de/pocket_guide/3.2/en/index.html PHPUnit Pocket Guide]

[[Category:Development]]

Unit Testing

2008-06-21T13:17:46Z

Instance: /* Unit Testing */ Added news and update section.

{{cookiejar}}
== News and Updates ==
2008 06 21: PHPUnit has been updated to version 3.2.21 with SVN rev 10436. Please update.

== Unit Testing ==
Unit testing is an essential part of a good Quality Control program.
For a good general discussion of unit testing, visit the [http://en.wikipedia.org/wiki/Unit_test Wikipedia article].

=== Unit Testing in Open Source ===
Open source projects, with multiple developers working in parallel around the world, can greatly benefit from unit testing. The main benefits are:
* Unit tests help highlight cases where seemingly minor changes cause unexpected breakage.
* Unit tests help clearly specify how a class should behave.
* Unit tests can expose design flaws very early in development.
* Unit tests make great examples. They are a great place for developers to learn how to use the code.

=== The Testing Hierarchy: Unit, Subsystem, Integrated ===
Software testing systems usually run through a spectrum from "pure" unit tests through to fully integrated systems tests. We've described low level unit tests above. Integrated testing typically involves some sort of script that simulates user actions and then verifies that the result matches what's expected. This sort of "end to end" test verifies that all parts of the system are working correctly.

It's unfortunate that there is no clear nomenclature to describe all the intermediate stages of testing. The next stage beyond testing a single unit of code is subsystem testing. A subsystem test verifies that two or more units of code are interacting correctly to produce the desired result. In the simplest case, a subsystem test can be created simply by replacing mock objects with real objects and running unit tests on the top level module. In practise, this tends to not work as well as expected, because the original unit test data wasn't designed for a subsystem test, or because the nature of the test cases needs to be changed in order to fully test the subsystem. After all there is little point in simply repeating the unit test cases; the objective of a subsystem test should be to test boundary conditions and special cases that would be difficult to duplicate in unit tests.

Once a subsystem has been tested, it can be integrated into a larger system, which is still a subset of the whole product. Tests can be written for larger and larger subsystems, but at each stage the complexity of the tests increases. At some point, the effort required to hand craft tests exceeds the benefits of running them. This is where integrated testing comes in.

Integrated testing involves recording a user's interaction with the system into a script that can be replayed. The testing framework then compares the system's response with the expected response and passes or fails the test. The PHPUnit testing framework that we use has the ability to work with Selenium, a browser based test automation tool.

==== Test Objects ====
The purpose of unit tests is to isolate a module of code. A test that tests only one thing provides better information than a test that involves several object interactions. But how do we isolate an object from its dependencies? By writing stub classes. [http://xunitpatterns.com/Mocks,%20Fakes,%20Stubs%20and%20Dummies.html xUnit Patterns] defines a the hierarchy of dummy classes, ranging from simple to complex:
* Dummy - Defines attributes and methods of a dummy class (not particularly useful in PHP).
* Fake - Provides canned responses to method calls and fixed attribute values. Good for speed.
* Stub - Allows the test to define responses to method calls (return values, exceptions) to simulate the dependent object.
* Spy - A Fake or Stub that records method calls and parameters for later analysis.
* Mock - A Fake or Stub with a set of expectations -- method calls and parameters -- that are automatically verified for correctness.

=== Unit Testing in Joomla! ===
Unit testing capabilities in Joomla are still at an early stage. The intention is to define more standards for developing tests, and then to expand the scope of available tests.

For an overview of unit testing status in Joomla visit the [[Unit_Testing_Status]] page.

The SVN repository contains code under the /testing path. /testing/trunk contains code based on the SimpleTest framework. In early December 2007, the development team elected to move to the [http://www.phpunit.de PHPUnit] framework.

Work on using PHPUnit has been done in '''/testing/branches/2007-12-17'''. Some new tests have been added, many old tests from the SimpleTest days are completely broken.

At this point, PHPUnit based tests only run in a command line environment.

==== The Unit Test Team ====
If you can commit to the Joomla code base, then you should consider yourself part of the unit test team!

Writing tests concurrently with code (or even before) is a good way to not only save development time, but a great tool for defending against regressions. Writing tests early in the development cycle also helps identify and resolve design issues sooner, which reduces refactoring.

If you want to get started on unit testing, get in touch with Alan Langford (instance) or Ray Tsai (mihu). Either of us will be happy to help out.
==== Current Work ====
* There is no longer any need to patch the main code to enable unit tests.
* Basic techniques for mock objects are defined.
* Strategies for dealing with local configuration is not yet complete, but there is a plan.
* Files of the form class-sequence-type-test.php, for example JObject-0000-class-test.php use PHPUnit.
* The JDate tests present a good example of a data-driven test, but they won't run on the current 1.5 code base (there are some proposed API changes as a result of unit test development).
* Previously functional tests, such as JFTP, haven't been moved to the PHPUnit environment yet.

==== Writing Unit Tests ====
At risk of stating the obvious, in the "purest" case the purpose of a unit test is to ''isolate a unit of code from its environment and to test the operation of that code''.

This isolation is usually achieved by writing dummy classes that emulate the code unit's environment. These dummy objects can be passive, by simply simulating the environment, or they can be more active, keeping track of how they are being used by the test unit and reporting any variations from the expected behaviour. See [[Unit_Testing_Mock_Objects|Mock Objects in Joomla]] for a detailed example.

An interesting aspect of writing tests is that they become ''de facto'' detailed technical specifications of the interfaces between units of code. The fact that these specifications can be verified in an automated way makes them a superb resource when refactoring code.

The test code has a few templates designed to kick-start a test. They are:

/unittest/sample-datatest-php.txt
/unittest/sample-simpletest.php.txt

Here are some example tests: [[Unit_Testing_--_a_Simple_Example|Simple Example]], [[Unit_Testing_--_Data_Driven_Example|Data Driven Example]], [[Unit_Testing_--_Plugin_Example|Plugin Example]].

==== Running Unit Tests ====
Test files follow the form class-sequence-type-test.php, for example JObject-0000-class-test.php. For tests that are not class based, the first element refers to the object being tested. An example of this is the e-mail cloaking plugin test, which is called emailcloak-0000-mode1-test.php.

Joomla unit tests use a customized test "runner". Every test directory should have a "runtests.php" file. Runtests has a few options, mostly to allow the selection of specific tests. The command line options are:

--class-filter ''regex''

e.g. --class-filter /JDate/ Selects only tests that have a class part that matches the regular expression.

--debug

Turns on additional debugging output.

--help

Prints information on options and exits.

--sequence-filter ''regex''

Selects only tests that have a sequence part that matches the regular expression.

--test-filter ''regex''

Selects only tests that have a test part that matches the regular expression.

'''TODO:''' Expand command line parsing to add other features of the PHPUnit framework, such as output formats, code metrics reports, etc.

== How to Get it Running ==

Before you start make sure you have installed PHPUnit and of course PHP (5!) properly...

To get the unit tests to run on your Joomla! installation, perform the following steps:
* Create an instance of your Joomla! installation
* In the root checkout (or export) the latest version of the unit test code from SVN ''"/testing/branches/2007-12-17"'' to your installation base. This will create a ''"/unittest"'' sub-folder under your joomla installation.
* Create a ''"TestConfiguration.php"'' file. You can copy a the file from ''"TestConfiguration-dist.php"'' that is part of the package you just have checked out.
* If you want to run a subset of the commands, change to the directory that contains those tests.
* Run the unit test from the command using the following command:

php runtests.php

The unit test will the run, and the results are rendered.

== Trouble shooting ==

The provided configurations should work out of the box. We have seen problems with it (currently the cause is unknown). If you get an error like blow, the solution is pretty easy.

file=/var/www/unittest/runtests.php
posn=17
base=runtests.php
/var/www
JPATH_BASE does not point to a valid Joomla! installation:
JPATH_BASE = /var/www
Please modify your copy of "TestConfiguration.php"

Modify the ''"TestConfiguration.php"'' file and change the definition of the JPATH_BASE so it points to the path of you Joomla! installation, in the example below the Joomla! installation is installed at "''/var/www/update''".

define('JPATH_BASE', '/var/www/update');

==See also==
[http://www.phpunit.de/pocket_guide/3.2/en/index.html PHPUnit Pocket Guide]

[[Category:Development]]

Pizza Bugs and Fun 2

2008-06-21T11:16:52Z

Instance: /* Internet Relay Chat (IRC) */

[[Image:pbf.png|right]]
{{RightTOC}}
We eagerly announce the second Joomla! Pizza Bug and Fun event scheduled for the weekends of '''June 21 and 22''' and '''June 28 and 29'''. It's hard to believe that six months have passed since the first Joomla! Pizza Bug and Fun event. The first PBF helped finalize Joomla! 1.5 and, if all goes as planned, this second event will help prepare Joomla! 1.5.4 for release early in July.

This wiki will be used as the central resource for coordinating efforts and accumulating results from this event.

== Goals ==

* '''Bugs''' : For our first PBF event, we targeted priority 1 and 2 bugs and tested the entire application. Since it's release, Joomla! 1.5 has been very stable and there are no serious bugs to fix. But, there are a number of medium priority items that require patches and testing. If we are able to empty the tracker during the weekend, it would be an important accomplishment for the community.

* '''Documentation''' : since the last [[Doc Camp 1|Doc Camp]] a lot of documentation has been written, but we need more of it. If you want to help out writing documentation, you're also more than welcome.

* '''Unit testing''' : we have started writing unit tests for Joomla! This is documented in the wiki, see [[Unit Testing]] for details. This is a very important part to improve the overall quality of Joomla! and increase development speed. If you have experience in this area, we challenge you to come help us.

== FAQ ==
Below you will find as much as possible information we can share on how this events is organized. If you don't find what you are looking for, you can check out the [[PBF FAQ]].

== Organization, logistics and communications ==

Managing this event will be a challenge. The team of [[Pizza couriers]] is working on the organization of this event, taking care of all logistics, infrastructure and communications.

'''Read this blog for information on how to get started when you arrive for the Pizza, Bugs and Fun event:'''
see http://developer.joomla.org/home/26-coordinator-blog/147-the-best-ingredients-for-a-nice-pizza.html

== Locations ==

If you want to get people together and have a venue to share, please add it below. Share as much as possible details like exact location, url for more information about the venue, ways to register, date and time the venue is available etc. If you have any questions regarding this, feel free to contact Wilco Jansen (wilco.jansen@joomla.org).

=== Europe ===
Hotel La Meridiana
Viale Italia 198 - Marina Romea 48010 Ravenna (Ra) Italy
28 June 2008
Additional information [http://www.joomladay.it/ www.joomladay.it]
To register post [http://forum.joomla.it/index.php/topic,44604.0.html here]
[http://www.joomladay.it/component/option,com_contact/task,view/contact_id,1/Itemid,2 Contacts]

JUG Catalan Countries
June 21. Can Domenge Centre Tecnologic. Soldat Arrom quart, 1. Palma de Mallorca Spain
[http://www.joomla.cat JUG Catalan Countries Website]

There will also be a location in the Netherlands (Amsterdam, Rotterdam or Eindhoven, most likely it will be Rotterdam)
If you are interested please send a mail to wilco.jansen@joomla.org

=== North America ===

Webimagery, LLC
843 Carondelet St. Suite 6
New Orleans, LA 70130
USA
[http://jpbf2nola1.eventbrite.com June 21 Registration]
[http://jpbf2nola2.eventbrite.com June 22 Registration]

PICnet, Inc. (DC)
1341 G St, NW, Suite 1100
Washington DC, 20005
[http://www.joomladayusa.org/index.php?option=com_events&type=event&task=details&id=6&Itemid=11 Registration Page]

New York City JUG
Address to be verified shortly
[http://www.joomlanyc.org Joomla NYC Website]

Vancouver, BC, Canada
822 Homer (at Robson)
Across from where the JoomlaDay event was held.
Call Mike Hamanaka or Amir Sharifnejad at +1-604-626-9225 and we will buzz you in.
[website to be announced]

=== South America ===
No venue registered

=== Asia/Pacific ===

Spike Systems Pty Ltd
Level 6, 99 York Street
Sydney.
Map here: http://tinyurl.com/4gwatl
URL with additional information will follow soon (including registration option).

------
Please enter your location in Asia here, provide us with:
location and name of the venue, date(s)/time (don't forget the timezone),
url for more info, how to register, contact option

=== Africa ===
No venue registered

===Cyberspace===
====Internet Relay Chat (IRC)====
Freenode channel [irc://irc.freenode.net/joomlapbf #joomlapbf] from 21 to 22 June 2008, all times, all timezones.

If you don't have an IRC client installed, use this link: [http://www.joomlanyc.org/index.php?option=com_wrapper&Itemid=23 #joomlapbf]. This is a web-based IRC client.

This channel is available now and throughout the event. We might set up additional channels, if we do they will be listed above.

== Registration ==
=== For write access to this wiki ===
To get write access to this wiki you will need to [[Special:Userlogin|register here first]]. Please be aware that the registration process requires a valid email address. If you are traveling to one of the physical locations you are advised to ensure that you have registered on this wiki and have a valid login before you travel. You don't need access to your email account after registration.

=== At a physical location ===
If you wish to be present at one of the physical locations listed above then you must register in advance because space most likely is limited. Registrations are the responsibility of the individual location organizers and you should click on the appropriate link above for more information.

=== Taking bugs, tasks and pizza ===
Pizza can be ordered at a shop near by :-)

Please check the [http://docs.joomla.org/Pizza_Bugs_and_Fun_2#Organization.2C_logistics_and_communications Organization, logistics and communications section] for detail on how to get involved in working on tasks.

==Requirements==
* All code must be made available under the [http://www.gnu.org/licenses/gpl-2.0.html General Public Licence version 2].
* All documentation contributions must be made available under the [[JEDL|Joomla! Electronic Documentation License]]. Further information on the JEDL is available in the [[JEDL/FAQ|JEDL Frequently Asked Questions]]
* No advertising or self-promotion will be allowed. This includes back links to your website or anyone else's. The one exception is that if you have made a contribution then feel free to add your name and an optional link to your website to the [[PBF Contributors List]]
* All contributions must be in English. Note that the official language of the Joomla! project is British/Australian English.
{{:PBF_Contributors_List}}
[[Category: Development]]

Pizza Bugs and Fun 2/Contributors List

2008-06-20T13:59:34Z

Instance: /* Contributors to the second PBF */

<noinclude>If you made a contribution to the documentation held on this site, please feel free to add your name below. Please consider adding your real name in addition to your nickname. You may, optionally, include a link to your website.</noinclude>

== Contributors to the second PBF ==

<font color=red>'''The people below plan to participate to PBF. Afterwards the list will be validated for the present we are planning. Those who haven't participated will be removed from this list afterward.'''</font>

* Chris Davenport ([[Special:Contributions/Chris_Davenport|contributions]])
* Kevin Devine ([[Special:Contributions/Kevin_Devine|contributions]])
* Anthony Ferrara ([[Special:Contributions/ircmaxell|contributions]])
* Jerry Hilburn ([[Special:Contributions/Jerry_Hilburn|contributions]])
* Louis Landry ([[Special:Contributions/Louis_Landry|contributions]])
* Wilco Jansen ([[Special:Contributions/willebil|contributions]])
* Jennifer Marriott ([[Special:Contributions/MMMedia|contributions]])
* Rob Schley ([[Special:Contributions/Rob_Schley|contributions]])
* Amy Stephen ([[Special:Contributions/AmyStephen|contributions]])
* Nereyda Valentin-Macias ([[Special:Contributions/Neriv|contributions]])
* Elin Waring ([[Special:Contributions/Elin|contributions]])
* Michael Casha ([[Special:Contributions/MiCCAS|contributions]])
* Phil Taylor ([[Special:Contributions/Prazgod|contributions]])
* Marcelo Eden ([[Special:Contributions/3dentech|contributions]])
* Matt Thomas ([[Special:Contributions/betweenbrain|contributions]])
* Ross Crawford ([[Special:Contributions/RoscoHead|contributions]])
* Mickael Maison ([[Special:Contributions/Mmaison|contributions]])
* Ian MacLennan ([[Special:Contributions/ian|contributions]])
* Jaap Woltjes ([[Special:Contributions/japie1001|contributions]])
* Alan Langford ([[Special:Contributions/Instance|contributions]])

Unit Testing

2008-05-23T16:33:08Z

Instance: /* How to Get it Running */ A little more formatting and add test subset tip.

{{cookiejar}}
== Unit Testing ==
Unit testing is an essential part of a good Quality Control program.
For a good general discussion of unit testing, visit the [http://en.wikipedia.org/wiki/Unit_test Wikipedia article].

=== Unit Testing in Open Source ===
Open source projects, with multiple developers working in parallel around the world, can greatly benefit from unit testing. The main benefits are:
* Unit tests help highlight cases where seemingly minor changes cause unexpected breakage.
* Unit tests help clearly specify how a class should behave.
* Unit tests can expose design flaws very early in development.
* Unit tests make great examples. They are a great place for developers to learn how to use the code.

=== The Testing Hierarchy: Unit, Subsystem, Integrated ===
Software testing systems usually run through a spectrum from "pure" unit tests through to fully integrated systems tests. We've described low level unit tests above. Integrated testing typically involves some sort of script that simulates user actions and then verifies that the result matches what's expected. This sort of "end to end" test verifies that all parts of the system are working correctly.

It's unfortunate that there is no clear nomenclature to describe all the intermediate stages of testing. The next stage beyond testing a single unit of code is subsystem testing. A subsystem test verifies that two or more units of code are interacting correctly to produce the desired result. In the simplest case, a subsystem test can be created simply by replacing mock objects with real objects and running unit tests on the top level module. In practise, this tends to not work as well as expected, because the original unit test data wasn't designed for a subsystem test, or because the nature of the test cases needs to be changed in order to fully test the subsystem. After all there is little point in simply repeating the unit test cases; the objective of a subsystem test should be to test boundary conditions and special cases that would be difficult to duplicate in unit tests.

Once a subsystem has been tested, it can be integrated into a larger system, which is still a subset of the whole product. Tests can be written for larger and larger subsystems, but at each stage the complexity of the tests increases. At some point, the effort required to hand craft tests exceeds the benefits of running them. This is where integrated testing comes in.

Integrated testing involves recording a user's interaction with the system into a script that can be replayed. The testing framework then compares the system's response with the expected response and passes or fails the test. The PHPUnit testing framework that we use has the ability to work with Selenium, a browser based test automation tool.

==== Test Objects ====
The purpose of unit tests is to isolate a module of code. A test that tests only one thing provides better information than a test that involves several object interactions. But how do we isolate an object from its dependencies? By writing stub classes. [http://xunitpatterns.com/Mocks,%20Fakes,%20Stubs%20and%20Dummies.html xUnit Patterns] defines a the hierarchy of dummy classes, ranging from simple to complex:
* Dummy - Defines attributes and methods of a dummy class (not particularly useful in PHP).
* Fake - Provides canned responses to method calls and fixed attribute values. Good for speed.
* Stub - Allows the test to define responses to method calls (return values, exceptions) to simulate the dependent object.
* Spy - A Fake or Stub that records method calls and parameters for later analysis.
* Mock - A Fake or Stub with a set of expectations -- method calls and parameters -- that are automatically verified for correctness.

=== Unit Testing in Joomla! ===
Unit testing capabilities in Joomla are still at an early stage. The intention is to define more standards for developing tests, and then to expand the scope of available tests

The SVN repository contains code under the /testing path. /testing/trunk contains code based on the SimpleTest framework. In early December 2007, the development team elected to move to the [http://www.phpunit.de PHPUnit] framework.

Work on using PHPUnit has been done in '''/testing/branches/2007-12-17'''. Some new tests have been added, many old tests from the SimpleTest days are completely broken.

At this point, PHPUnit based tests only run in a command line environment.

==== The Unit Test Team ====
If you can commit to the Joomla code base, then you should consider yourself part of the unit test team!

Writing tests concurrently with code (or even before) is a good way to not only save development time, but a great tool for defending against regressions. Writing tests early in the development cycle also helps identify and resolve design issues sooner, which reduces refactoring.

If you want to get started on unit testing, get in touch with Alan Langford (instance) or Ray Tsai (mihu). Either of us will be happy to help out.
==== Current Work ====
* There is no longer any need to patch the main code to enable unit tests.
* Basic techniques for mock objects are defined.
* Strategies for dealing with local configuration is not yet complete, but there is a plan.
* Files of the form class-sequence-type-test.php, for example JObject-0000-class-test.php use PHPUnit.
* The JDate tests present a good example of a data-driven test, but they won't run on the current 1.5 code base (there are some proposed API changes as a result of unit test development).
* Previously functional tests, such as JFTP, haven't been moved to the PHPUnit environment yet.

==== Writing Unit Tests ====
At risk of stating the obvious, in the "purest" case the purpose of a unit test is to ''isolate a unit of code from its environment and to test the operation of that code''.

This isolation is usually achieved by writing dummy classes that emulate the code unit's environment. These dummy objects can be passive, by simply simulating the environment, or they can be more active, keeping track of how they are being used by the test unit and reporting any variations from the expected behaviour. See [[Unit_Testing_Mock_Objects|Mock Objects in Joomla]] for a detailed example.

An interesting aspect of writing tests is that they become ''de facto'' detailed technical specifications of the interfaces between units of code. The fact that these specifications can be verified in an automated way makes them a superb resource when refactoring code.

The test code has a few templates designed to kick-start a test. They are:

/unittest/sample-datatest-php.txt
/unittest/sample-simpletest.php.txt

Here are some example tests: [[Unit_Testing_--_a_Simple_Example|Simple Example]], [[Unit_Testing_--_Data_Driven_Example|Data Driven Example]], [[Unit_Testing_--_Plugin_Example|Plugin Example]].

==== Running Unit Tests ====
Test files follow the form class-sequence-type-test.php, for example JObject-0000-class-test.php. For tests that are not class based, the first element refers to the object being tested. An example of this is the e-mail cloaking plugin test, which is called emailcloak-0000-mode1-test.php.

Joomla unit tests use a customized test "runner". Every test directory should have a "runtests.php" file. Runtests has a few options, mostly to allow the selection of specific tests. The command line options are:

--class-filter ''regex''

e.g. --class-filter /JDate/ Selects only tests that have a class part that matches the regular expression.

--debug

Turns on additional debugging output.

--help

Prints information on options and exits.

--sequence-filter ''regex''

Selects only tests that have a sequence part that matches the regular expression.

--test-filter ''regex''

Selects only tests that have a test part that matches the regular expression.

'''TODO:''' Expand command line parsing to add other features of the PHPUnit framework, such as output formats, code metrics reports, etc.

== How to Get it Running ==

Before you start make sure you have installed PHPUnit and of course PHP (5!) properly...

To get the unit tests to run on your Joomla! installation, perform the following steps:
* Create an instance of your Joomla! installation
* In the root checkout (or export) the latest version of the unit test code from SVN ''"/testing/branches/2007-12-17"'' to your installation base. This will create a ''"/unittest"'' sub-folder under your joomla installation.
* Create a ''"TestConfiguration.php"'' file. You can copy a the file from ''"TestConfiguration-dist.php"'' that is part of the package you just have checked out.
* If you want to run a subset of the commands, change to the directory that contains those tests.
* Run the unit test from the command using the following command:

php runtests.php

The unit test will the run, and the results are rendered.

== Trouble shooting ==

The provided configurations should work out of the box. We have seen problems with it (currently the cause is unknown). If you get an error like blow, the solution is pretty easy.

file=/var/www/unittest/runtests.php
posn=17
base=runtests.php
/var/www
JPATH_BASE does not point to a valid Joomla! installation:
JPATH_BASE = /var/www
Please modify your copy of "TestConfiguration.php"

Modify the ''"TestConfiguration.php"'' file and change the definition of the JPATH_BASE so it points to the path of you Joomla! installation, in the example below the Joomla! installation is installed at "''/var/www/update''".

define('JPATH_BASE', '/var/www/update');

[[Category:Development]]

Unit Testing

2008-05-23T16:30:07Z

Instance: /* How to get it running */ Formatting fixes

{{cookiejar}}
== Unit Testing ==
Unit testing is an essential part of a good Quality Control program.
For a good general discussion of unit testing, visit the [http://en.wikipedia.org/wiki/Unit_test Wikipedia article].

=== Unit Testing in Open Source ===
Open source projects, with multiple developers working in parallel around the world, can greatly benefit from unit testing. The main benefits are:
* Unit tests help highlight cases where seemingly minor changes cause unexpected breakage.
* Unit tests help clearly specify how a class should behave.
* Unit tests can expose design flaws very early in development.
* Unit tests make great examples. They are a great place for developers to learn how to use the code.

=== The Testing Hierarchy: Unit, Subsystem, Integrated ===
Software testing systems usually run through a spectrum from "pure" unit tests through to fully integrated systems tests. We've described low level unit tests above. Integrated testing typically involves some sort of script that simulates user actions and then verifies that the result matches what's expected. This sort of "end to end" test verifies that all parts of the system are working correctly.

It's unfortunate that there is no clear nomenclature to describe all the intermediate stages of testing. The next stage beyond testing a single unit of code is subsystem testing. A subsystem test verifies that two or more units of code are interacting correctly to produce the desired result. In the simplest case, a subsystem test can be created simply by replacing mock objects with real objects and running unit tests on the top level module. In practise, this tends to not work as well as expected, because the original unit test data wasn't designed for a subsystem test, or because the nature of the test cases needs to be changed in order to fully test the subsystem. After all there is little point in simply repeating the unit test cases; the objective of a subsystem test should be to test boundary conditions and special cases that would be difficult to duplicate in unit tests.

Once a subsystem has been tested, it can be integrated into a larger system, which is still a subset of the whole product. Tests can be written for larger and larger subsystems, but at each stage the complexity of the tests increases. At some point, the effort required to hand craft tests exceeds the benefits of running them. This is where integrated testing comes in.

Integrated testing involves recording a user's interaction with the system into a script that can be replayed. The testing framework then compares the system's response with the expected response and passes or fails the test. The PHPUnit testing framework that we use has the ability to work with Selenium, a browser based test automation tool.

==== Test Objects ====
The purpose of unit tests is to isolate a module of code. A test that tests only one thing provides better information than a test that involves several object interactions. But how do we isolate an object from its dependencies? By writing stub classes. [http://xunitpatterns.com/Mocks,%20Fakes,%20Stubs%20and%20Dummies.html xUnit Patterns] defines a the hierarchy of dummy classes, ranging from simple to complex:
* Dummy - Defines attributes and methods of a dummy class (not particularly useful in PHP).
* Fake - Provides canned responses to method calls and fixed attribute values. Good for speed.
* Stub - Allows the test to define responses to method calls (return values, exceptions) to simulate the dependent object.
* Spy - A Fake or Stub that records method calls and parameters for later analysis.
* Mock - A Fake or Stub with a set of expectations -- method calls and parameters -- that are automatically verified for correctness.

=== Unit Testing in Joomla! ===
Unit testing capabilities in Joomla are still at an early stage. The intention is to define more standards for developing tests, and then to expand the scope of available tests

The SVN repository contains code under the /testing path. /testing/trunk contains code based on the SimpleTest framework. In early December 2007, the development team elected to move to the [http://www.phpunit.de PHPUnit] framework.

Work on using PHPUnit has been done in '''/testing/branches/2007-12-17'''. Some new tests have been added, many old tests from the SimpleTest days are completely broken.

At this point, PHPUnit based tests only run in a command line environment.

==== The Unit Test Team ====
If you can commit to the Joomla code base, then you should consider yourself part of the unit test team!

Writing tests concurrently with code (or even before) is a good way to not only save development time, but a great tool for defending against regressions. Writing tests early in the development cycle also helps identify and resolve design issues sooner, which reduces refactoring.

If you want to get started on unit testing, get in touch with Alan Langford (instance) or Ray Tsai (mihu). Either of us will be happy to help out.
==== Current Work ====
* There is no longer any need to patch the main code to enable unit tests.
* Basic techniques for mock objects are defined.
* Strategies for dealing with local configuration is not yet complete, but there is a plan.
* Files of the form class-sequence-type-test.php, for example JObject-0000-class-test.php use PHPUnit.
* The JDate tests present a good example of a data-driven test, but they won't run on the current 1.5 code base (there are some proposed API changes as a result of unit test development).
* Previously functional tests, such as JFTP, haven't been moved to the PHPUnit environment yet.

==== Writing Unit Tests ====
At risk of stating the obvious, in the "purest" case the purpose of a unit test is to ''isolate a unit of code from its environment and to test the operation of that code''.

This isolation is usually achieved by writing dummy classes that emulate the code unit's environment. These dummy objects can be passive, by simply simulating the environment, or they can be more active, keeping track of how they are being used by the test unit and reporting any variations from the expected behaviour. See [[Unit_Testing_Mock_Objects|Mock Objects in Joomla]] for a detailed example.

An interesting aspect of writing tests is that they become ''de facto'' detailed technical specifications of the interfaces between units of code. The fact that these specifications can be verified in an automated way makes them a superb resource when refactoring code.

The test code has a few templates designed to kick-start a test. They are:

/unittest/sample-datatest-php.txt
/unittest/sample-simpletest.php.txt

Here are some example tests: [[Unit_Testing_--_a_Simple_Example|Simple Example]], [[Unit_Testing_--_Data_Driven_Example|Data Driven Example]], [[Unit_Testing_--_Plugin_Example|Plugin Example]].

==== Running Unit Tests ====
Test files follow the form class-sequence-type-test.php, for example JObject-0000-class-test.php. For tests that are not class based, the first element refers to the object being tested. An example of this is the e-mail cloaking plugin test, which is called emailcloak-0000-mode1-test.php.

Joomla unit tests use a customized test "runner". Every test directory should have a "runtests.php" file. Runtests has a few options, mostly to allow the selection of specific tests. The command line options are:

--class-filter ''regex''

e.g. --class-filter /JDate/ Selects only tests that have a class part that matches the regular expression.

--debug

Turns on additional debugging output.

--help

Prints information on options and exits.

--sequence-filter ''regex''

Selects only tests that have a sequence part that matches the regular expression.

--test-filter ''regex''

Selects only tests that have a test part that matches the regular expression.

'''TODO:''' Expand command line parsing to add other features of the PHPUnit framework, such as output formats, code metrics reports, etc.

== How to Get it Running ==

Before you start make sure you have installed PHPUnit and of course PHP (5!) properly...

To get the unit tests to run on your Joomla! installation, perform the following steps:
* Create an instance of your Joomla! installation
* In the root checkout (or export) the latest version of the unit test code from SVN ''"/testing/branches/2007-12-17"'' to your installation base. This will create a ''"/unittest"'' (sub-folder under your joomla installation).
* Create a ''"TestConfiguration.php"'' file. You can copy a the file from ''"TestConfiguration-dist.php"'' that is part of the package you just have checked out.
* Run the unit test from the command using the following command:

php runtests.php

The unit test will the run, and the results are rendered.

== Trouble shooting ==

The provided configurations should work out of the box. We have seen problems with it (currently the cause is unknown). If you get an error like blow, the solution is pretty easy.

file=/var/www/unittest/runtests.php
posn=17
base=runtests.php
/var/www
JPATH_BASE does not point to a valid Joomla! installation:
JPATH_BASE = /var/www
Please modify your copy of "TestConfiguration.php"

Modify the ''"TestConfiguration.php"'' file and change the definition of the JPATH_BASE so it points to the path of you Joomla! installation, in the example below the Joomla! installation is installed at "''/var/www/update''".

define('JPATH_BASE', '/var/www/update');

[[Category:Development]]

Unit Testing

2008-05-23T16:28:16Z

Instance: Make the branch location more obvious.

{{cookiejar}}
== Unit Testing ==
Unit testing is an essential part of a good Quality Control program.
For a good general discussion of unit testing, visit the [http://en.wikipedia.org/wiki/Unit_test Wikipedia article].

=== Unit Testing in Open Source ===
Open source projects, with multiple developers working in parallel around the world, can greatly benefit from unit testing. The main benefits are:
* Unit tests help highlight cases where seemingly minor changes cause unexpected breakage.
* Unit tests help clearly specify how a class should behave.
* Unit tests can expose design flaws very early in development.
* Unit tests make great examples. They are a great place for developers to learn how to use the code.

=== The Testing Hierarchy: Unit, Subsystem, Integrated ===
Software testing systems usually run through a spectrum from "pure" unit tests through to fully integrated systems tests. We've described low level unit tests above. Integrated testing typically involves some sort of script that simulates user actions and then verifies that the result matches what's expected. This sort of "end to end" test verifies that all parts of the system are working correctly.

It's unfortunate that there is no clear nomenclature to describe all the intermediate stages of testing. The next stage beyond testing a single unit of code is subsystem testing. A subsystem test verifies that two or more units of code are interacting correctly to produce the desired result. In the simplest case, a subsystem test can be created simply by replacing mock objects with real objects and running unit tests on the top level module. In practise, this tends to not work as well as expected, because the original unit test data wasn't designed for a subsystem test, or because the nature of the test cases needs to be changed in order to fully test the subsystem. After all there is little point in simply repeating the unit test cases; the objective of a subsystem test should be to test boundary conditions and special cases that would be difficult to duplicate in unit tests.

Once a subsystem has been tested, it can be integrated into a larger system, which is still a subset of the whole product. Tests can be written for larger and larger subsystems, but at each stage the complexity of the tests increases. At some point, the effort required to hand craft tests exceeds the benefits of running them. This is where integrated testing comes in.

Integrated testing involves recording a user's interaction with the system into a script that can be replayed. The testing framework then compares the system's response with the expected response and passes or fails the test. The PHPUnit testing framework that we use has the ability to work with Selenium, a browser based test automation tool.

==== Test Objects ====
The purpose of unit tests is to isolate a module of code. A test that tests only one thing provides better information than a test that involves several object interactions. But how do we isolate an object from its dependencies? By writing stub classes. [http://xunitpatterns.com/Mocks,%20Fakes,%20Stubs%20and%20Dummies.html xUnit Patterns] defines a the hierarchy of dummy classes, ranging from simple to complex:
* Dummy - Defines attributes and methods of a dummy class (not particularly useful in PHP).
* Fake - Provides canned responses to method calls and fixed attribute values. Good for speed.
* Stub - Allows the test to define responses to method calls (return values, exceptions) to simulate the dependent object.
* Spy - A Fake or Stub that records method calls and parameters for later analysis.
* Mock - A Fake or Stub with a set of expectations -- method calls and parameters -- that are automatically verified for correctness.

=== Unit Testing in Joomla! ===
Unit testing capabilities in Joomla are still at an early stage. The intention is to define more standards for developing tests, and then to expand the scope of available tests

The SVN repository contains code under the /testing path. /testing/trunk contains code based on the SimpleTest framework. In early December 2007, the development team elected to move to the [http://www.phpunit.de PHPUnit] framework.

Work on using PHPUnit has been done in '''/testing/branches/2007-12-17'''. Some new tests have been added, many old tests from the SimpleTest days are completely broken.

At this point, PHPUnit based tests only run in a command line environment.

==== The Unit Test Team ====
If you can commit to the Joomla code base, then you should consider yourself part of the unit test team!

Writing tests concurrently with code (or even before) is a good way to not only save development time, but a great tool for defending against regressions. Writing tests early in the development cycle also helps identify and resolve design issues sooner, which reduces refactoring.

If you want to get started on unit testing, get in touch with Alan Langford (instance) or Ray Tsai (mihu). Either of us will be happy to help out.
==== Current Work ====
* There is no longer any need to patch the main code to enable unit tests.
* Basic techniques for mock objects are defined.
* Strategies for dealing with local configuration is not yet complete, but there is a plan.
* Files of the form class-sequence-type-test.php, for example JObject-0000-class-test.php use PHPUnit.
* The JDate tests present a good example of a data-driven test, but they won't run on the current 1.5 code base (there are some proposed API changes as a result of unit test development).
* Previously functional tests, such as JFTP, haven't been moved to the PHPUnit environment yet.

==== Writing Unit Tests ====
At risk of stating the obvious, in the "purest" case the purpose of a unit test is to ''isolate a unit of code from its environment and to test the operation of that code''.

This isolation is usually achieved by writing dummy classes that emulate the code unit's environment. These dummy objects can be passive, by simply simulating the environment, or they can be more active, keeping track of how they are being used by the test unit and reporting any variations from the expected behaviour. See [[Unit_Testing_Mock_Objects|Mock Objects in Joomla]] for a detailed example.

An interesting aspect of writing tests is that they become ''de facto'' detailed technical specifications of the interfaces between units of code. The fact that these specifications can be verified in an automated way makes them a superb resource when refactoring code.

The test code has a few templates designed to kick-start a test. They are:

/unittest/sample-datatest-php.txt
/unittest/sample-simpletest.php.txt

Here are some example tests: [[Unit_Testing_--_a_Simple_Example|Simple Example]], [[Unit_Testing_--_Data_Driven_Example|Data Driven Example]], [[Unit_Testing_--_Plugin_Example|Plugin Example]].

==== Running Unit Tests ====
Test files follow the form class-sequence-type-test.php, for example JObject-0000-class-test.php. For tests that are not class based, the first element refers to the object being tested. An example of this is the e-mail cloaking plugin test, which is called emailcloak-0000-mode1-test.php.

Joomla unit tests use a customized test "runner". Every test directory should have a "runtests.php" file. Runtests has a few options, mostly to allow the selection of specific tests. The command line options are:

--class-filter ''regex''

e.g. --class-filter /JDate/ Selects only tests that have a class part that matches the regular expression.

--debug

Turns on additional debugging output.

--help

Prints information on options and exits.

--sequence-filter ''regex''

Selects only tests that have a sequence part that matches the regular expression.

--test-filter ''regex''

Selects only tests that have a test part that matches the regular expression.

'''TODO:''' Expand command line parsing to add other features of the PHPUnit framework, such as output formats, code metrics reports, etc.

== How to get it running ==

Before you start make sure you have installed PHPUnit and of course PHP (5!) properly...

To get the unit tests to run on your Joomla! installation, perform the following steps:
* Create an instance of your Joomla! installation
* In the root checkout (or export) the latest version of the unit test code from SVN ''/testing/branches/2007-12-17'' to your installation base. This will create a ''"/unittest"'' (sub-folder under your joomla installation).
* Create a ''"TestConfiguration.php"'' file. You can copy a the file from ''"TestConfiguration-dist.php"'' that is part of the package you just have checked out.
* Run the unit test from the command using the following command:

php runtests.php

The unit test will the run, and the results are rendered.

== Trouble shooting ==

The provided configurations should work out of the box. We have seen problems with it (currently the cause is unknown). If you get an error like blow, the solution is pretty easy.

file=/var/www/unittest/runtests.php
posn=17
base=runtests.php
/var/www
JPATH_BASE does not point to a valid Joomla! installation:
JPATH_BASE = /var/www
Please modify your copy of "TestConfiguration.php"

Modify the ''"TestConfiguration.php"'' file and change the definition of the JPATH_BASE so it points to the path of you Joomla! installation, in the example below the Joomla! installation is installed at "''/var/www/update''".

define('JPATH_BASE', '/var/www/update');

[[Category:Development]]

Unit Testing

2008-05-13T11:50:32Z

Instance: A little reorganization; new information on dummy classes.

== Unit Testing ==
Unit testing is an essential part of a good Quality Control program.
For a good general discussion of unit testing, visit the [http://en.wikipedia.org/wiki/Unit_test Wikipedia article].

=== Unit Testing in Open Source ===
Open source projects, with multiple developers working in parallel around the world, can greatly benefit from unit testing. The main benefits are:
* Unit tests help highlight cases where seemingly minor changes cause unexpected breakage.
* Unit tests help clearly specify how a class should behave.
* Unit tests can expose design flaws very early in development.
* Unit tests make great examples. They are a great place for developers to learn how to use the code.

=== The Testing Hierarchy: Unit, Subsystem, Integrated ===
Software testing systems usually run through a spectrum from "pure" unit tests through to fully integrated systems tests. We've described low level unit tests above. Integrated testing typically involves some sort of script that simulates user actions and then verifies that the result matches what's expected. This sort of "end to end" test verifies that all parts of the system are working correctly.

It's unfortunate that there is no clear nomenclature to describe all the intermediate stages of testing. The next stage beyond testing a single unit of code is subsystem testing. A subsystem test verifies that two or more units of code are interacting correctly to produce the desired result. In the simplest case, a subsystem test can be created simply by replacing mock objects with real objects and running unit tests on the top level module. In practise, this tends to not work as well as expected, because the original unit test data wasn't designed for a subsystem test, or because the nature of the test cases needs to be changed in order to fully test the subsystem. After all there is little point in simply repeating the unit test cases; the objective of a subsystem test should be to test boundary conditions and special cases that would be difficult to duplicate in unit tests.

Once a subsystem has been tested, it can be integrated into a larger system, which is still a subset of the whole product. Tests can be written for larger and larger subsystems, but at each stage the complexity of the tests increases. At some point, the effort required to hand craft tests exceeds the benefits of running them. This is where integrated testing comes in.

Integrated testing involves recording a user's interaction with the system into a script that can be replayed. The testing framework then compares the system's response with the expected response and passes or fails the test. The PHPUnit testing framework that we use has the ability to work with Selenium, a browser based test automation tool.

==== Test Objects ====
The purpose of unit tests is to isolate a module of code. A test that tests only one thing provides better information than a test that involves several object interactions. But how do we isolate an object from its dependencies? By writing stub classes. [http://xunitpatterns.com/Mocks,%20Fakes,%20Stubs%20and%20Dummies.html xUnit Patterns] defines a the hierarchy of dummy classes, ranging from simple to complex:
* Dummy - Defines attributes and methods of a dummy class (not particularly useful in PHP).
* Fake - Provides canned responses to method calls and fixed attribute values. Good for speed.
* Stub - Allows the test to define responses to method calls (return values, exceptions) to simulate the dependent object.
* Spy - A Fake or Stub that records method calls and parameters for later analysis.
* Mock - A Fake or Stub with a set of expectations -- method calls and parameters -- that are automatically verified for correctness.

=== Unit Testing in Joomla! ===
Unit testing capabilities in Joomla are still at an early stage. The intention is to define more standards for developing tests, and then to expand the scope of available tests

The SVN repository contains code under the /testing path. /testing/trunk contains code based on the SimpleTest framework. In early December 2007, the development team elected to move to the [http://www.phpunit.de PHPUnit] framework.

Work on using PHPUnit has been done in /testing/branches/2007-12-17. Some new tests have been added, many old tests from the SimpleTest days are completely broken.

At this point, PHPUnit based tests only run in a command line environment.

==== The Unit Test Team ====
If you can commit to the Joomla code base, then you should consider yourself part of the unit test team!

Writing tests concurrently with code (or even before) is a good way to not only save development time, but a great tool for defending against regressions. Writing tests early in the development cycle also helps identify and resolve design issues sooner, which reduces refactoring.

If you want to get started on unit testing, get in touch with Alan Langford (instance) or Ray Tsai (mihu). Either of us will be happy to help out.
==== Current Work ====
* There is no longer any need to patch the main code to enable unit tests.
* Basic techniques for mock objects are defined.
* Strategies for dealing with local configuration is not yet complete, but there is a plan.
* Files of the form class-sequence-type-test.php, for example JObject-0000-class-test.php use PHPUnit.
* The JDate tests present a good example of a data-driven test, but they won't run on the current 1.5 code base (there are some proposed API changes as a result of unit test development).
* Previously functional tests, such as JFTP, haven't been moved to the PHPUnit environment yet.

==== Writing Unit Tests ====
At risk of stating the obvious, in the "purest" case the purpose of a unit test is to ''isolate a unit of code from its environment and to test the operation of that code''.

This isolation is usually achieved by writing dummy classes that emulate the code unit's environment. These dummy objects can be passive, by simply simulating the environment, or they can be more active, keeping track of how they are being used by the test unit and reporting any variations from the expected behaviour. See [[Unit_Testing_Mock_Objects|Mock Objects in Joomla]] for a detailed example.

An interesting aspect of writing tests is that they become ''de facto'' detailed technical specifications of the interfaces between units of code. The fact that these specifications can be verified in an automated way makes them a superb resource when refactoring code.

The test code has a few templates designed to kick-start a test. They are:

/unittest/sample-datatest-php.txt
/unittest/sample-simpletest.php.txt

Here are some example tests: [[Unit_Testing_--_a_Simple_Example|Simple Example]], [[Unit_Testing_--_Data_Driven_Example|Data Driven Example]], [[Unit_Testing_--_Plugin_Example|Plugin Example]].

==== Running Unit Tests ====
Test files follow the form class-sequence-type-test.php, for example JObject-0000-class-test.php. For tests that are not class based, the first element refers to the object being tested. An example of this is the e-mail cloaking plugin test, which is called emailcloak-0000-mode1-test.php.

Joomla unit tests use a customized test "runner". Every test directory should have a "runtests.php" file. Runtests has a few options, mostly to allow the selection of specific tests. The command line options are:

--class-filter ''regex''

e.g. --class-filter /JDate/ Selects only tests that have a class part that matches the regular expression.

--debug

Turns on additional debugging output.

--help

Prints information on options and exits.

--sequence-filter ''regex''

Selects only tests that have a sequence part that matches the regular expression.

--test-filter ''regex''

Selects only tests that have a test part that matches the regular expression.

'''TODO:''' Expand command line parsing to add other features of the PHPUnit framework, such as output formats, code metrics reports, etc.

== How to get it running ==

Before you start make sure you have installed PHPUnit and of course PHP (5!) properly...

To get the unit tests to run on your Joomla! installation, perform the following steps:
* Create an instance of your Joomla! installation
* In the root checkout (or export) the latest version of the unit test code in ''"/unittest"'' (sub-folder under your joomla installation).
* Create a ''"TestConfiguration.php"'' file. You can copy a the file from ''"TestConfiguration-dist.php"'' that is part of the package you just have checked out.
* Run the unit test from the command using the following command:

php runtests.php

The unit test will the run, and the results are rendered.

== Trouble shooting ==

The provided configurations should work out of the box. We have seen problems with it (currently the cause is unknown). If you get an error like blow, the solution is pretty easy.

file=/var/www/unittest/runtests.php
posn=17
base=runtests.php
/var/www
JPATH_BASE does not point to a valid Joomla! installation:
JPATH_BASE = /var/www
Please modify your copy of "TestConfiguration.php"

Modify the ''"TestConfiguration.php"'' file and change the definition of the JPATH_BASE so it points to the path of you Joomla! installation, in the example below the Joomla! installation is installed at "''/var/www/update''".

define('JPATH_BASE', '/var/www/update');

[[Category:Development]]

Unit Testing

2008-05-13T11:26:29Z

Instance:

== Unit Testing ==
Unit testing is an essential part of a good Quality Control program.
For a good general discussion of unit testing, visit the [http://en.wikipedia.org/wiki/Unit_test Wikipedia article].

=== Unit Testing in Open Source ===
Open source projects, with multiple developers working in parallel around the world, can greatly benefit from unit testing. The main benefits are:
* Unit tests help highlight cases where seemingly minor changes cause unexpected breakage.
* Unit tests help clearly specify how a class should behave.
* Unit tests can expose design flaws very early in development.
* Unit tests make great examples. They are a great place for developers to learn how to use the code.

=== The Testing Hierarchy: Unit, Subsystem, Integrated ===
Software testing systems usually run through a spectrum from "pure" unit tests through to fully integrated systems tests. We've described low level unit tests above. Integrated testing typically involves some sort of script that simulates user actions and then verifies that the result matches what's expected. This sort of "end to end" test verifies that all parts of the system are working correctly.

It's unfortunate that there is no clear nomenclature to describe all the intermediate stages of testing. The next stage beyond testing a single unit of code is subsystem testing. A subsystem test verifies that two or more units of code are interacting correctly to produce the desired result. In the simplest case, a subsystem test can be created simply by replacing mock objects with real objects and running unit tests on the top level module. In practise, this tends to not work as well as expected, because the original unit test data wasn't designed for a subsystem test, or because the nature of the test cases needs to be changed in order to fully test the subsystem. After all there is little point in simply repeating the unit test cases; the objective of a subsystem test should be to test boundary conditions and special cases that would be difficult to duplicate in unit tests.

Once a subsystem has been tested, it can be integrated into a larger system, which is still a subset of the whole product. Tests can be written for larger and larger subsystems, but at each stage the complexity of the tests increases. At some point, the effort required to hand craft tests exceeds the benefits of running them. This is where integrated testing comes in.

Integrated testing involves recording a user's interaction with the system into a script that can be replayed. The testing framework then compares the system's response with the expected response and passes or fails the test. The PHPUnit testing framework that we use has the ability to work with Selenium, a browser based test automation tool.

==== Test Objects ====
The purpose of unit tests is to isolate a module of code. A test that tests only one thing provides better information than a test that involves several object interactions. But how do we isolate an object from its dependencies? By writing stub classes. [http://xunitpatterns.com/Mocks,%20Fakes,%20Stubs%20and%20Dummies.html xUnit Patterns] defines a the hierarchy of dummy classes, ranging from simple to complex:
* Dummy - Defines attributes and methods of a dummy class (not particularly useful in PHP).
* Fake - Provides canned responses to method calls and fixed attribute values. Good for speed.
* Stub - Allows the test to define responses to method calls (return values, exceptions) to simulate the dependent object.
* Spy - A Fake or Stub that records method calls and parameters for later analysis.
* Mock - A Fake or Stub with a set of expectations -- method calls and parameters -- that are automatically verified for correctness.

=== Unit Testing in Joomla! ===
Unit testing capabilities in Joomla are still at an early stage. The intention is to define more standards for developing tests, and then to expand the scope of available tests

The SVN repository contains code under the /testing path. /testing/trunk contains code based on the SimpleTest framework. In early December 2007, the development team elected to move to the [http://www.phpunit.de PHPUnit] framework.

Work on using PHPUnit has been done in /testing/branches/2007-12-17. Some new tests have been added, many old tests from the SimpleTest days are completely broken.

At this point, PHPUnit based tests only run in a command line environment.

==== The Unit Test Team ====
If you can commit to the Joomla code base, then you should consider yourself part of the unit test team!

Writing tests concurrently with code (or even before) is a good way to not only save development time, but a great tool for defending against regressions. Writing tests early in the development cycle also helps identify and resolve design issues sooner, which reduces refactoring.

If you want to get started on unit testing, get in touch with Alan Langford (instance) or Ray Tsai (mihu). Either of us will be happy to help out.
==== Current Work ====
* There is no longer any need to patch the main code to enable unit tests.
* Basic techniques for mock objects are defined.
* Strategies for dealing with local configuration is not yet complete, but there is a plan.
* Files of the form class-sequence-type-test.php, for example JObject-0000-class-test.php use PHPUnit.
* The JDate tests present a good example of a data-driven test, but they won't run on the current 1.5 code base (there are some proposed API changes as a result of unit test development).
* Previously functional tests, such as JFTP, haven't been moved to the PHPUnit environment yet.

==== Running Unit Tests ====
Test files follow the form class-sequence-type-test.php, for example JObject-0000-class-test.php. For tests that are not class based, the first element refers to the object being tested. An example of this is the e-mail cloaking plugin test, which is called emailcloak-0000-mode1-test.php.

Joomla unit tests use a customized test "runner". Every test directory should have a "runtests.php" file. Runtests has a few options, mostly to allow the selection of specific tests. The command line options are:

--class-filter ''regex''

e.g. --class-filter /JDate/ Selects only tests that have a class part that matches the regular expression.

--debug

Turns on additional debugging output.

--help

Prints information on options and exits.

--sequence-filter ''regex''

Selects only tests that have a sequence part that matches the regular expression.

--test-filter ''regex''

Selects only tests that have a test part that matches the regular expression.

'''TODO:''' Expand command line parsing to add other features of the PHPUnit framework, such as output formats, code metrics reports, etc.

==== Writing Unit Tests ====
At risk of stating the obvious, in the "purest" case the purpose of a unit test is to ''isolate a unit of code from its environment and to test the operation of that code''.

This isolation is usually achieved by writing simple stubs that emulate the code unit's environment. These stubs are known as "Mock Objects". Mock objects can be passive, by simply simulating the environment, or they can be more active, keeping track of how they are being used by the test unit and reporting any variations from the expected behaviour.

An interesting aspect of writing tests is that they become ''de facto'' detailed technical specifications of the interfaces between units of code. The fact that these specifications can be verified in an automated way makes them a superb resource when refactoring code.

The test code has a few templates designed to kick-start a test. They are:

/unittest/sample-datatest-php.txt
/unittest/sample-simpletest.php.txt

Here are some example tests: [[Unit_Testing_--_a_Simple_Example|Simple Example]], [[Unit_Testing_--_Data_Driven_Example|Data Driven Example]], [[Unit_Testing_--_Plugin_Example|Plugin Example]].

== How to get it running ==

Before you start make sure you have installed PHPUnit and of course PHP (5!) properly...

To get the unit tests to run on your Joomla! installation, perform the following steps:
* Create an instance of your Joomla! installation
* In the root checkout (or export) the latest version of the unit test code in ''"/unittest"'' (sub-folder under your joomla installation).
* Create a ''"TestConfiguration.php"'' file. You can copy a the file from ''"TestConfiguration-dist.php"'' that is part of the package you just have checked out.
* Run the unit test from the command using the following command:

php runtests.php

The unit test will the run, and the results are rendered.

== Trouble shooting ==

The provided configurations should work out of the box. We have seen problems with it (currently the cause is unknown). If you get an error like blow, the solution is pretty easy.

file=/var/www/unittest/runtests.php
posn=17
base=runtests.php
/var/www
JPATH_BASE does not point to a valid Joomla! installation:
JPATH_BASE = /var/www
Please modify your copy of "TestConfiguration.php"

Modify the ''"TestConfiguration.php"'' file and change the definition of the JPATH_BASE so it points to the path of you Joomla! installation, in the example below the Joomla! installation is installed at "''/var/www/update''".

define('JPATH_BASE', '/var/www/update');

[[Category:Development]]

Unit Testing

2008-05-02T11:56:30Z

Instance: Add unit test team.

== Unit Testing ==
Unit testing is an essential part of a good Quality Control program.
For a good general discussion of unit testing, visit the [http://en.wikipedia.org/wiki/Unit_test Wikipedia article].

=== Unit Testing in Open Source ===
Open source projects, with multiple developers working in parallel around the world, can greatly benefit from unit testing. The main benefits are:
* Unit tests help highlight cases where seemingly minor changes cause unexpected breakage.
* Unit tests help clearly specify how a class should behave.
* Unit tests can expose design flaws very early in development.
* Unit tests make great examples. They are a great place for developers to learn how to use the code.

=== Unit Testing in Joomla! ===
Unit testing capabilities in Joomla are still at an early stage. The intention is to define more standards for developing tests, and then to expand the scope of available tests

The SVN repository contains code under the /testing path. /testing/trunk contains code based on the SimpleTest framework. In early December 2007, the development team elected to move to the [http://www.phpunit.de PHPUnit] framework.

Work on using PHPUnit has been done in /testing/branches/2007-12-17. Some new tests have been added, many old tests from the SimpleTest days are completely broken.

At this point, PHPUnit based tests only run in a command line environment.

==== The Unit Test Team ====
If you can commit to the Joomla code base, then you should consider yourself part of the unit test team!

Writing tests concurrently with code (or even before) is a good way to not only save development time, but a great tool for defending against regressions. Writing tests early in the development cycle also helps identify and resolve design issues sooner, which reduces refactoring.

If you want to get started on unit testing, get in touch with Alan Langford (instance) or Ray Tsai (mihu). Either of us will be happy to help out.
==== Current Work ====
* There is no longer any need to patch the main code to enable unit tests.
* Basic techniques for mock objects are defined.
* Strategies for dealing with local configuration is not yet complete, but there is a plan.
* Files of the form class-sequence-type-test.php, for example JObject-0000-class-test.php use PHPUnit.
* The JDate tests present a good example of a data-driven test, but they won't run on the current 1.5 code base (there are some proposed API changes as a result of unit test development).
* Previously functional tests, such as JFTP, haven't been moved to the PHPUnit environment yet.

==== Running Unit Tests ====
Test files follow the form class-sequence-type-test.php, for example JObject-0000-class-test.php. For tests that are not class based, the first element refers to the object being tested. An example of this is the e-mail cloaking plugin test, which is called emailcloak-0000-mode1-test.php.

Joomla unit tests use a customized test "runner". Every test directory should have a "runtests.php" file. Runtests has a few options, mostly to allow the selection of specific tests. The command line options are:

--class-filter ''regex''

e.g. --class-filter /JDate/ Selects only tests that have a class part that matches the regular expression.

--debug

Turns on additional debugging output.

--help

Prints information on options and exits.

--sequence-filter ''regex''

Selects only tests that have a sequence part that matches the regular expression.

--test-filter ''regex''

Selects only tests that have a test part that matches the regular expression.

'''TODO:''' Expand command line parsing to add other features of the PHPUnit framework, such as output formats, code metrics reports, etc.

==== Writing Unit Tests ====
At risk of stating the obvious, in the "purest" case the purpose of a unit test is to ''isolate a unit of code from its environment and to test the operation of that code''.

This isolation is usually achieved by writing simple stubs that emulate the code unit's environment. These stubs are known as "Mock Objects". Mock objects can be passive, by simply simulating the environment, or they can be more active, keeping track of how they are being used by the test unit and reporting any variations from the expected behaviour.

An interesting aspect of writing tests is that they become ''de facto'' detailed technical specifications of the interfaces between units of code. The fact that these specifications can be verified in an automated way makes them a superb resource when refactoring code.

The test code has a few templates designed to kick-start a test. They are:

/unittest/sample-datatest-php.txt
/unittest/sample-simpletest.php.txt

Here are some example tests: [[Unit_Testing_--_a_Simple_Example|Simple Example]], [[Unit_Testing_--_Data_Driven_Example|Data Driven Example]], [[Unit_Testing_--_Plugin_Example|Plugin Example]].

=== The Testing Hierarchy: Unit, Subsystem, Integrated ===
Software testing systems usually run through a spectrum from "pure" unit tests through to fully integrated systems tests. We've described low level unit tests above. Integrated testing typically involves some sort of script that simulates user actions and then verifies that the result matches what's expected. This sort of "end to end" test verifies that all parts of the system are working correctly.

It's unfortunate that there is no clear nomenclature to describe all the intermediate stages of testing. The next stage beyond testing a single unit of code is subsystem testing. A subsystem test verifies that two or more units of code are interacting correctly to produce the desired result. In the simplest case, a subsystem test can be created simply by replacing mock objects with real objects and running unit tests on the top level module. In practise, this tends to not work as well as expected, because the original unit test data wasn't designed for a subsystem test, or because the nature of the test cases needs to be changed in order to fully test the subsystem. After all there is little point in simply repeating the unit test cases; the objective of a subsystem test should be to test boundary conditions and special cases that would be difficult to duplicate in unit tests.

Once a subsystem has been tested, it can be integrated into a larger system, which is still a subset of the whole product. Tests can be written for larger and larger subsystems, but at each stage the complexity of the tests increases. At some point, the effort required to hand craft tests exceeds the benefits of running them. This is where integrated testing comes in.

Integrated testing involves recording a user's interaction with the system into a script that can be replayed. The testing framework then compares the system's response with the expected response and passes or fails the test. The PHPUnit testing framework that we use has the ability to work with Selenium, a browser based test automation tool.

== How to get it running ==

Before you start make sure you have installed PHPUnit and of course PHP (5!) properly...

To get the unit tests to run on your Joomla! installation, perform the following steps:
* Create an instance of your Joomla! installation
* In the root checkout (or export) the latest version of the unit test code in ''"/unittest"'' (sub-folder under your joomla installation).
* Create a ''"TestConfiguration.php"'' file. You can copy a the file from ''"TestConfiguration-dist.php"'' that is part of the package you just have checked out.
* Run the unit test from the command using the following command:

php runtests.php

The unit test will the run, and the results are rendered.

== Trouble shooting ==

The provided configurations should work out of the box. We have seen problems with it (currently the cause is unknown). If you get an error like blow, the solution is pretty easy.

file=/var/www/unittest/runtests.php
posn=17
base=runtests.php
/var/www
JPATH_BASE does not point to a valid Joomla! installation:
JPATH_BASE = /var/www
Please modify your copy of "TestConfiguration.php"

Modify the ''"TestConfiguration.php"'' file and change the definition of the JPATH_BASE so it points to the path of you Joomla! installation, in the example below the Joomla! installation is installed at "''/var/www/update''".

define('JPATH_BASE', '/var/www/update');

[[Category:Development]]

Archived:Code 05010

2008-03-20T13:40:12Z

Instance:

==Title==
Create Web-Based Unit Test Runner

== One line summary ==
Write a test runner that makes it easy to run unit tests from a web browser.

== Description ==
The existing unit test framework is based on running PHP from the command line. While this is essential for integrating testing into the build and release process, it's a barrier to using tests during development.

This project involves adapting web-based test runners provided by PHPUnit to support the "Joomla!" testing environment.

== Skills needed ==

== Difficulty ==

== Work Product ==

== Licensing ==
All code must be created using the [[http://www.gnu.org/licenses/old-licenses/gpl-2.0.html#SEC4 GNU General Public License version]]

Documentation written for this task must be made available under the Joomla! Electronic Documentation License.

== Possible mentor ==

Return to [[Google Summer of Code 2008]]

[[Category:Google Summer of Code 2008]]

Archived:Code 05010

2008-03-20T13:35:34Z

Instance: New page: ==Title== Create Web-Based Unit Test Runner == One line summary == Write a test runner that makes it easy to run unit tests from a web browser. == Description == The existing unit test f...

==Title==
Create Web-Based Unit Test Runner

== One line summary ==
Write a test runner that makes it easy to run unit tests from a web browser.

== Description ==
The existing unit test framework is based on running PHP from the command line. While this is essential for integrating testing into the build and release process, it's a barrier to using tests during development.

== Skills needed ==

== Difficulty ==

== Work Product ==

== Licensing ==
All code must be created using the [[http://www.gnu.org/licenses/old-licenses/gpl-2.0.html#SEC4 GNU General Public License version]]

Documentation written for this task must be made available under the Joomla! Electronic Documentation License.

== Possible mentor ==

Return to [[Google Summer of Code 2008]]

[[Category:Google Summer of Code 2008]]

Archived:ProjectTemplate

2008-03-20T12:23:48Z

Instance:

==Title==

== One line summary ==

== Description ==

== Skills needed ==

== Difficulty ==

== Work Product ==

== Licensing ==
All code must be created using the [[http://www.gnu.org/licenses/old-licenses/gpl-2.0.html#SEC4 GNU General Public License version]]

Documentation written for this task must be made available under the Joomla! Electronic Documentation License.

== Possible mentor ==

Return to [[Google Summer of Code 2008]]

[[Category:Google Summer of Code 2008]]

Archived:Summer of Code 2008 Project Ideas

2008-03-20T12:20:52Z

Instance: /* Unit testing */

This page contains a list of project proposal ideas from the Joomla! Project (community members). The mentoring organization has written down a non-exhaustive list of project ideas to guide the students into selecting a suitable idea.

This list will be updated on a regular basis. Feel free to post any other ideas into into the [http://forum.joomla.org/viewforum.php?f=525 Google Summer of Code 2008 Forum Area] or use the [http://groups.google.com/group/joomla-summer-of-code-2008 Google Summer of Code mail list] (don't forget to register in the forum and list before you post).

We would kindly ask you not to add new projects here unless you are one of the project mentors. Please discuss these on the list/forum mentioned above.

[[ProjectTemplate]]

== Components ==

[[Code 01000]] Article Versioning
[[Code 01010]] Multi-site implementation
[[Code 01020]] Whiteboard component
[[Code 01030]] Image Manager improvements
[[Code 01040]] Create a forms component/extension
[[Code 01050]] Export and Import Tools
[[Code 01060]] Searching Improvements
[[Code 01070]] Tagging for various content-types
[[Code 01080]] User Registration and Management

== Libraries/Framework related ==

[[Code 02000]] MultiDB support
[[Code 02010]] Create an PHP API for using mootools.

== Modules ==

[[Code 03000]]
[[Code 03010]]

== Templates ==

[[Code 04000]] Deploy Triplify for Joomla! v 1.5, Semantic Web
[[Code 04010]] Semantic Web: Linked Data

== Unit testing ==

[[Code 05000]] Improve Unit Test Coverage
[[Code 05010]] Create Web-Based Unit Test Runner

== Plugins ==

[[Code 06000]] Comments; threaded and not threaded, support for various content-types, not just articles
[[Code 06010]] SEF URL Plugins
[[Code 06020]] Create a plugin for TinyMCE that makes it easy for end users to choose which add-ons they want without hacking the core

== Inter-Project Projects ==

[[Code 08001]] Civicrm integration

== Miscellaneous ==

[[Code 07000]] Multi-lingual support
[[Code 07010]] Error Page Handling
[[Code 07020]] Data Portability
[[Code 07030]] Facebook Integration
[[Code 07040]] Create an download extension for Joomla!
[[Code 07050]] Create an extension to register Joomla! tasks/projects

[[Category:Google Summer of Code 2008]]

Archived:Code 05000

2008-03-20T12:00:39Z

Instance: New page: == Title == Improve Unit Test Coverage == One Line Summary == Most of the code in "Joomla!" doesn't have supporting unit tests, this project aims to address that. == Description == The v...

== Title ==
Improve Unit Test Coverage

== One Line Summary ==
Most of the code in "Joomla!" doesn't have supporting unit tests, this project aims to address that.

== Description ==
The value of unit tests increase exponentially with the amount of code that is covered by tests. This project involves identifying code that doesn't have existing unit tests and writing them.

== Skills needed ==

== Difficulty ==

== Work Product ==

== Licensing ==
All code must be created using the [[http://www.gnu.org/licenses/old-licenses/gpl-2.0.html#SEC4 GNU General Public License version]]

Documentation written for this task must be made available under the Joomla! Electronic Documentation License.

== Possible mentor ==

Return to [[Google Summer of Code 2008]]

[[Category:Google Summer of Code 2008]]

Unit Testing

2008-03-05T12:35:13Z

Instance: /* Unit Testing */

Unit Testing

2008-03-05T12:31:36Z

Instance: /* The Testing Hierarchy: Unit, Subsystem, Integrated */

== Unit Testing ==
Unit testing is an essential part of a good Quality Control program.
For more information, visit the [http://en.wikipedia.org/wiki/Unit_test Wikipedia article on unit testing].

=== Unit Testing in Open Source ===
Open source projects, with multiple developers working in parallel around the world, can greatly benefit from unit testing. The main benefits are:
* Unit tests help highlight cases where seemingly minor changes cause unexpected breakage.
* Unit tests help clearly specify how a class should behave.
* Unit tests can expose design flaws very early in development.
* Unit tests make great examples. They are a great place for developers to learn how to use the code.

=== Unit Testing in Joomla! ===
Unit testing capabilities in Joomla are still at an early stage. The intention is to define more standards for developing tests, and then to expand the scope of available tests

The SVN repository contains code under the /testing path. /testing/trunk contains code based on the SimpleTest framework. In early December 2007, the development team elected to move to the [http://www.phpunit.de PHPUnit] framework.

Work on using PHPUnit has been done in /testing/branches/2007-12-17. Some new tests have been added, many old tests from the SimpleTest days are completely broken.

At this point, PHPUnit based tests only run in a command line environment.

==== Current Work ====
* There is no longer any need to patch the main code to enable unit tests.
* Basic techniques for mock objects are defined.
* Strategies for dealing with local configuration is not yet complete, but there is a plan.
* Files of the form class-sequence-type-test.php, for example JObject-0000-class-test.php use PHPUnit.
* The JDate tests present a good example of a data-driven test, but they won't run on the current 1.5 code base (there are some proposed API changes as a result of unit test development).
* Previously functional tests, such as JFTP, haven't been moved to the PHPUnit environment yet.

==== Running Unit Tests ====
Test files follow the form class-sequence-type-test.php, for example JObject-0000-class-test.php. For tests that are not class based, the first element refers to the object being tested. An example of this is the e-mail cloaking plugin test, which is called emailcloak-0000-mode1-test.php.

Joomla unit tests use a customized test "runner". Every test directory should have a "runtests.php" file. Runtests has a few options, mostly to allow the selection of specific tests. The command line options are:

--class-filter ''regex''

e.g. --class-filter /JDate/ Selects only tests that have a class part that matches the regular expression.

--debug

Turns on additional debugging output.

--help

Prints information on options and exits.

--sequence-filter ''regex''

Selects only tests that have a sequence part that matches the regular expression.

--test-filter ''regex''

Selects only tests that have a test part that matches the regular expression.

'''TODO:''' Expand command line parsing to add other features of the PHPUnit framework, such as output formats, code metrics reports, etc.

==== Writing Unit Tests ====
At risk of stating the obvious, in the "purest" case the purpose of a unit test is to ''isolate a unit of code from its environment and to test the operation of that code''.

This isolation is usually achieved by writing simple stubs that emulate the code unit's environment. These stubs are known as "Mock Objects". Mock objects can be passive, by simply simulating the environment, or they can be more active, keeping track of how they are being used by the test unit and reporting any variations from the expected behaviour.

An interesting aspect of writing tests is that they become ''de facto'' detailed technical specifications of the interfaces between units of code. The fact that these specifications can be verified in an automated way makes them a superb resource when refactoring code.

The test code has a few templates designed to kick-start a test. They are:

/unittest/sample-datatest-php.txt
/unittest/sample-simpletest.php.txt

Here are some example tests: [[Unit_Testing_--_a_Simple_Example|Simple Example]], [[Unit_Testing_--_Data_Driven_Example|Data Driven Example]], [[Unit_Testing_--_Plugin_Example|Plugin Example]].

=== The Testing Hierarchy: Unit, Subsystem, Integrated ===
Software testing systems usually run through a spectrum from "pure" unit tests through to fully integrated systems tests. We've described low level unit tests above. Integrated testing typically involves some sort of script that simulates user actions and then verifies that the result matches what's expected. This sort of "end to end" test verifies that all parts of the system are working correctly.

It's unfortunate that there is no clear nomenclature to describe all the intermediate stages of testing. The next stage beyond testing a single unit of code is subsystem testing. A subsystem test verifies that two or more units of code are interacting correctly to produce the desired result. In the simplest case, a subsystem test can be created simply by replacing mock objects with real objects and running unit tests on the top level module. In practise, this tends to not work as well as expected, because the original unit test data wasn't designed for a subsystem test, or because the nature of the test cases needs to be changed in order to fully test the subsystem. After all there is little point in simply repeating the unit test cases; the objective of a subsystem test should be to test boundary conditions and special cases that would be difficult to duplicate in unit tests.

Once a subsystem has been tested, it can be integrated into a larger system, which is still a subset of the whole product. Tests can be written for larger and larger subsystems, but at each stage the complexity of the tests increases. At some point, the effort required to hand craft tests exceeds the benefits of running them. This is where integrated testing comes in.

Integrated testing involves recording a user's interaction with the system into a script that can be replayed. The testing framework then compares the system's response with the expected response and passes or fails the test. The PHPUnit testing framework that we use has the ability to work with Selenium, a browser based test automation tool.

Unit Testing

2008-03-05T12:30:50Z

Instance:

== Unit Testing ==
Unit testing is an essential part of a good Quality Control program.
For more information, visit the [http://en.wikipedia.org/wiki/Unit_test Wikipedia article on unit testing].

=== Unit Testing in Open Source ===
Open source projects, with multiple developers working in parallel around the world, can greatly benefit from unit testing. The main benefits are:
* Unit tests help highlight cases where seemingly minor changes cause unexpected breakage.
* Unit tests help clearly specify how a class should behave.
* Unit tests can expose design flaws very early in development.
* Unit tests make great examples. They are a great place for developers to learn how to use the code.

=== Unit Testing in Joomla! ===
Unit testing capabilities in Joomla are still at an early stage. The intention is to define more standards for developing tests, and then to expand the scope of available tests

The SVN repository contains code under the /testing path. /testing/trunk contains code based on the SimpleTest framework. In early December 2007, the development team elected to move to the [http://www.phpunit.de PHPUnit] framework.

Work on using PHPUnit has been done in /testing/branches/2007-12-17. Some new tests have been added, many old tests from the SimpleTest days are completely broken.

At this point, PHPUnit based tests only run in a command line environment.

==== Current Work ====
* There is no longer any need to patch the main code to enable unit tests.
* Basic techniques for mock objects are defined.
* Strategies for dealing with local configuration is not yet complete, but there is a plan.
* Files of the form class-sequence-type-test.php, for example JObject-0000-class-test.php use PHPUnit.
* The JDate tests present a good example of a data-driven test, but they won't run on the current 1.5 code base (there are some proposed API changes as a result of unit test development).
* Previously functional tests, such as JFTP, haven't been moved to the PHPUnit environment yet.

==== Running Unit Tests ====
Test files follow the form class-sequence-type-test.php, for example JObject-0000-class-test.php. For tests that are not class based, the first element refers to the object being tested. An example of this is the e-mail cloaking plugin test, which is called emailcloak-0000-mode1-test.php.

Joomla unit tests use a customized test "runner". Every test directory should have a "runtests.php" file. Runtests has a few options, mostly to allow the selection of specific tests. The command line options are:

--class-filter ''regex''

e.g. --class-filter /JDate/ Selects only tests that have a class part that matches the regular expression.

--debug

Turns on additional debugging output.

--help

Prints information on options and exits.

--sequence-filter ''regex''

Selects only tests that have a sequence part that matches the regular expression.

--test-filter ''regex''

Selects only tests that have a test part that matches the regular expression.

'''TODO:''' Expand command line parsing to add other features of the PHPUnit framework, such as output formats, code metrics reports, etc.

==== Writing Unit Tests ====
At risk of stating the obvious, in the "purest" case the purpose of a unit test is to ''isolate a unit of code from its environment and to test the operation of that code''.

This isolation is usually achieved by writing simple stubs that emulate the code unit's environment. These stubs are known as "Mock Objects". Mock objects can be passive, by simply simulating the environment, or they can be more active, keeping track of how they are being used by the test unit and reporting any variations from the expected behaviour.

An interesting aspect of writing tests is that they become ''de facto'' detailed technical specifications of the interfaces between units of code. The fact that these specifications can be verified in an automated way makes them a superb resource when refactoring code.

The test code has a few templates designed to kick-start a test. They are:

/unittest/sample-datatest-php.txt
/unittest/sample-simpletest.php.txt

Here are some example tests: [[Unit_Testing_--_a_Simple_Example|Simple Example]], [[Unit_Testing_--_Data_Driven_Example|Data Driven Example]], [[Unit_Testing_--_Plugin_Example|Plugin Example]].

==== The Testing Hierarchy: Unit, Subsystem, Integrated ====
Software testing systems usually run through a spectrum from "pure" unit tests through to fully integrated systems tests. We've described low level unit tests above. Integrated testing typically involves some sort of script that simulates user actions and then verifies that the result matches what's expected. This sort of "end to end" test verifies that all parts of the system are working correctly.

It's unfortunate that there is no clear nomenclature to describe all the intermediate stages of testing. The next stage beyond testing a single unit of code is subsystem testing. A subsystem test verifies that two or more units of code are interacting correctly to produce the desired result. In the simplest case, a subsystem test can be created simply by replacing mock objects with real objects and running unit tests on the top level module. In practise, this tends to not work as well as expected, because the original unit test data wasn't designed for a subsystem test, or because the nature of the test cases needs to be changed in order to fully test the subsystem. After all there is little point in simply repeating the unit test cases; the objective of a subsystem test should be to test boundary conditions and special cases that would be difficult to duplicate in unit tests.

Once a subsystem has been tested, it can be integrated into a larger system, which is still a subset of the whole product. Tests can be written for larger and larger subsystems, but at each stage the complexity of the tests increases. At some point, the effort required to hand craft tests exceeds the benefits of running them. This is where integrated testing comes in.

Integrated testing involves recording a user's interaction with the system into a script that can be replayed. The testing framework then compares the system's response with the expected response and passes or fails the test. The PHPUnit testing framework that we use has the ability to work with Selenium, a browser based test automation tool.

Unit Testing Example Simple

2008-03-05T11:53:46Z

Instance: Unit Testing Example Simple moved to Unit Testing -- a Simple Example

#REDIRECT [[Unit Testing -- a Simple Example]]

Unit Testing

2008-03-04T21:26:53Z

Instance: Information on running and writign tests

Unit Testing

2008-03-04T20:29:49Z

Instance: Add running tests section

Unit Testing

2008-03-04T20:14:13Z

Instance: /* Current Work */

Unit Testing

2008-01-22T19:49:52Z

Instance: /* Unit Testing in Joomla! */

Unit Testing

2008-01-22T19:49:03Z

Instance: /* Unit Testing in Open Source */

Unit Testing

2008-01-22T19:48:23Z

Instance: Initial description of unit test as it applies to Joomla!

JDOC:Creating pages with preloaded text

2008-01-22T13:53:38Z

Instance:

<div class="messagebox">
''Please note: Some techniques recommended in this article require the use of extensions. Please use with care. The status assigned to each extension is self-assigned by the maintainer and does not represent the opinion of the MediaWiki development team.''
----
This article is based on [[Mediawiki:Manual:Creating_pages_with_preloaded_text]]
</div>
'''Preloading wikitext''' is one of many techniques for helping users create pages more quickly and for improving the quality of those pages. Instead of creating a new page from scratch, users are presented with a partially created page, and possibly instructions for filling it in.

This technique is especially useful when:
* wiki users are willing to read and write simple wikitext (sometimes an issue on intranet installations of MediaWiki)
* the wiki contains one or more categories of articles with lots of pro-forma text
* the information that needs to be collected for such articles is a mix of structured data and free form text

__TOC__

Creating pages with preloaded text is a three step process:
# Design the preload file and its supporting templates
# Create pages for the preload files and supporting templates
# Set up the trigger to load the preload file

== Designing the preload file ==
The preload file is often an article with an embedded template. For example, if you wanted one article for each customer or marketing contact, you might want to preload text that looks something like this:
<pre>

{{CustomerContact
|Number=
|BizcardImage=
|Primary phone number=
|Address=
}}
</pre>

== Naming and documenting the preload file ==
Some extensions (see [[mediawiki:Extension:Boilerplate]]) have specific expectations as to where the preloaded text should be stored. Others leave that decision entirely up to the system administrator.

Naming and documenting the preload file takes some care because preload files don't always show up on "What links here" and so are at risk for accidental deletion (no info/no links - hard to tell from an article that got created and abandoned).
For template based preload files, the following naming conventions may help avoid accidental deletion:

* place template in <code>Template:''CategoryName''</code>
* place preload file in <code>Template:''CategoryName''/Preload</code>

While documentation of regular templates is often presented on the template page itself (using noinclude tags), this is not possible for a page to be preloaded. Also categories and interlanguage links for the preload page itself are not possible without affecting the wikitext that is preloaded. The talk page has to be used for all these.

== Loading the preload file ==

Preloading can be done with a preload parameter in a URL like
{{fullurl:Joomla:Sandbox/Preloadtest|action=edit&preload=Template:Preload_demo}} which links to the edit box of a new page, preloaded with {{tim|Preload demo}}. There are also a number of extensions available to trigger your preload file, see below.

The wikitext of the source page, '''including noinclude parts and tags, but not includeonly tags''', is preloaded into the editbox if the page or section does not exist yet. If the page or section to be edited already exists then only its wikitext is loaded, the preload command is ignored.

Notes:
* Both the <noinclude> and </noinclude> tags AND their content are preloaded, which means you can't categorize the source page or include some self-documentation: it'd be dumped into the preloaded text too.
* The <includeonly> and </includeonly> tags are stripped from the source page. If you need the preloaded text to provide includeonly tags, you can use
::<CODE><include<includeonly></includeonly>only></CODE>

:in your source: since the two middle tags will be stripped, the preloaded text will end up with just the <includeonly> wanted.

Thus there is neither a complete inclusion nor a regular transclusion. See also [http://bugzilla.wikimedia.org/show_bug.cgi?id=5210 bug 5210] (since 2006-03-09).

== Extensions ==
Extensions that trigger a preload file include:

* [[Mediawiki:Extension:Inputbox]], [[Mediawiki:Extension:CreateBox]], [[Mediawiki:Extension:CreateArticle]] offer the most control over the loading process. Each of these extensions let you place a button somewhere in an article, typically in a user help page or the category page corresponding to the article. You specify the name of the preload file as part of the button definition.
* [[Mediawiki:Extension:BoilerplateSelection]] - preloaded text selected by pattern matching on article title. To set this up you create an array in [[Joomla:LocalSettings.php]] file. This array associates regular expressions with preload article names.
* [[Mediawiki:Extension:Boilerplate]] - preloaded text for all articles irrespective of name or category. The preloaded text must be stored in the MediaWiki article <code><nowiki>[[Mediawiki:MediaWiki:Boilerplate]]</nowiki></code>. It will be loaded automatically whenever an article is created.

A few extensions also handle all three steps for you:

* [[Mediawiki:Extension:Add Article to Category]] - puts an add-an-article button on each category. When an article is created using this extension it will automatically contain the wiki text for including the article in that category, i.e. <nowiki>[[Category:...]]</nowiki>

[[Category:Template documentation|preload]]
[[Category:Wiki Templates|preload]]

JDOC:Templates for chunk categorisation

2008-01-22T13:52:36Z

Instance:

On this page you will find a bunch of ''Wiki templates'' to help categorize your content according to the information provided in the article "[[Categorising a chunk]]". Unlike Joomla! templates, Wiki templates are wiki ''pages'' which can be used in other pages. They reside in their own content ''namespace'' to avoid name clashing with regular articles. In order to use such a Template, all you have to do is to enclose its name in ''curly brackets'': <nowiki>{{template name}}</nowiki>. That's it.

The list of available templates will be expanded in the future.

== Chunks ==
[[Category:Wiki Templates]]

JDOC:Local wiki templates

2008-01-22T13:51:50Z

Instance:

<p style="text-align:center;border:1px solid #ccc">[[Local wiki templates]] • [[Local wiki extensions]] • [[Local interwiki links]]</p>
MediaWiki templates should not to be confused with Joomla! templates! MediaWiki templates are "boiler-plate" items that can be included in your wiki pages by inserting a simple reference.

===Incomplete Content Notice===
Insert <nowiki>{{Content-incomplete}}</nowiki> to obtain the following notice:
{{Content-incomplete}}

===Standard License Notice===
Insert {{tl|license}} to obtain the following notice:

{{license}}

===Page In Use Notice===
Insert {{tl|inuse}} to obtain the following notice:
{{inuse}}

===Under Construction Notice===
Insert {{tl|underconstruction}} to obtain the following notice:
{{underconstruction}}

===Article Reviews===
Once you're done with editing please replace {{tl|underconstruction}} and {{tl|inuse}} with {{tl|review}}. This will add your document to the [[:Category:Under review]].
{{review}}

==Table of Contents==
You will get a table of contents box on each page by default as soon as you start making use of headings and subheadings on the page. The default table of contents box is located on the left and text does not flow around it. You can make the table of contents box float right by inserting '''{{tlp|RightTOC}}''' at the appropriate place in your page. You can also suppress the table of contents box altogether by inserting '''<nowiki>__NOTOC__</nowiki>''' at the top of the page.

==Shortcuts, Links & Navigation==
Some URLs can become utterly long, some are ugly, and some are just tedious to type over and over again. Adding categories to a page can become equally annoying.

To simplify your job try some of the following templates. Similar to the interwikis, they're true keystroke-savers:
* {{tlx|jsite|keyword}}, for example:
: <nowiki>{{jsite}}</nowiki> = {{jsite}}
: <nowiki>{{jsite|forum}}</nowiki> = {{jsite|forum}}
: <nowiki>{{jsite|ext}}</nowiki> = {{jsite|ext}}. For more see {{tl|jsite}}.
* {{tlx|jforum|keyword}}, shortcuts for the many Working Group fora, i.e.
: <nowiki>{{jforum}}</nowiki> = {{jforum}}
: <nowiki>{{jforum|doc}}</nowiki> = {{jforum|doc}}
: <nowiki>{{jforum|devdoc}}</nowiki> = {{jforum|devdoc}}. For more see {{tl|jforum}}.

: an excerpt of categorisation and [[:Category:Typing-aid templates|typing-aid templates]] coming soon! --[[User:CirTap|CirTap]] 14:52, 20 January 2008 (EST)

[[Category:Wiki Templates]]

Category:License templates

2008-01-22T13:50:37Z

Instance:

[[Category:Wiki Templates]]

Template:Catjoomla/doc

2008-01-22T13:48:48Z

Instance:

This template is a categorisation workhorse. It adds a page to several categories at once and supports supplemental text to abandon features that have been deprecated or removed from the Joomla! code base, the {{jf}}, or any of its [[Application]]s. Although it's best applied to {{jfr}} pages it's also a valuable addition in other types of Joomla! documentation.

== Usage ==
For example in articles about a concept or feature as well as in a [[:Category|Tutorial|]]:
<pre>
{{catjoomla|1.5.0}}
</pre>

Framework or feature specific:
<pre>
{{catjoomla
| since = version
| package = name
| class = name
| deprecated = version
| use = pagename
| removed = version
| remark = wiki text
}}
</pre>
<big>All <tt>version</tt> numbers MUST use the '''major.minor.release''' numbering scheme, ie. <tt>1.5.0</tt>, <tt>1.0.12</tt> etc.</big>
<br />Don't drop the ''.release'' number just because you don't know the exact version. You may look at Joomla!s CHANGELOG.php however.
If you are unsure about the exact version number a feature was introduced please ommit the <var>since</var> parameter alltogether, and ''don't'' add the unnamed 1. parameter as shown in the general syntax. This will place the document in the "unknown version" category where someone who ''does know'' can find the entry and possibly fix it.
;since (or <nowiki>{{{1}}}</nowiki>)
: Joomla! Version this feature was first introduced
;package
: Framework package name
:;class
:: Class name, can only be used if ''package'' name is given
;deprecated
: Joomla! Version the feature was deprecated
:;use
:: if ''deprecated'' is set, the page name of the replacing (new, alternative) feature, if applicable. See ''remark'' parameter.
;removed
: Joomla! Version the feature was removed (w/o adequated replacement)
;remark:
: Supplemental message, i.e. combined with ''removed''. ;This parameter may contain wiki text.
You cay "misuse" the ''remark'' parameter to apply additional categories not covered in the default set.

== Example ==
Documentation in a deprecated feature:
<nowiki>{{</nowiki>catjoomla
| since = 1.5.0
| package = Whatever
| class = JWhatever
| deprecated = 1.6.0
| use = [[JAPI:Newpackage/JWhatelse]]
}}
will assign the page to the following categories
<nowiki>Framework, Whatever, JWhatever, Joomla! 1.5.0, Joomla! 1.6.0</nowiki>
and generate this text:
Deprecated as of <nowiki>[[Framework:Joomla! 1.6.0]]</nowiki>. Please use <nowiki>[[JAPI:Newpackage/JWhatelse|]]</nowiki> instead.

<nowiki>{{</nowiki>catjoomla
| since = 1.0.6
| removed = 1.6.0
| remark = No alternative at time of writing.
}}

== Issues ==
You can't use the literal pipe character in '''any''' parameter, i.e. to rename the link. A trailing <tt>|</tt> pipe is automatically added after the '''page name''' assigned to <tt><nowiki>{{{use}}}</nowiki></tt>. You may however try the {{tlp|!}} template instead.

If <tt><nowiki>{{{use}}}</nowiki></tt> is refering to a subpage via <tt>/Pagename/</tt> (note the trailing <tt>/</tt>), the link caption might look wrong but the link itself should work (provided the target page exists). This is hopefully going to be fixed soon.

Using the '''[[Help:ParserFunctions|#titleparts:]''' parser function instead of, or in combination with, the named parameters, is should be easier to place a subpage such as "Package/Application/Classes/JApplication" into all appropriate categories with a suitable sortorder key.

'''See also:'''
* {{tlp|future}} to "flag" a feature of a future, yet unreleased version of Joomla! ... if you dare ;)
<includeonly>[[Category:Wiki Templates|{{PAGENAME}}]][[Category:Link templates|{{PAGENAME}}]]</includeonly>