Joomla! Documentation - User contributions [en]

Understanding Output Overrides

2015-04-21T05:54:57Z

Renekorss: prettified paths

{{version/tutor|1.5,2.5,3.1}}
[[Category:Development]] [[Category:Templates]] [[Category:Overrides]] [[Category:Tips and tricks 1.5]]
This was a Developer Blog post by Andrew Eddie, initially copied to the wiki with minor edits by Alan Langford.
== 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 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--and, more importantly, the power--to control output 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 Website 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 fours areas of the output of Joomla! that are able to be customised by the template designer.

Not interested in all the theory? Jump straight to the cheat sheet below.

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

=== Ancillary Customisation:Chrome ===
In addition to layouts, modules have what we call "chrome". Chrome is the style(s) 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).

Note the potential plural. A module or component can have multiple chrome styles applied to it. For example, When the global template setting "preview module positions" is enabled and the page is loaded with ?tp=1 at the end of the url the chrome "outline" is added to all modules and the component. This is in addition to their regular chrome styling. The default chrome settings can be found in the template/system/html/modules.php file and additional chrome styles may be added by adding your own modules.php file to your template.

Chrome styles are functions and are written in this manner:
<source lang="php">
/*
* foobar (outputs foo before module content and bar after)
*/
function modChrome_foobar($module, &$params, &$attribs)
{
echo '<h1>Foo</h1>';
echo $module->content;
echo '<h1>Bar</h1>';
}
</source>

Use $module->content to access the content generated by the module. You may access the module parameters and attributes by using the appropriate variables passed to this function.

=== Ancillary Customisation:Pagination ===
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:

<pre>/components/com_content/views/article/tmpl/default.php</pre>

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

<pre>/templates/rhuk_milkyway/html/com_content/article/default.php</pre>

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

<pre>/components/com_content/views/category/tmpl/blog.php</pre>

to:

<pre>/templates/rhuk_milkyway/html/com_content/category/blog.php</pre>

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:

<pre>/components/com_content/views/category/tmpl/blog_item.php</pre>

to:

<pre>/templates/rhuk_milkyway/html/com_content/category/blog_item.php</pre>

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

<pre>/modules/mod_latest_news/tmpl/default.php</pre>

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

<pre>/templates/rhuk_milkyway/html/mod_latest_news/default.php</pre>

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 referred to as "chrome". The default chrome is in the system template of the default Joomla! install:

<pre>/templates/system/html/modules.php</pre>

This file is maintained by the project so you should never modify it. You will lose your changes when you upgrade your Joomla! installation.

To create your own chrome, or module styles, 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 provides some extra chrome as an example. (It provides an example style called "slider"). This can be found in the following file:

<pre>/templates/rhuk_milkyway/html/modules.php</pre>

Creating your own chrome is easy. Let's look at 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 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:

<pre>/templates/rhuk_milkyway/html/pagination.php</pre>

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

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

== Media Files Override ==

This method allows 3rd party developers to override CSS and JS files that where inserted using the functions <code>JHtml::script()</code> or <code>JHtml::stylesheet()</code> and are stored inside the Joomla media folder.

=== Supporting Media Files Override ===

For this example we have a module called <code>mod_test</code>, this module have a CSS file installed at:

/media/mod_test/css/mystyle.css

That file should be inserted using the following functions and parameters:

JHtml::stylesheet('mod_test/mystyle.css', false, true, false);

Note that the 3rd parameter (true) is the one that makes the Joomla API to look for an override file inside your current template folder.

The override file must be placed as follow at your current template folder:

/templates/my_template/css/mod_test/mystyle.css

== Cheat Sheet ==
Using the rhuk_milkyway template as an example, here is a brief summary of the principles 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:

/modules/mod_latest_news/tmpl/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 the output generated by Joomla!.

Understanding Output Overrides

2015-04-21T05:52:20Z

Renekorss: prettified paths

{{version/tutor|1.5,2.5,3.1}}
[[Category:Development]] [[Category:Templates]] [[Category:Overrides]] [[Category:Tips and tricks 1.5]]
This was a Developer Blog post by Andrew Eddie, initially copied to the wiki with minor edits by Alan Langford.
== 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 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--and, more importantly, the power--to control output 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 Website 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 fours areas of the output of Joomla! that are able to be customised by the template designer.

