Archived

Difference between revisions of "Layout Overrides in Joomla"

From Joomla! Documentation

(Initial draft)
 
(Remove 1.6 and 1.7 tags and add 3.1)
(14 intermediate revisions by 7 users not shown)
Line 1: Line 1:
=== Introduction to Alternative Layout Feature in Version 1.6 ===
+
{{version/tutor|2.5,3.1}}
Joomla! version 1.6 introduces a set set of features that give the site administrator more control over the display of articles, contacts, news feeds, and web links. There are four types of alternative layouts:  
+
=== Introduction to Alternative Layout Feature in Versions 2.5+ ===
# Module  
+
Joomla! 1.5 introduced the concept of [[How_to_override_the_output_from_the_Joomla!_core | overriding core layouts]] using the template override system. Joomla! version 2.5 introduces a set of features that give the site administrator more control over the display of articles, contacts, news feeds, and web links. There are four types of alternative layouts:  
# Component  
+
# Module
# Category and
+
# Component
 +
# Category
 
# Menu Item
 
# Menu Item
  
Line 9: Line 10:
  
 
=== Module Alternative Layouts ===
 
=== Module Alternative Layouts ===
<nowiki>Creating an alternative layout for a module is very similar to creating a template override for a module. In both cases, you create a folder called "templates/<your template>/html/<module name>. For example, the folder for a "mod_login" template override or alternative layout would be </nowiki>"templates/beez5/html/mod_login/".  
+
Creating an alternative layout for a module is similar to creating a template override for a module. In both cases, you create a folder called "templates/<your template>/html/<module name>. For example, the folder for a "mod_login" template override or alternative layout for the beez5 template would be "templates/beez5/html/mod_login/".  
  
There are two important differences between a template override and an alternative layout. The first is the file name. For the template override, you would call the file "default.php" to match the core file name. For an alternative layout, you use a different name. The only rule is that the file name should not have any underscores in it. This allows you to have complex layouts that include multiple files. The initial file to be called is named without underscores and any other files that are called from this initial file will have underscores in the name. For example, you could have the initial file called "mynewlogin.php" which called "mynewlogin_1.php".
+
There are two important differences between a template override and an alternative layout. The first is the file name. For the template override, you would call the file "default.php" to match the core file name. For an alternative layout, you use a different name. The only rule is that the file name should not have any underscores in it. This allows you to have complex layouts that include multiple files. The initial file to be called is named without underscores and any other files that are called from this initial file will have underscores in the name. For example, you could have the initial file called "mynewlogin.php" which calls "mynewlogin_1.php".
  
The second important difference is that, unlike template override files which are called automatically whenever the module is displayed using the template with the override, an alternative layout file is only called if you select it as a parameter in the Module Manager. In version 1.6, there is a new parameter called under Advanced Options called Alternative Layout, as shown below.
+
The second important difference is that, unlike template override files which are called automatically whenever the module is displayed using the template with the override, an alternative layout file is only called if you select it as a parameter in the Module Manager. In version 2.5 and later, there is a new parameter under Advanced Options called Alternative Layout, as shown below.
  
[[Image:]]
+
[[Image:Screenshot_override_tutorial_20110107-01.png|frame|center]]
  
 
This parameter will list any files (without underscores) that you have placed in the template folder for this module. You can also translate the file name using the template's system language file. For example, if you add the line  
 
This parameter will list any files (without underscores) that you have placed in the template folder for this module. You can also translate the file name using the template's system language file. For example, if you add the line  
Line 23: Line 24:
 
to the file "en-GB.tpl_beez5.sys.ini", it will translate the file name "nologin.php" to "Alt Login Layout".  
 
to the file "en-GB.tpl_beez5.sys.ini", it will translate the file name "nologin.php" to "Alt Login Layout".  
  
It is important to understand, if specified in the Module Manager screen, an alternative layout file for a module will be used for that module regardless of what template is used to display the page where the module is shown. It is therefore the administrator's responsibility to make sure that the layout file will work as desired in any templates where this module may be shown.
+
It is important to understand that if specified in the Module Manager screen, an alternative layout file for a module will be used for that module regardless of what template is used to display the page where the module is shown. It is therefore the administrator's responsibility to make sure that the layout file will work as desired in any templates where this module may be shown.
  
 
=== Component Alternative Layouts ===
 
=== Component Alternative Layouts ===
Line 30: Line 31:
 
You can set a global value for component layouts in the Options window of the component. For example, in the Article Manager Options window, there is a parameter for Alternative Layout as shown below:
 
You can set a global value for component layouts in the Options window of the component. For example, in the Article Manager Options window, there is a parameter for Alternative Layout as shown below:
  
