View source for Sharing layouts across views or extensions with JLayout

{{Version/tutor|3.0}}

It is common that parts of pages are replicated across several views inside an extension, or even across several extensions. Examples might be:

* an extension sharing some display layouts between front-end and backend views, or with one or more modules
* backend extensions that have some common settings, and thus have to replicate common display layouts to allow users to change them

Up until Joomla! 3.0, the loading (and template overriding) of layout files was restricted to a given view.
The JLayout interface and set of classes was added to Joomla! 3.0 to help solve this very problem. It encapsulates a layout and the data required to display it so that they can be reused across views and extensions.
At the time of writing, JLayout is used by the JHtmlSidebar class to display the submenu and filters found in most backend extensions pages.

JLayout consists in an interface and 2 classes:

* JLayout interface defines escape and render methods, much like the JView class of Joomla! platform
* JLayoutBase implements a basic layout class, where layout may be hardcoded in the class itself for instance
* JLayoutFile, the most commonly used class, wraps and render a layout stored in a file, checking for overrides in template before doing so.

Here is a basic usage example of JLayoutFile:
<source lang="php">// Create a layout object and ask it to render the sidebar
$layout      = new JLayoutFile('joomla.sidebars.submenu', $basePath = null);
$sidebarHtml = $layout->render($data);</source>
Executing this code creates a JLayoutFile object, wrapping a layout file, and passing in a $data structure that may be required for the display itself.

The first parameter, 'joomla.sidebars.submenu' is the file identifier. The last part ('submenu')is the file name, everything before ('joomla.sidebars') is the relative path. An optional $basePath parameter can be prepended to the relative path. If $basePath is missing, layout files will be searched inside the /layouts directory.

Our example:
<source lang="php">new JLayoutFile('joomla.sidebars.submenu', $basePath = null)</source>will result in the 'submenu.php' layout file being loaded from the '/layouts/joomla/sidebars' directory.

Passing in a non-empty base path allows accessing and storing layout files anywhere on the site directory structure, for instance:
<source lang="php">$layout = new JLayoutFile('my_layout', $basePath = JPATH_ROOT .'/components/com_something/layouts');
$html = $layout->render($data);</source>

will load and render the 'my_layout.php' layout file found in  JPATH_ROOT .'/components/com_something/layouts' directory.

Template overrides:
When executing the render() method, that is actually loading the layout file, JLayoutFile will check for the existence of an override in the currently selected template, inside a 'layouts' directory. Looking back at our initial example, should you want to override the sidebar layout of all backend Joomla! extensions, you should place a 'submenu.php' file under:
/administrator/templates/{currently_selected_template}/html/layouts/joomla/sidebars/

Note: JLayoutFile will check the currently selected template for overrides. As layouts can be shared across both front end and backend side, if you need to override a layout file in both cases, you'll have to put an override file in both backend and front end template.

<noinclude>[[Category:Development]][[Category:Tutorials]][[Category:Template Development]]</noinclude>