Not interested in all the theory? Jump straight to the cheat sheet below.

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

=== Ancillary Customisation:Chrome ===
In addition to layouts, modules have what we call "chrome". Chrome is the style(s) 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).

Note the potential plural. A module or component can have multiple chrome styles applied to it. For example, When the global template setting "preview module positions" is enabled and the page is loaded with ?tp=1 at the end of the url the chrome "outline" is added to all modules and the component. This is in addition to their regular chrome styling. The default chrome settings can be found in the template/system/html/modules.php file and additional chrome styles may be added by adding your own modules.php file to your template.

Chrome styles are functions and are written in this manner:
<source lang="php">
/*
* foobar (outputs foo before module content and bar after)
*/
function modChrome_foobar($module, &$params, &$attribs)
{
echo '<h1>Foo</h1>';
echo $module->content;
echo '<h1>Bar</h1>';
}
</source>

Use $module->content to access the content generated by the module. You may access the module parameters and attributes by using the appropriate variables passed to this function.

=== Ancillary Customisation:Pagination ===
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:

<pre>/components/com_content/views/article/tmpl/default.php</pre>

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

<pre>/templates/rhuk_milkyway/html/com_content/article/default.php</pre>

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

<pre>/components/com_content/views/category/tmpl/blog.php</pre>

to:

<pre>/templates/rhuk_milkyway/html/com_content/category/blog.php</pre>

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

/modules/mod_latest_news/tmpl/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 referred to as "chrome". The default chrome is in the system template of the default Joomla! install:

/templates/system/html/modules.php

This file is maintained by the project so you should never modify it. You will lose your changes when you upgrade your Joomla! installation.

To create your own chrome, or module styles, 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 provides some extra chrome as an example. (It provides an example style called "slider"). This can be found in the following file:

/templates/rhuk_milkyway/html/modules.php

Creating your own chrome is easy. Let's look at 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 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_inactive

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

== Media Files Override ==

This method allows 3rd party developers to override CSS and JS files that where inserted using the functions <code>JHtml::script()</code> or <code>JHtml::stylesheet()</code> and are stored inside the Joomla media folder.

=== Supporting Media Files Override ===

For this example we have a module called <code>mod_test</code>, this module have a CSS file installed at:

/media/mod_test/css/mystyle.css

That file should be inserted using the following functions and parameters:

JHtml::stylesheet('mod_test/mystyle.css', false, true, false);

Note that the 3rd parameter (true) is the one that makes the Joomla API to look for an override file inside your current template folder.

The override file must be placed as follow at your current template folder:

/templates/my_template/css/mod_test/mystyle.css

== Cheat Sheet ==
Using the rhuk_milkyway template as an example, here is a brief summary of the principles 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:

/modules/mod_latest_news/tmpl/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 the output generated by Joomla!.

Using Content History in your Component

2015-03-20T11:04:27Z

Renekorss: added missing description to edit model to make restoring work

In version 3.2, Joomla added the ability to track content history (also called versions) for all core components. This allows you to view and restore from prior versions of an article, banner, category, and other content types. This feature can easily be added to third-party components. This tutorial shows you how to do this. We will illustrate this by adding content history to an example component.

'''Important Note:''' This tutorial assumes that the component uses a JTable sub-class for its "CRUD" (create/update/delete) operations. If the component does not use JTable then the simplest thing to do is to re-work it to use JTable's store() and delete() methods. If you do that, you will be able to use the methods described in this tutorial.

=Set up Working Environment=

# Install a new instance of Joomla version 3.2 on your local workstation.
# Install the example component using the file com_joomprosubs_3.2.0.zip in the Extension Manager: Install screen. You can get the ZIP archive here: https://github.com/joomla/jdoc-examples/raw/master/zip_archives/com_joomprosubs-3.2.0.zip.

At this point, you should be able to see the Joompro Subscriptions component in the Components menu in the back end of Joomla. This is the component before we have added content history to it.

=Add Rows to Content Types Table=
The first thing we need to do is to add two new rows into the #__content_types table. This table stores information about the different tables for each content type. As of Joomla version 3.2, this table is used by the com_tags and com_contenthistory components to get information about each content type for which history is stored. The columns for #__content_types are as follows:

*'''type_id:''' auto-increment id number.
*'''type_title:''' descriptive title for this table.
*'''type_alias:''' <component name>.<type name>. For example: "com_content.article" or "com_content.category".
*'''table:''' JSON string that contains the name of the JTable class and other information about the table.
*'''rules:''' Not used as of Joomla version 3.2.
*'''field_mappings:''' Used by the com_tags component to map database columns from the component table to the ucm_content table.
*'''router:''' Optional location of the component's router, if any.
*'''content_history_options:''' JSON string used to store information for rendering the pop-up windows in the content history component. We will discuss this in detail later in this tutorial.

Our example component uses a table called #__joompro_subscriptions to store each subscription. In addition, it uses the standard Joomla categories. So we will add a row in #__content_types for the category table and one for the component table.

The row for the categories can be copied from the row for "Weblinks Category" (or any other category row). The only columns that need to be changed are <code>type_title</code> and <code>type_alias</code>. The other columns are the same as for <code>com_weblinks.category</code>.

The SQL statement for adding this row is as follows:

<source lang="sql">
INSERT INTO `#__content_types` (`type_id`, `type_title`, `type_alias`, `table`, `rules`, `field_mappings`, `router`, `content_history_options`)
VALUES
(null,
'Subscription Category',
'com_joomprosubs.category',
'{"special":{"dbtable":"#__categories","key":"id","type":"Category","prefix":"JTable","config":"array()"},"common": {"dbtable":"#__ucm_content","key":"ucm_id","type":"Corecontent","prefix":"JTable","config":"array()"}}',
'',
'{"common":{"core_content_item_id":"id","core_title":"title","core_state":"published","core_alias":"alias","core_created_time":"created_time","core_modified_time":"modified_time","core_body":"description", "core_hits":"hits","core_publish_up":"null","core_publish_down":"null","core_access":"access", "core_params":"params", "core_featured":"null", "core_metadata":"metadata", "core_language":"language", "core_images":"null", "core_urls":"null", "core_version":"version", "core_ordering":"null", "core_metakey":"metakey", "core_metadesc":"metadesc", "core_catid":"parent_id", "core_xreference":"null", "asset_id":"asset_id"}, "special":{"parent_id":"parent_id","lft":"lft","rgt":"rgt","level":"level","path":"path","extension":"extension","note":"note"}}',
'WeblinksHelperRoute::getCategoryRoute',
'{"formFile":"administrator\\/components\\/com_categories\\/models\\/forms\\/category.xml", "hideFields":["asset_id","checked_out","checked_out_time","version","lft","rgt","level","path","extension"], "ignoreChanges":["modified_user_id", "modified_time", "checked_out", "checked_out_time", "version", "hits", "path"],"convertToInt":["publish_up", "publish_down"], "displayLookup":[{"sourceColumn":"created_user_id","targetTable":"#__users","targetColumn":"id","displayColumn":"name"},{"sourceColumn":"access","targetTable":"#__viewlevels","targetColumn":"id","displayColumn":"title"},{"sourceColumn":"modified_user_id","targetTable":"#__users","targetColumn":"id","displayColumn":"name"},{"sourceColumn":"parent_id","targetTable":"#__categories","targetColumn":"id","displayColumn":"title"}]}');</source>

For the actual subscriptions, we only need the following information in the content types table:

*'''type_title:''' <code>Subscriptions</code>
*'''type_alias:''' <code>com_joomprosubs.subscription</code>
*'''table:'''
::<pre>{"special":{"dbtable":"#__joompro_subscriptions","key":"id","type":"Subscription","prefix":"JoomprosubsTable"}}</pre>
::This creates a JSON object as follows:
:::special:
:::dbtable = #__joompro_subscriptions
:::key = id
:::type = Subscription
:::prefix = JoomprosubsTable

The <code>type_alias</code> column is used by the com_contenthistory component to find the row for each component in the #__content_types table. The <code>table</code> column gives the com_contenthistory component the information it needs to work with the JTable class for each component. The None of the other columns need to be set for now. Note that we will come back to the <code>content_history_options</code> column later in the tutorial to improve the appearance of the pop-up window.

The SQL for adding this second row to the #__content_types table is as follows:

<source lang="sql">INSERT INTO `#__content_types` (`type_id`, `type_title`, `type_alias`, `table`, `rules`, `field_mappings`, `router`, `content_history_options`)
VALUES
(null,
'Subscriptions',
'com_joomprosubs.subscription',
'{"special":{"dbtable":"#__joompro_subscriptions","key":"id","type":"Subscription","prefix":"JoomprosubsTable"}}',
'', '', '', '');
</source>

These lines should be added to the file <code>administrator/components/com_joomprosubs/sql/install.mysql.utf8.sql</code> so that these rows will be created when the component is installed. You should also run these commands on your database to add the two rows to your #__content_types table before going to the next section. Remember to change the placeholder prefix "#__" to the actual prefix for your database before running the SQL commands on your local database.

'''Tip:''' When creating the values for the JSON strings, one trick is to copy from an existing row and edit the strings.

=Add Component Level Options=
The content history component uses two options as follows.
*'''save_history:''' If Yes, history is saved. Otherwise, no history is saved.
*'''history_limit:''' If > 0, limits the number of different history versions saved in the database. For example, if this is set to 10, then when the 11th history version is saved, the oldest is deleted automatically.

If our example component, we will add the following lines to the file <code>administrator/components/com_joomprosubs/config.xml</code>.

<source lang="xml">

<fieldset name="component">
<field
name="save_history"
type="radio"
class="btn-group btn-group-yesno"
default="1"
label="JGLOBAL_SAVE_HISTORY_OPTIONS_LABEL"
description="JGLOBAL_SAVE_HISTORY_OPTIONS_DESC"
>
<option
value="0">JNO</option>
<option
value="1">JYES</option>
</field>

<field
name="history_limit"
type="text"
filter="integer"
label="JGLOBAL_HISTORY_LIMIT_OPTIONS_LABEL"
description="JGLOBAL_HISTORY_LIMIT_OPTIONS_DESC"
default="5"
/>
</fieldset>
</source>
With this code, we will now be able to add and save these options. Go into the Options for the component and set save_history to Yes and history_limit to 10.

=Update Content History During Table Save and Delete=
Next we need to tell our component to call the content history methods during the save and delete operations. We can do this by adding this line of code to the <code>__construct()</code> method of the <code>JoomprosubsTableSubscription</code> class.

<source lang="php">
JObserverMapper::addObserverClassToClass('JTableObserverContenthistory', 'JoomprosubsTableSubscription', array('typeAlias' => 'com_joomprosubs.subscription'));
</source>

This code registers the content history table as an observer class for our component table. When a row is saved or deleted from our table, the appropriate methods are called automatically for the content history table.

At this point, we should be able to see content history working for the Joomprosubs categories. Test this by adding a new category for the component and then clicking on the Versions button in the toolbar. It should work exactly the same as categories for the core Joomla components.

=Add type alias to model=

To make restoring work, you need to add <code>$typeAlias</code> property to your model class. Model is located in <code>administrator/components/com_joomprosubs/models/subscription.php</code>

<source lang="php">
public $typeAlias = 'com_joomprosubs.subscription';
</source>

If this is not set, you will get <code>Error restoring item version from history.</code> error, because Joomla! can not find correct row from <code>#__content_types</code> table.

=Add Versions Button to Tool Bar=
At this point, categories are working completely and we are saving history versions in the #__ucm_history table for our component. However, we need to be able to access these changes on our edit screen. To do this, we need to add the Versions button to the edit screen's toolbar. We do this by adding this code to the file <code>administrator/components/com_joomprosubs/views/subscription/view.html.php</code>, just before the code that adds the "cancel" button, as shown here.

<source lang="php">
else {
if ($this->state->params->get('save_history', 1) && $user->authorise('core.edit')) {
JToolbarHelper::versions('com_joomprosubs.subscription', $this->item->id);
}
JToolBarHelper::cancel('subscription.cancel', 'JTOOLBAR_CLOSE');
}
</source>

This code checks that we have the save_history option set and that we have edit permission for this component. If so, we show the Versions button using the <code>JToolbarHelper::versions()</code> method. This method has two arguments: the type_alias and the primary key of the component item row in the database.

With this code added, we can now go into the Joomprosubs component, add and save a new subscription, and now see the Versions button. If we click on it, we will see the Item Version History modal window open with our saved version.