[[Image:]]This will create a global value that individual components (articles, contacts, newsfeeds, and weblinks) can inherit from.
+
[[Image:Screenshot_override_tutorial_20110107-02.png|frame|center]]
 +
 
 +
This will create a global value that individual components (articles, contacts, newsfeeds, and weblinks) can inherit from.
  
 
As with module layouts, the component layouts are shown as parameter options in the individual component edit screen. For example, for an article, the parameter shows in the Article Options group as shown below.
 
As with module layouts, the component layouts are shown as parameter options in the individual component edit screen. For example, for an article, the parameter shows in the Article Options group as shown below.
  
[[Image:]]
+
[[Image:Screenshot_override_tutorial_20110107-03.png|frame|center]]
  
As with other parameters, the Use Global setting will use the setting from the Options parameter. The From Component → Default setting will use the component's default layout. Alternative layouts that you have created for different templates are shown under each template heading.
+
As with other parameters, the Use Global setting will use the setting from the Options parameter. The From Component's Default setting will use the component's default layout. Alternative layouts that you have created for different templates are shown under each template heading.
  
 
File names may be translated. The line below
 
File names may be translated. The line below
Line 48: Line 51:
 
Component alternative layouts may be used with articles, contacts, or news feeds. Web links don't have a single-component layout so no alternative layout is available for web links.
 
Component alternative layouts may be used with articles, contacts, or news feeds. Web links don't have a single-component layout so no alternative layout is available for web links.
  
Component alternative layouts are only used when two conditions are met: (1) they are specified in the component parameters; and (2) there is no menu item for this specific component. For example, if you have one or more menu items of type "Single Article" set up for a given article, then the alternative layout for that article will not be used. Instead, the layout specified in the menu item will be used. This is consistent with the general way that component parameters work, where the most specific (in this case a single-article menu item) overrides the less specific (in this case, the article parameters).  
+
Component alternative layouts are only used when two conditions are met: (1) they are specified in the component parameters; and (2) there is no menu item for this specific component. For example, if you have one or more menu items of type "Single Article" set up for a given article, then the alternative layout for that article will not be used. Instead, the layout specified in the menu item will be used. This is consistent with the general way that component parameters work, where the most specific (in this case a single-article menu item) overrides the less specific (in this case, the article parameters).
  
 
=== Category Alternative Layouts ===
 
=== Category Alternative Layouts ===
Line 55: Line 58:
 
You can set category layouts globally, in the Options screen of each component. Below is an example from the Contact Manager Options screen:
 
You can set category layouts globally, in the Options screen of each component. Below is an example from the Contact Manager Options screen:
  
[[Image:]]
+
[[Image:Screenshot_override_tutorial_20110107-04.png|frame|center]]
  
 
Category alternative layouts show up when you add or edit a category in the Category Manager under the Basic Options, as shown below.
 
Category alternative layouts show up when you add or edit a category in the Category Manager under the Basic Options, as shown below.
  
[[Image:]]
+
[[Image:Screenshot_override_tutorial_20110107-05.png|frame|center]]
  
 
Category alternative layouts may be used for articles, contacts, news feeds, and web links.  
 
Category alternative layouts may be used for articles, contacts, news feeds, and web links.  
Line 68: Line 71:
  
 
=== Drill Down to Blog or List ===
 
=== Drill Down to Blog or List ===
For articles, we have two core layouts available: Blog and List. Both of these options show under the "From Component" heading in the layout parameters for article category. So, like other layout options, you can now select Blog or List for categories either globally (in the Article Manager → Options, shown below), or when editing a single article category.
+
For articles, we have two core layouts available: Blog and List. Both of these options show under the "From Component" heading in the layout parameters for article category. So, like other layout options, you can now select Blog or List for categories either globally (in the Article Manager Options, shown below), or when editing a single article category.
  
[[Image:]]This means like, like other layout options, you can control whether article category links drill down to blog or list layouts. It is important to understand that, like other layout parameters, this option will only take effect when there is no single-category menu item for the category.
+
[[Image:Screenshot_override_tutorial_20110107-06.png|frame|center]]
 +
 
 +
This means that, like other layout options, you can control whether article category links drill down to blog or list layouts. It is important to understand that, like other layout parameters, this option will only take effect when there is no single-category menu item for the category.
  
 
=== Alternative Menu Items ===
 
=== Alternative Menu Items ===
Line 79: Line 84:
 
Alternative Menu Items show up when you select a menu item type in the Menu Manager, as shown below.
 
Alternative Menu Items show up when you select a menu item type in the Menu Manager, as shown below.
  
