Actions

J3.x

Difference between revisions of "Sharing layouts across views or extensions with JLayout"

From Joomla! Documentation

(Add hello world example)
(woopsy)
 
Line 1: Line 1:
{{Version/tutor|3.0}}
+
{{Version/tutor|3.x}}
  
 
It is common that parts of pages are replicated across several views inside an extension, or even across several extensions. Examples might be:
 
It is common that parts of pages are replicated across several views inside an extension, or even across several extensions. Examples might be:
Line 33: Line 33:
 
will load and render the 'my_layout.php' layout file found in  JPATH_ROOT .'/components/com_something/layouts' directory.
 
will load and render the 'my_layout.php' layout file found in  JPATH_ROOT .'/components/com_something/layouts' directory.
  
Template overrides:
+
 
 +
'''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:
 
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/
 
/administrator/templates/{currently_selected_template}/html/layouts/joomla/sidebars/
Line 39: Line 41:
 
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.
 
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.
  
Here is a very simple example.
 
  
 +
'''Storing layouts:'''
 +
 +
Layouts files can basically be stored anywhere, as a full base path can be specified when using them (and still allow template override). However, for consistency and to avoid name clashes, we would recommend the following:
 +
 +
* default to storing layout files in your extension own admin layouts folder. For instance: /administrator/components/com_example/layouts
 +
* if your extension doesn't have an administrative folder (front-end only component, module, plugin), then use a layouts folder such as:
 +
**/components/com_example/layouts
 +
**/plugins/content/example/layouts
 +
**/modules/mod_example/layouts
 +
 +
 +
In addition, note that the folder itself MUST be named '''layouts'''.
 +
Using the root /layouts folder is normally reserved for Joomla! itself, and possibly other "official" applications in the future such as the installer for instance.
 +
Lastly, though not mandatory, I advise you put all your layout files under an additional "com_example" or "mod_example" sub folder inside the main "layouts" folder. This serves no purpose for your extension, however, should a template override layouts for several extensions, this would avoid possible name collisions.
 +
For instance, if 2 extensions use the "filters.search_all" JLayout, then a template cannot provide a separate override for each. A single override will be used for both extension, which may not be desirable.
 +
Using "com_example_1.filters.search_all" and "com_example_2.filters.search_all" allows templates to provide overrides for layouts, even if they have the same id.
 +
 +
'''Examples:'''
 +
 +
Here is a very simple example.
  
 
Create a file, /layouts/joomla/content/helloworld.php:
 
Create a file, /layouts/joomla/content/helloworld.php:
Line 64: Line 85:
 
View an article on the front end and you will see Hello World!.
 
View an article on the front end and you will see Hello World!.
 
Of course often you will want to pass some data via the render() method.
 
Of course often you will want to pass some data via the render() method.
 +
 +
A simple example of that might be:
 +
 +
<source lang="php">
 +
<?php
 +
defined('JPATH_BASE') or die;
 +
 +
?>
 +
<div id="helloworld">
 +
  <h1>Hello <?php echo $displayData['name']; ?>!</h1>
 +
</div>
 +
</source>
 +
(Note that the variable passed in to the layout is called $displayData)
 +
 +
With the corresponding PHP
 +
 +
<source lang="php">
 +
<?php
 +
$layout      = new JLayoutFile('joomla.content.helloworld');
 +
$data = array('name' => 'Bob');
 +
echo $layout->render($data);
 +
?>
 +
</source>
 +
 +
Now when you view your article you should see: Hello Bob!.
 +
  
  
 
<noinclude>[[Category:Development]][[Category:Tutorials]][[Category:Template Development]]</noinclude>
 
<noinclude>[[Category:Development]][[Category:Tutorials]][[Category:Template Development]]</noinclude>

Latest revision as of 02:11, 30 August 2013