There are still two things missing, however. One is that we don't have a way to add the Version Note to each version. The second is that we don't currently have meaningful labels for the versions when we use the Preview or Compare features. We will address these in the next two sections of this tutorial.

=Add Version Note Field to Form=
The content history feature adds a new field called "version_note" to the component edit form. This optional field is not saved in the component table. Instead, it is used to label the version in the content history table.

To add this field to our component edit screen, we do changes to two files. First, we add the field to the XML form file <code>administrator/components/com_joomprosubs/models/forms/subscription.xml</code> as follows:

<source lang="xml">
<field name="version_note"
type="text"
label="JGLOBAL_FIELD_VERSION_NOTE_LABEL"
description="JGLOBAL_FIELD_VERSION_NOTE_DESC"
class="inputbox" size="45"
labelclass="control-label"
/>
</source>

We can add it anywhere inside the fieldset element. Because we will place the field "created_by_alias" on the screen, we add it in the XML file after this element.

Second, we add this code to the file <code>administrator/components/com_joomprosubs/views/subscription/tmpl/edit.php</code>, just after the control group for "created_by_alias", as follows:

<source lang="php">
<div class="control-group">
<div class="control-label"><?php echo $this->form->getLabel('version_note'); ?></div>
<div class="controls"><?php echo $this->form->getInput('version_note'); ?></div>
</div>
</source>

Now we can add in a version note and see this in the Item Version History modal window.

=Add Labels to Pop-Up Windows=
At this point, everything works. However, when we use the pop-up Preview or Compare windows in the Item Version History modal, we see the database column names instead of the translated label from the form. Also, we see the category and user id numbers instead of the category name and user name.

We can improve the readability of windows by entering in some additional about our component's table. This information is entered as a JSON-formatted string in the content_history_options column of the #__content_types table. The following information can be entered in this column.
*'''formfile:''' This is the path to the XML JForm file for this form. If you add this, the Preview and Compare views will look up the labels from this XML file. This way the user will see translated labels instead of the database column name.
*'''hideFields:''' Some database columns are not meaningful for the user when viewing the item. For example, asset_id or check_out_time are not things that appear in the form and are not helpful to the user when figuring out the contents of an item. This is entered as an array of column names.
*'''ignoreChanges:''' The content history component uses a "hash" calculation (Sha1) to determine whether an item has changed. This allows you to see which version in history matches the current version. It also prevents duplicate versions from being saved in the content history table (for example, if you press the "save" button without making any changes). For this to work properly, we need to exclude some columns from the hash calculate. The "ignoreChanges" lets you exclude some database columns from the hash so that changes to these columns will not be considered real changes to the item. For example, columns such as "hits" or "modified_time" will change with each save, even if no meaningful data was changed in the item. This is an array of database column names.
*'''convertToInt:''' When the hash value is created, it uses a JSON array of the database column values. In some cases, such as start and stop publishing dates, the value might be blank when a row is first created and then a different value after the item is saved. To get a consistent hash value for the first and subsequent saves, these values can be converted to integers before the hash is created. That way, we don't think a value has changed when it really hasn't. This is an array of database column names.
*'''displayLookup:''' Here we can define how to display more meaningful data, for example, displaying a category title or user name instead of the ID. This is stored as an array of PHP standard class objects. Each object has the following fields.
:*''sourceColumn:'' The column in the form to replace. For example, the "created_user_id" or "catid".
:*''targetTable:'' The database table to get the title or name. For example, "#__users" or "#__categories".
:*''targetColumn:'' The column in the target table to use in the SQL query JOIN statement. For example, "id".
:*''displayColumn:'' The column in the target table to display in the Preview or Compare pop-up window. For example, "name" or "title".

In our example component, we need the following values.
*'''formfile:''' <code>administrator/components/com_joomprosubs/models/forms/subscription.xml</code>.
*'''hideFields:''' checked_out, checked_out_time, params, langauge. The last two columns are not used.
*'''ignoreChanges:''' modified_by, modified, checked_out, checked_out_time.
*'''convertToInt:''' publish_up, publish_down.
*'''displayLookup:''' We look up five fields: catid, group_id, created_by, access, and modified_by. The values for each are as follows.
:*''sourceColumn:'' catid
:*''targetTable:'' #__categories
:*''targetColumn:'' id
:*''displayColumn:'' title