[[Image:]]
+
[[Image:Screenshot_override_tutorial_20110107-07.png|frame|center]]
  
 
Alternative Menu Items are used and work the same way as standard menu items. Since they are already based on customised layouts, template overrides do not apply to alternative menu items.
 
Alternative Menu Items are used and work the same way as standard menu items. Since they are already based on customised layouts, template overrides do not apply to alternative menu items.
Line 85: Line 90:
 
As indicated above, menu item layouts take priority over component or category alternative layouts.  
 
As indicated above, menu item layouts take priority over component or category alternative layouts.  
  
<nowiki>Translation of alternative menu items is done with the following tags in the XML files. The format is "TPL_"<template name>_<component>_<view>_<menu item name>_<tag type>. For example, these lines below will translate the title, option, and description for an alternative menu item called "catmenuitem".</nowiki>
+
Translation of alternative menu items is done with the following tags in the XML files. The format is "TPL_"<template name>_<component>_<view>_<menu item name>_<tag type>. For example, these lines below will translate the title, option, and description for an alternative menu item called "catmenuitem".
  
 
TPL_BEEZ5_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_TITLE="Beez5 Custom Category Layout"
 
TPL_BEEZ5_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_TITLE="Beez5 Custom Category Layout"
 +
 
TPL_BEEZ5_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_OPTION="Beez5 Custom"
 
TPL_BEEZ5_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_OPTION="Beez5 Custom"
 +
 
TPL_BEEZ5_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_DESC="Description for beez5 custom category layout."
 
TPL_BEEZ5_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_DESC="Description for beez5 custom category layout."
 +
 +
These strings have to be added to '''language/en-GB/en-GB.tpl_beez5.sys.ini'''
 +
 +
The catmenuitem.xml would start with:
 +
 +
<source lang="XML">
 +
<?xml version="1.0" encoding="utf-8"?>
 +
<metadata>
 +
  <layout title="TPL_BEEZ5_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_TITLE" option="TPL_BEEZ5_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_OPTION">
 +
      <help
 +
        key = "JHELP_MENUS_MENU_ITEM_ARTICLE_SINGLE_ARTICLE"
 +
      />
 +
      <message>
 +
        <![CDATA[TPL_BEEZ5_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_DESC]]>
 +
      </message>
 +
  </layout>
 +
</source>
  
 
=== Controlling the Template for Alternative Menu Items ===
 
=== Controlling the Template for Alternative Menu Items ===
Line 96: Line 120:
 
It is also possible to override parameter settings for core parameters. One example of this is to control which templates an alternative menu item layout can be displayed with. In some cases, you may want to allow a custom menu item to be displayed with any template for
 
It is also possible to override parameter settings for core parameters. One example of this is to control which templates an alternative menu item layout can be displayed with. In some cases, you may want to allow a custom menu item to be displayed with any template for
 
the site. In other cases, you may wish to limit that menu item's layout to one specific template. In this situation, you would just add the following parameter to the menu item's XML file:
 
the site. In other cases, you may wish to limit that menu item's layout to one specific template. In this situation, you would just add the following parameter to the menu item's XML file:
 
+
<source lang="XML">
<nowiki><</nowiki>fields>
+
<fields>
<nowiki><</nowiki>field
+
  <field
name<nowiki>=</nowiki>''"template_style_id"''
+
    name=''"template_style_id"''
type<nowiki>=</nowiki>''"templatestyle"''
+
    type=''"templatestyle"''
label<nowiki>=</nowiki>''"COM_MENUS_ITEM_FIELD_TEMPLATE_LABEL"''
+
    label=''"COM_MENUS_ITEM_FIELD_TEMPLATE_LABEL"''
description<nowiki>=</nowiki>''"COM_MENUS_ITEM_FIELD_TEMPLATE_DESC"''
+
    description=''"COM_MENUS_ITEM_FIELD_TEMPLATE_DESC"''
filter<nowiki>=</nowiki>''"int"''
+
    filter=''"int"''
template<nowiki>=</nowiki>''"beez5"''
+
    template=''"beez5"''
class<nowiki>=</nowiki>''"inputbox"''>
+
    class=''"inputbox"''>
<nowiki></</nowiki>field>
+
  </field>
 
+
</fields>
<tt><nowiki></</nowiki>fields></tt>
+
</source>
  
 
This will override the core "template_style_id" parameter. Setting the template equal to "beez5" in this case will limit the user to only selecting template styles for the "beez5" template.
 
