Layouts
Layouts in FUEL are made up of static content and variable placeholders to be used by your pages. You can use layouts for both your static view files as well as pages you create inside the CMS. Layout files should be placed in the application/views/_layouts/ folder.
Programmatically, you can access information about the layouts through the instantiated Fuel_layouts object like so:
$this->fuel->layouts->options_list(); $this->fuel->layouts->get();
Layouts currently only exist as view files and cannot be changed in the CMS.
Using Layouts for Static View Files
There are a couple ways to assign a layout to a static view file. The first is to assign a view variable with the key of layout in your variables file. The second is to assign a variable of layout using fuel_set_var.
// in your _variables/home.php
$vars['layout'] = 'home';
// or as a page variable in the same file
$pages['home'] = array('layout' => 'home');
// using the fuel_set_var in your view file
<?php fuel_set_var('layout', 'home')?>
The variable $body is is used to hold the contents of the static view file which gets merged into the layout. Because of this, you'll often see fuel_set_var('body', '') in layout files.
Using Layouts in the CMS
For a layout to appear in the FUEL admin, a layout view file must exist in the fuel/application/views/_layouts/ folder AND there must be an entry in the fuel/application/config/MY_fuel_layouts.php file. The latter assigns the variable fields to the layout and signals that the layout can be used to create pages in the admin.
As of version 1.0, there are two ways to assign layouts in the MY_fuel_layouts.php file. The first being the old way of assigning the layout variables to the fields key which is a multi-dimensional array that will be used by Form_builder.
Note that there was a change in version 1.0 that all layout information exists under a single key in the $config['layouts'] array and all fields now exist as a child under the "fields" key.
$config['layouts']['main'] = array(
'fields' => array(
'Header' => array('type' => 'fieldset', 'label' => 'Header', 'class' => 'tab'),
'page_title' => array('label' => lang('layout_field_page_title')),
'heading' => array('label' => 'heading'),
'meta_description' => array('label' => lang('layout_field_meta_description')),
'meta_keywords' => array('label' => lang('layout_field_meta_keywords')),
'Body' => array('type' => 'fieldset', 'label' => 'Body', 'class' => 'tab'),
'body' => array('label' => lang('layout_field_body'), 'type' => 'textarea', 'description' => lang('layout_field_body_description')),
'body_class' => array('label' => lang('layout_field_body_class')),
)
);
Layout Objects
The second, and newer way, is to create a Fuel_layout object and assign the layout variables to it. Additionally, you can assign the label (used for the dropdown in the admin), and the description (used to describe the layout in the admin). For layouts that share common fields, we recommend separating them out and assigning them using the add_fields method which adds multiple fields at once. Note that you must still assign the object to the $config['layouts']['main'] below:
$common_meta = array(
'Meta' => array('type' => 'fieldset', 'label' => 'Meta', 'class' => 'tab'),
'meta_section' => array('type' => 'copy', 'label' => 'The following fields control the meta information found in the head of the HTML.'),
'page_title' => array('style' => 'width: 520px', 'label' => lang('layout_field_page_title')),
'meta_description' => array('style' => 'width: 520px', 'label' => lang('layout_field_meta_description')),
'meta_keywords' => array('style' => 'width: 520px', 'label' => lang('layout_field_meta_keywords')),
);
$main_layout = new Fuel_layout('main');
$main_layout->set_description('This is the main layout used for most of the pages of the site.');
$main_layout->set_label('Main');
$main_layout->add_fields($common_meta);
$main_layout->add_field('Sections', array('type' => 'fieldset', 'label' => 'Sections', 'class' => 'tab'));
$main_layout->add_field('section_description', array('type' => 'copy', 'label' => 'The following fields control the sections of the legal page.'));
$main_layout->add_field('sections', array('display_label' => FALSE, 'add_extra' => FALSE, 'init_display' => 'none', 'dblclick' => 'accordion', 'repeatable' => TRUE, 'style' => 'width: 900px;', 'type' => 'template', 'label' => 'Page sections', 'title_field' => 'title',
'fields' => array(
'sections' => array('type' => 'section', 'label' => '{__title__}'),
'title' => array('style' => 'width: 800px'),
'content' => array('type' => 'textarea', 'style' => 'width: 800px; height: 500px;'),
)));
// !!! IMPORTANT ... NOW ASSIGN THIS TO THE MAIN "layouts"
$config['layouts']['main'] = $main_layout;
What is all this other stuff in the "Sections area"? We added this to the example just to show how complicated you can get with the layouts. The above is using several new features including the addition of the class "tabs" which can be applied to a "type" of "fieldset" and creates tabs for your forms automatically. We are also displaying the new field type of "template", which gives you the power to easily create complicated repeatable forms that you can reorder and nest inside other forms. For more details visit the Form_builder page.
Custom Layout Classes
Occasionally, you may need a layout that does some additional variable processing before being applied to the page. To accomplish this, you can create your own Layout class by extending the Fuel_layout class and modifying the pre_process and/or post_process method hooks. The pre_process method gets passed the array of variables used to generate the page (e.g. formatting of dates). The post_process method gets passed the final rendered output in case you want to do any post rendering of the final output (e.g. appending tracking scripts). You can tell FUEL where to look for the class by specifying file, class, filepath and filename parameters as displayed below:
$config['layouts']['main'] = array(
'class' => 'Main_layout',
'filepath' => 'libraries',
'filename' => 'Main_layout.php',
'module' => 'app',
'fields' => array(
'Header' => array('type' => 'fieldset', 'label' => 'Header', 'class' => 'tab'),
'page_title' => array('label' => lang('layout_field_page_title')),
'heading' => array('label' => 'heading'),
'meta_description' => array('label' => lang('layout_field_meta_description')),
'meta_keywords' => array('label' => lang('layout_field_meta_keywords')),
'Body' => array('type' => 'fieldset', 'label' => 'Body', 'class' => 'tab'),
'body' => array('label' => lang('layout_field_body'), 'type' => 'textarea', 'description' => lang('layout_field_body_description')),
'body_class' => array('label' => lang('layout_field_body_class')),
)
);
Layouts As Their Own Class Files
Similarly, you can overwrite the extended Fuel_layout classes fields() method to return the fields for your layout:
fuel/application/config/MY_fuel_layouts.php$config['layouts']['home'] = array( 'label' => 'Home', 'filepath' => 'libraries/_layouts', 'class' => 'Home_layout', );
fuel/application/libraries/_layouts/Home_layout.php
require_once('Fuel_layout.php');
class Home_layout extends Fuel_layout {
// --------------------------------------------------------------------
/**
* Fields specific to the home page
*
* @access public
* @return array
*/ function fields()
{
$fields = parent::fields($include);
// PUT YOUR FIELDS HERE...
return $fields;
}
// --------------------------------------------------------------------
/**
* Hook used for processing variables specific to a layout
*
* @access public
* @param array variables for the view
* @return array
*/
function pre_process($vars)
{
return $vars;
}
}
Assigning a Different Layout View
By default, FUEL will assume the layout view file is the same name as the layout's key value (e.g. 'main'). To change it, you can assign the layout a different file value:
$config['layouts']['main'] = array(
'file' => $config['layouts_path'].'MY_main_layout',
'class' => 'Main_layout',
'filepath' => 'libraries',
'filename' => 'Main_layout.php',
'fields' => array(
'Header' => array('type' => 'fieldset', 'label' => 'Header', 'class' => 'tab'),
'page_title' => array('label' => lang('layout_field_page_title')),
'heading' => array('label' => 'heading'),
'meta_description' => array('label' => lang('layout_field_meta_description')),
'meta_keywords' => array('label' => lang('layout_field_meta_keywords')),
'Body' => array('type' => 'fieldset', 'label' => 'Body', 'class' => 'tab'),
'body' => array('label' => lang('layout_field_body'), 'type' => 'textarea', 'description' => lang('layout_field_body_description')),
'body_class' => array('label' => lang('layout_field_body_class')),
)
);
Block Layouts
Block layouts are a way to associate layout form fields to particular blocks. This creates a whole new level of layout control for FUEL layouts. For example, you can now create repeatable sections in your layouts that allow you to select the block you want to use and will automatically pull in that block's associated fields. Block layouts are added to the $config['blocks'] and NOT $config['layouts']. Below is an example that creates a block field on a repeatable section. It assumes that you have a page layout of fuel/application/views/_layouts/test.php and a block at fuel/application/views/_blocks/sections/image_right.php:
fuel/application/config/MY_fuel_layouts.php
$test_layout = new Fuel_layout('test');
$test_layout->set_description('This is the test layout field.');
$test_layout->set_label('Test');
$test_fields = array(
'Title/Intro' => array('type' => 'fieldset', 'label' => 'Title/Intro', 'class' => 'tab'),
'h1' => array('label' => 'Heading'),
'Sections' => array('type' => 'fieldset', 'label' => 'Sections', 'class' => 'tab'),
'sections' => array(
'type' => 'template',
'display_label' => FALSE,
'label' => 'Sections',
'add_extra' => FALSE,
'repeatable' => TRUE,
'max' => 4,
'min' => 0,
'title_field' => 'block',
'fields' => array(
'section' => array('type' => 'section', 'value' => 'Section <span class="num">{num}</span>'),
'block' => array('type' => 'block', 'folder' => 'sections'),
),
),
);
$test_layout->add_fields($test_fields);
// Added to the 'layouts' key
$config['layouts']['test'] = $test_layout;
// Fuel layout block
$image_right = new Fuel_block_layout('image_right');
$image_right->set_label('Image Right');
$image_right->add_field('title', array());
$image_right->add_field('content', array('type' =>'text'));
$image_right->add_field('image', array('type' =>'asset'));
// NOTE THIS IS ADDED TO THE 'blocks' key and not the 'layouts' key !!!!
$config['blocks']['image_right'] = $image_right;
fuel/application/views/_layouts/test.php
<?php $this->load->view('_blocks/header')?>
<div id="main">
<div class="wrapper">
<article id="primary">
<?=fuel_var('h1', ''); ?>
<?php foreach($sections as $section) :
// 'block_name' contains the hidden field value that automatically set to the name of the selected block
$block_name = $section['block']['block_name'];
if (!empty($block_name)) :
?>
<?=fuel_block('sections/'.$block_name, $section['block']) ?>
<?php endif; ?>
<?php endforeach; ?>
</article>
</div>
</div>
<?php $this->load->view('_blocks/footer')?>
fuel/application/views/_blocks/sections/image_right.php
<section class="row"> <div class="col_1-3"><img src="<?=img_path($image)?>" /></div> <div class="col_2-3"> <h3><?=$title?></h3> <p><?=$content?></p> </div> </section>
The value saved for block is an array that includes a special value of block_name for the name of the block selected.
Array
(
[title] => My Title
[content] => My Content
[image] => my_image.jpg
[block_name] => image_right
)