:*''sourceColumn:'' group_id
:*''targetTable:'' #__usergroups
:*''targetColumn:'' id
:*''displayColumn:'' title

:*''sourceColumn:'' created_by
:*''targetTable:'' #__users
:*''targetColumn:'' id
:*''displayColumn:'' name

:*''sourceColumn:'' access
:*''targetTable:'' #__viewlevels
:*''targetColumn:'' id
:*''displayColumn:'' title

:*''sourceColumn:'' modified_by
:*''targetTable:'' #__users
:*''targetColumn:'' id
:*''displayColumn:'' name

The entire JSON string for this column is as follows.

<source>
{"formFile":"administrator\/components\/com_joomprosubs\/models\/forms\/subscription.xml",
"hideFields":["checked_out","checked_out_time","params","language"],
"ignoreChanges":["modified_by", "modified", "checked_out", "checked_out_time"],
"convertToInt":["publish_up", "publish_down"],
"displayLookup":[
{"sourceColumn":"catid","targetTable":"#__categories","targetColumn":"id","displayColumn":"title"},
{"sourceColumn":"group_id","targetTable":"#__usergroups","targetColumn":"id","displayColumn":"title"},
{"sourceColumn":"created_by","targetTable":"#__users","targetColumn":"id","displayColumn":"name"},
{"sourceColumn":"access","targetTable":"#__viewlevels","targetColumn":"id","displayColumn":"title"},
{"sourceColumn":"modified_by","targetTable":"#__users","targetColumn":"id","displayColumn":"name"} ]}
</source>

Note that the slashes are escaped inside the JSON string. In order to get this column correctly into the database when our component is installed, we need to modify the file <code>administrator/components/com_joomprosubs/sql/install.mysql.utf8.sql</code> where we create the #__content_types for for the component as follows:

<source lang="sql">
INSERT INTO `#__content_types` (`type_id`, `type_title`, `type_alias`, `table`, `rules`, `field_mappings`, `router`, `content_history_options`) VALUES
(null, 'Subscriptions', 'com_joomprosubs.subscription', '{"special":{"dbtable":"#__joompro_subscriptions","key":"id","type":"Subscription","prefix":"JoomprosubsTable"}}', '', '', '', '{"formFile":"administrator\\/components\\/com_joomprosubs\\/models\\/forms\\/subscription.xml", "hideFields":["checked_out","checked_out_time","params","language"], "ignoreChanges":["modified_by", "modified", "checked_out", "checked_out_time"], "convertToInt":["publish_up", "publish_down"], "displayLookup":[{"sourceColumn":"catid","targetTable":"#__categories","targetColumn":"id","displayColumn":"title"},{"sourceColumn":"group_id","targetTable":"#__usergroups","targetColumn":"id","displayColumn":"title"},{"sourceColumn":"created_by","targetTable":"#__users","targetColumn":"id","displayColumn":"name"},{"sourceColumn":"access","targetTable":"#__viewlevels","targetColumn":"id","displayColumn":"title"},{"sourceColumn":"modified_by","targetTable":"#__users","targetColumn":"id","displayColumn":"name"} ]}');
</source>

Note that the "/" characters are now preceeded by two escape "\" characters. The first one is the SQL escape character for the second "\" character. The second "\" is the JSON escape character for the "/" character.

With this change to the SQL install file, the changes for content history are complete.

=Update Extension SQL Files=
To tidy things up, should should edit the uninstall SQL file to remove the rows from the #__content_types table. Also, if your component uses the one-click update feature, you should create a SQL file to create these rows when the component is updated.

Hopefully, this tutorial will help you as you update your component to take advantage of the content history feature in Joomla. You can download the com_joomprosubs component with the code for content history added here: https://github.com/joomla/jdoc-examples/raw/master/zip_archives/com_joomprosubs-3.2.1.zip.

[[Category:Development]][[Category:Content History]]
[[Category:Tutorials]]

Extensions packing

2013-10-24T11:51:13Z

Renekorss:

{{incomplete}}
{{RightTOC}}
Recommendations when creating packs to distribute extensions:
== Single extension ==
Name it with extension type and version at end
* com_extensionxyz_v1.0.zip
* mod_extensionxyz_v1.0.zip
* plg_extensionxyz_v1.0.zip