This will override the core "template_style_id" parameter. Setting the template equal to "beez5" in this case will limit the user to only selecting template styles for the "beez5" template.
  
 
+
[[Category:Joomla! 1.6]][[Category:Joomla! 1.7]][[Category:Joomla! 2.5]] [[Category:Joomla! 3.1]] [[Category:Tutorials]]
[[Category:Joomla! 1.6]] [[Category:Tutorials]]
 

Revision as of 04:25, 29 April 2013

This page has been archived. This page contains information for an unsupported Joomla! version or is no longer relevant. It exists only as a historical reference, it will not be improved and its content may be incomplete and/or contain broken links.

Introduction to Alternative Layout Feature in Versions 2.5+[edit]

Joomla! 1.5 introduced the concept of overriding core layouts using the template override system. Joomla! version 2.5 introduces a set of features that give the site administrator more control over the display of articles, contacts, news feeds, and web links. There are four types of alternative layouts:

  1. Module
  2. Component
  3. Category
  4. Menu Item

Alternative layouts work in a similar fashion to the template override feature but allow you more options and control. Each type is discussed below.

Module Alternative Layouts[edit]

Creating an alternative layout for a module is similar to creating a template override for a module. In both cases, you create a folder called "templates/<your template>/html/<module name>. For example, the folder for a "mod_login" template override or alternative layout for the beez5 template would be "templates/beez5/html/mod_login/".

There are two important differences between a template override and an alternative layout. The first is the file name. For the template override, you would call the file "default.php" to match the core file name. For an alternative layout, you use a different name. The only rule is that the file name should not have any underscores in it. This allows you to have complex layouts that include multiple files. The initial file to be called is named without underscores and any other files that are called from this initial file will have underscores in the name. For example, you could have the initial file called "mynewlogin.php" which calls "mynewlogin_1.php".

The second important difference is that, unlike template override files which are called automatically whenever the module is displayed using the template with the override, an alternative layout file is only called if you select it as a parameter in the Module Manager. In version 2.5 and later, there is a new parameter under Advanced Options called Alternative Layout, as shown below.

Screenshot override tutorial 20110107-01-en.png

This parameter will list any files (without underscores) that you have placed in the template folder for this module. You can also translate the file name using the template's system language file. For example, if you add the line

TPL_BEEZ5_MOD_LOGIN_LAYOUT_NOLOGIN="Alt Login Layout"

to the file "en-GB.tpl_beez5.sys.ini", it will translate the file name "nologin.php" to "Alt Login Layout".

It is important to understand that if specified in the Module Manager screen, an alternative layout file for a module will be used for that module regardless of what template is used to display the page where the module is shown. It is therefore the administrator's responsibility to make sure that the layout file will work as desired in any templates where this module may be shown.

Component Alternative Layouts[edit]