== Multiple extensions pack ==
If creating zip/tar files that require unzipping prior to install name the zip accordingly:
* extensionxyz_v1.0_UNZIPME.zip
It's strongly recommended to use [[Package|Package]] ({{JVer|2.5}} and higher) for multiple extensions. This avoids unpacking and is easily installable.
== Test it ==
Please do test the zip/tar file and install it in a Joomla test server before release your file.

[[Category:JED]]{{stub}}
[[Category:Stubs]]

Deploying an Update Server

2013-10-24T11:18:35Z

Renekorss: /* Contributors */

{{version/tutor|2.5,3.x}}

== Introduction ==
This tutorial is designed to teach developers how to create an update server for integration with the update system introduced in Joomla!. By adding an update server listing to your extension's manifest, developers enable users to update their extensions via the Extension Manager's Update (see [[Help25:Extensions Extension Manager Update|Joomla 2.5]] and [[Help31:Extensions Extension Manager Update|Joomla 3.x]] helpscreens) view with only a few clicks.

== Defining an update server ==
In order to use this feature, an update server must be defined in your extension's manifest. This definition can be used in all Joomla! 2.5 and newer compatible extensions but is not available for templates. You can use two options for your server type; collection or extension. These will be explained in detail shortly. This code should be added to the extension manifest file, within the root "extension" element. The update server is defined as follows for each type:

<source lang="xml">
<extension>
<...>
<updateservers>
<server type="collection">http://example.com/list.xml</server>
<server type="extension" priority="2" name="My Extension's Updates">http://example.com/extension.xml</server>
</updateservers>
</extension>
</source>

Multiple servers can be defined within the <updateservers> tag.

== Server types ==
=== Collection ===
The collection server type allows developers to define an extension's manifest to pull updates from a collection. This type of server can be used if the developer wants to define all of their extension's updates in a single file (not recommended) or if their extension has multiple sub-extensions which are not distributed or updated at the same time (such as a package extension type). The below example is the collection definition used by the updater when processing core Joomla! updates:

<source lang="xml">
<extensionset name="Joomla Core" description="Joomla! Core">
<extension name="Joomla" element="joomla" type="file" version="1.7.0" detailsurl="http://update.joomla.org/core/extension.xml"/>
</extensionset>
</source>

All definitions must be defined between <extensionset> tags in your collection manifest. The <extensionset> tag has two optional parameters; name and description. For each extension that this collection references, a separate <extension> tag is required. The <extension> tag has the following parameters, all of which are required for updates to properly process:

* '''name''' - The name of the extension
* '''element''' - The untranslated extension name i.e. mod_custom
* '''type''' - The extension type (component, module, plugin, etc.)
* '''version''' - The latest version of the extension
* '''detailsurl''' - The URL of the XML file which contains that extension's individual update definitions

=== Extension ===
The extension server type allows developers to define an extension's manifest to pull updates from a single extension's manifest. All collection manifests eventually point to this XML file. All updates in this file must be defined after an <updates> tag at the beginning of the file. The below example is the update definition for the Joomla! 1.7.0 release:

<source lang="xml">
<update>
<name>Joomla! 1.7</name>
<description>Joomla! 1.7 CMS</description>
<element>joomla</element>
<type>file</type>
<version>1.7.0</version>
<infourl title="Joomla!">http://www.joomla.org/</infourl>
<downloads>
<downloadurl type="full" format="zip">http://joomlacode.org/gf/download/frsrelease/15279/66552/Joomla_1.6.5_to_1.7.0_Package.zip</downloadurl>
</downloads>
<tags>
<tag>stable</tag>
</tags>
<maintainer>Sam Moffatt</maintainer>
<maintainerurl>http://sammoffatt.com.au</maintainerurl>
<section>Testing</section>
<targetplatform name="joomla" version="1.6"/>
</update>
</source>

The following section describes the elements of a single update entity.

* '''name''' - The name of the extension, this name will appear in the Name column of the Extension Manager's Update view (required)
* '''description''' - A short description of the extension (optional) -- if you choose to use <![CDATA[]]>, double-quotes will break the HTML formatting. Use single quotes with your HTML entities.
* '''element''' - The installed name of the extension (required). For plugins, this needs to be same as plugin attribute value for main file in plugin manifest. For <filename plugin="pluginname">pluginname.php</filename>, element value should be '''pluginname'''.
* '''type''' - The type of extension (component, module, plugin, etc.) (required)
* '''folder''' - Specific to plugins, this tag describes the type of plugin being updated (content, system, etc.) (required for plugins)
* '''client''' (usually optional, required for J! 1.7.3 due to a regression; but highly encouraged regardless) - The client ID of the extension, which can be found by looking inside the #__extensions table. To date, use 0 for "site" and 1 for "administrator". Plugins and front-end modules are automatically installed with a client of 0 (site), but you will need to specify the client in an update or it will default to 1 (administrator) and then found update would not be shown because it would not match any extension. Components are automatically installed with a client of 1, which is currently the default.
** ''Warning'': The tag name is <'''client'''> for Joomla! 2.5 and <'''client_id'''> for 1.6 and 1.7. If you use <client_id> (rather than <client>) on a 2.5 site, it will be ignored.
* '''version''' - The version of the release (required)
* '''infourl''' - A URL to point users to containing information about the update (optional) (In CMS 2.5, if set, this URL will be displayed in the update view)
* '''downloads''' - The section which lists all download locations
** '''downloadurl''' - The URL to download the extension from; the <downloadurl> tag has two required parameters:
*** '''type''' - The type of package (full or upgrade)
*** '''format''' - The format of the package (zip, tar, etc.)
* '''tags''' - Optional (unknown use)
* '''maintainer''' - The name of the extension maintainer (similar to the <author> tag in a manifest) (optional)
* '''maintainerurl''' - The website of the extension maintainer (similar to the <authorUrl> tag in a manifest) (optional)
* '''section''' - Optional (unknown use)
* '''targetplatform''' - A tag to define platform requirements, requires the following elements
** '''name''' - The name of the platform dependency; as of this writing, it should ONLY be "joomla"
** '''version''' - The version of Joomla! the extension supports
** '''min_dev_level''' and '''max_dev_level''' - These attributes were added in 3.0.1 to allow you to select a target platform based on the developer level ("z" in x.y.z). They are optional. You can specifiy either one or both. If omitted, all developer levels are matched. For example, the following matches versions 4.0.0 and 4.0.1. <code><targetplatform name="joomla" version="4.0" min_dev_level="0" max_dev_level="1"/></code>
*** '''Note:''' If your extension is Joomla! 2.5 and/or 3.1 compatible, you will be required to have separate <update> definitions for each version due to the manner in which the updater checks the version if you specify a number. However to show your extension on all Joomla versions that support automatic updates add <code><targetplatform name="joomla" version=".*"/></code>. If you want your extension to show on all {{JVer|3.x}} versions then rather than specifying a version in the version tag add in <code><targetplatform name="joomla" version="3.[012345]"/></code>. This will show the update to all 3.x versions.

A separate <update> definition will be required for each version of your extension you release.

The values of '''element''', '''type''', '''client_id''' and '''folder''' should match those in the table #__extensions.

'''Important for plugins:''' Plugins have to include <folder> and <client> elements to work properly

== Troubleshooting ==
* '''SQL update script is not executed during update.'''
:If the SQL update script (for example, in the folder <code>sql/updates/mysql</code>) does not get executed during the update process, it could be because there is no version number in the <code>#__schemas</code> table for this extension ''prior to the update''. This value is determined by the last script name in the SQL updates folder. If this value is blank, no SQL scripts will be executed during that update cycle. To make sure this value is set correctly, make sure you have a SQL script in this folder with its name as the version number (for example, 1.2.3.sql if the version is 1.2.3). The file can be empty or just have a SQL comment line. This should be done in the old version -- the one before the update. Alternatively, you can add this value to the <code>#__schemas</code> using a SQL query.

== Supporting Tools ==
Maintaining your update server files can be difficult depending on the manner in which you set up your files. An extension which can help you to maintain this is the Akeeba Release System, available free of charge from https://www.akeebabackup.com

== Contributors ==
*[[User:mbabker|Michael Babker]]
*[[User:Renekorss|Rene Korss]]
[[Category:Development]]

Deploying an Update Server

2013-10-22T10:36:00Z

Renekorss: Element confusion. Developers often add plg_ in front.