Component alternative layouts work similarly to module layouts discussed above. Again, a file is placed in the same folder where you place a template override file. For example, to create an alternative layout for an article for the template "beez5", you would put a file in the folder "templates/beez5/html/com_content/article/". As with module layouts, the file should not be named the same as the core file and should not include underscores in the name. Additionally, there should not be an XML file of the same name in this folder. (We'll discuss XML files below under Menu Item Alternative Layouts.)

You can set a global value for component layouts in the Options window of the component. For example, in the Article Manager Options window, there is a parameter for Alternative Layout as shown below:

Screenshot override tutorial 20110107-02-en.png

This will create a global value that individual components (articles, contacts, newsfeeds, and weblinks) can inherit from.

As with module layouts, the component layouts are shown as parameter options in the individual component edit screen. For example, for an article, the parameter shows in the Article Options group as shown below.

Screenshot override tutorial 20110107-03-en.png

As with other parameters, the Use Global setting will use the setting from the Options parameter. The From Component's Default setting will use the component's default layout. Alternative layouts that you have created for different templates are shown under each template heading.

File names may be translated. The line below

TPL_BEEZ5_COM_CONTENT_ARTICLE_LAYOUT_MYLAYOUT="Title Only No XML"

will translate a file called "mylayout.php" as "Title Only No XML".

You can have more than one file for a layout. The initial file must be named without underscores and any additional files must have underscores.

Component alternative layouts may be used with articles, contacts, or news feeds. Web links don't have a single-component layout so no alternative layout is available for web links.

Component alternative layouts are only used when two conditions are met: (1) they are specified in the component parameters; and (2) there is no menu item for this specific component. For example, if you have one or more menu items of type "Single Article" set up for a given article, then the alternative layout for that article will not be used. Instead, the layout specified in the menu item will be used. This is consistent with the general way that component parameters work, where the most specific (in this case a single-article menu item) overrides the less specific (in this case, the article parameters).

Category Alternative Layouts[edit]

Category alternative layouts work identically to component layouts. The rules for specifying layout files are the same. The only difference is that the folder is the category folder, not the component folder. For example, a contact category alternative layout for beez5 would go in the folder "templates/beez5/html/com_contact/category".

You can set category layouts globally, in the Options screen of each component. Below is an example from the Contact Manager Options screen:

Screenshot override tutorial 20110107-04-en.png

Category alternative layouts show up when you add or edit a category in the Category Manager under the Basic Options, as shown below.

Screenshot override tutorial 20110107-05-en.png

Category alternative layouts may be used for articles, contacts, news feeds, and web links.

As with component layouts, category layouts only will show if (1) they are specified for the category in the global or category parameters and (2) there is no menu item specifically for this category (for example, List Contacts in a Category, List Newsfeeds in a Category, List Weblinks in a Category, Category List, Category Blog).

If there is a menu item set up for this specific category, that layout will be used instead of the alternative category layout.

Drill Down to Blog or List[edit]

For articles, we have two core layouts available: Blog and List. Both of these options show under the "From Component" heading in the layout parameters for article category. So, like other layout options, you can now select Blog or List for categories either globally (in the Article Manager Options, shown below), or when editing a single article category.

Screenshot override tutorial 20110107-06-en.png

This means that, like other layout options, you can control whether article category links drill down to blog or list layouts. It is important to understand that, like other layout parameters, this option will only take effect when there is no single-category menu item for the category.

Alternative Menu Items[edit]

Alternative Menu Items have one important difference with the others. To create a menu item alternative layout, you must include an XML file whose name matches the initial layout file. For example, to create an alternative menu item called "myarticle" for an article in the beez5 template, you would create two files in the "templates/beez5/html/com_content/article" folder called "myarticle.php" and "myarticle.xml". If you wanted to include more layout files, you would add these files with underscores in the file names.

The XML file uses the same format as the core Menu Item XML files. This allows you not only to create a customized layout for this menu item, it also allows you to create customized parameters. For example, you could hide some parameters or add new parameters.

Alternative Menu Items show up when you select a menu item type in the Menu Manager, as shown below.

Screenshot override tutorial 20110107-07-en.png

Alternative Menu Items are used and work the same way as standard menu items. Since they are already based on customised layouts, template overrides do not apply to alternative menu items.

As indicated above, menu item layouts take priority over component or category alternative layouts.

Translation of alternative menu items is done with the following tags in the XML files. The format is "TPL_"<template name>_<component>_<view>_<menu item name>_<tag type>. For example, these lines below will translate the title, option, and description for an alternative menu item called "catmenuitem".

TPL_BEEZ5_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_TITLE="Beez5 Custom Category Layout"

TPL_BEEZ5_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_OPTION="Beez5 Custom"

TPL_BEEZ5_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_DESC="Description for beez5 custom category layout."

These strings have to be added to language/en-GB/en-GB.tpl_beez5.sys.ini

The catmenuitem.xml would start with:

<?xml version="1.0" encoding="utf-8"?>
<metadata>
   <layout title="TPL_BEEZ5_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_TITLE" option="TPL_BEEZ5_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_OPTION">
      <help
         key = "JHELP_MENUS_MENU_ITEM_ARTICLE_SINGLE_ARTICLE"
      />
      <message>
         <![CDATA[TPL_BEEZ5_COM_CONTENT_CATEGORY_VIEW_CATMENUITEM_DESC]]>
      </message>
   </layout>

Controlling the Template for Alternative Menu Items[edit]

As discussed above, the presence of an XML file makes an alternative layout a menu item. The format of the XML file is the same as the format for core menu item XML files. With this XML file, you can add the parameters you wish to include for this menu item. They can be the same as one of the core menu items, or you can omit core parameters or add new ones. Note that if you add new parameters, these can be used in the layout file but will not be used in the core model or view files.

It is also possible to override parameter settings for core parameters. One example of this is to control which templates an alternative menu item layout can be displayed with. In some cases, you may want to allow a custom menu item to be displayed with any template for the site. In other cases, you may wish to limit that menu item's layout to one specific template. In this situation, you would just add the following parameter to the menu item's XML file:

<fields>
  <field
    name=''"template_style_id"''
    type=''"templatestyle"''
    label=''"COM_MENUS_ITEM_FIELD_TEMPLATE_LABEL"''
    description=''"COM_MENUS_ITEM_FIELD_TEMPLATE_DESC"''
    filter=''"int"''
    template=''"beez5"''
    class=''"inputbox"''>
  </field>
 </fields>

This will override the core "template_style_id" parameter. Setting the template equal to "beez5" in this case will limit the user to only selecting template styles for the "beez5" template.