fuelcms
Download 1.5.2

Learning FUEL CMS PART 1: Creating Pages, Layouts and Blocks

Posted on Dec 09, 2010 by David McReynolds

In Part 1 of this blog series we will cover the basic site structure used for this tutorial and then dive into the building blocks of creating a FUEL website — pages, layouts and blocks. To start, be sure you have read the previous introduction post about the blog series and have downloaded the FUEL CMS 0.91 branch from GitHub.

Site Structure

To help give us some context, let's review the WidgiCorp site structure and how the pages are implemented.

  • Home - static view file with no layout
  • About - static view file that uses the main layout
    • Services - static view file that uses the main layout
    • Team - static view file that uses the main layout
    • What They Say - static view file that uses the main layout
  • Blog - powered by the blog module (fuel/modules/blog)
  • Showcase - contains a static list view and detail view that pulls data from the projects table
  • Contact - uses contact controller (fuel/application/controllers/contact.php)

All the static view file pages above can be imported into the CMS. We will show this in Part 4: Using the CMS.

Creating Pages

Pages are a combination of views, layouts and blocks, and represent a specific URI location (e.g. http://mysite.com/about). They can be either a static view file located in the fuel/application/views folder, or it can be created in the CMS. For the purpose of the first part of this tutorial, we will only be dealing with the static view files. We'll discuss the latter when we get to Part 4: Using the CMS but if you are really wanting to know how to create pages in the CMS you can glean some information from the user guide. The reason we usually create static view files and then import them later is because it's much quicker and more comfortable for us to work in our favorite text editor.

When creating pages, we normally use the Opt-in Controller Development method to create pages. In short, this method maps a URI location to a view file that acts as the body of the page without the need of creating an additional corresponding controller method. We like to use controllers only for processing more complicated logic like submitting forms.

TIP: putting an underscore before your file or folder name tells FUEL to ignore that file/folder when searching for a view to render.

The Home Page

The WidgiCorp homepage HTML can be viewed in the fuel/application/views/home file. Typically, the homepage layout is unique to a website. Therefore, we normally don't use a layout for the homepage and this is the case for the WidgiCorp site. There are a couple of ways to do this in FUEL. The first way is to create a variables file and specify an empty value for the layout like so:

fuel/application/views/_variables/home.php (this page doesn't exist in the demo) 
$vars['layout'] = '';

The second way, and the way we've implemented it with WidgiCorp, is to specify the layout to be a blank variable from within the view file using fuel_set_var() like so:

fuel/application/views/home.php 
<?=fuel_set_var('layout', '')?>

Continuing the examination of the home view file, you'll see that below the <?=fuel_set_var('layout', '')?> there is logic to display the install page which we can ignore. Below the install logic, we simply load the header block file like so (we will talk more about blocks, including the header block, in a bit):

<?php $this->load->view('_blocks/header')?>

Further down, you'll see where we load in the latest blog posts from FUEL. No need for SimplePie here!

<?php $posts = fuel_model('blog_posts', array('find' => 'all', 'limit' => 3, 'order' => 'sticky, date_added desc', 'module' => 'blog')) ?>
<?php if (!empty($posts)) : ?>
<h2>The Latest from our Blog</h2>
<ul>
<?php foreach($posts as $post) : ?>
<li>
	<h4><a href="<?php echo $post->url; ?>"><?php echo $post->title; ?></a></h4>
	<?php echo $post->get_excerpt(200, 'Read More'); ?>
</li>
<?php endforeach; ?>
</ul>

<?php endif; ?>

Lastly, similar to the header, we load the footer block:

<?php $this->load->view('_blocks/footer')?>

The view file named home has special meaning in FUEL and should only be used for the homepage. This can be configured in your fuel/application/config/MY_fuel.php by changing the $config['default_home_view'] configuration parameter.

About Pages

The About section of the WidgiCorp site contains the following sub pages:

  • About - static view file that uses the main layout
    • Services - static view file that uses the main layout
    • Team - static view file that uses the main layout
    • What They Say - static view file that uses the main layout

The About section pages, can be found in the fuel/application/views/ folder. These pages all have the fuel/application/views/_layouts/main.php layout applied to them (along with most of the other pages on the site) and is why you don't see the header and footer in the files. This allows us to keep the view files clean and only include the things that change from page to page.

The What They Say page is slightly different then the others though. It uses the fuel_model() function to include quotes that were entered in the CMS. This is seen at the top of the view file:

application/views/about/what-they-say.php 
<?php $quotes = fuel_model('quotes', array('find' => 'all', 'precedence desc')); ?>

The above retrieves the quotes from the database and then below we loop through them to display the quotes:

<div id="quotes">
<?php echo fuel_edit('create', 'Add Quote', 'quotes'); ?>

<?php foreach($quotes as $quote) : ?>
	<?php echo fuel_edit($quote->id, 'Edit Quote', 'quotes'); ?>
	<?php echo quote($quote->content, $quote->name, $quote->title); ?>
<?php endforeach; ?>
</div>

Another thing to point out here is the use of the fuel_edit() function. This is used to create the inline editing for the page.

Lastly, because this section has sub pages, there is a sub menu on the right side of the page. This will be covered in the Part 2: Creating Menus, but briefly, the $sidemenu variable is created in the views/_variables/global.php file by using the fuel_nav() function.

Showcase Pages

The showcase section is really made up of 2 pages—a list view of projects and a detail view. The list view simply displays all the projects in the showcase. The detail pages are created by passing the project slug as a URI segment. For the detail page to work, we need to explicitly specify the view file to use for all showcase detail pages. To do that, we apply a views variable to all pages with a URI that matches showcase/project OR showcase/project/{project_slug} in the showcase variables file as shown below:

fuel/application/views/_variables/showcase.php 
$vars['blocks'] = array('quote');
$pages['showcase/project$|showcase/project/:any'] = array('view' => 'showcase/project');

The $vars['blocks'] array value specifies which blocks to display for all pages with showcase as the first URI segment.

For more about passing variables to views, click here.

Blog Pages

The blog pages are located in the blog module in the fuel/modules/blog/views/theme/default folder. There you will find the view, layout and block files that you can edit. There are several block files ready for you to use but you can create your own (e.g. twitter, flickr feeds etc) and include them in the side menu by editing the blog layout. Additionally, there is a separate assets/css/blog.css file you can use to style the blog.

For more about the Blog module and creating your own themes, click here.

Contact Page

The Contact page uses the standard controller method to display the page. There is a contact controller that takes the information from the contact form and emails it (you must specify an email address for the $config['dev_email'] parameter in the fuel/application/config/MY_config.php for it to work). The one thing different you may see, is that we use the library Fuel_page to render the page instead of $this->load->view('contact'). This is so we can load in the variable and layout information that may be associated with the page in it's corresponding variables file.

fuel/application/controllers/contact.php 
$page_init = array('location' = 'contact');
$this->load->module_library(FUEL_FOLDER, 'fuel_page', $page_init);
$fuel_page->add_variables($vars);
$fuel_page->render();

For more on creating pages, click here.

Creating Layouts

Layouts are used for commonly structured pages. They are located in the fuel/application/views/_layouts/ folder. By default, FUEL comes with several that you can modify. As explained above, we use the main layout for all secondary pages and no layout for the homepage (since it is one of a kind). Additionally, if you are creating pages in the CMS, which we will discuss in Part 4: Using the CMS, you can create or edit the fields specific to the layout in the fuel/application/config/MY_fuel_layouts.php file (which gets included in the fuel/modules/fuel/config/fuel_layouts.php file and specifies the main layout fields).

Main Layout

Examining the main.php layout file (fuel/application/views/_layouts/main.php), you will see that it simply includes the header and footer static blocks and uses the <?=fuel_var('body')?> to merge in the body variable passed to the page. The body variable is a special variable that will either map to a static page view (if using static layouts) or the layout variable of body (if using the CMS). This variable name can be modified in the FUEL config.

<?php $this->load->view('_blocks/header')?>

	<?php /* RIGHT SIDE WITH SIDE MENU AND BLCOKS */ ?>
	<?php if (!empty($blocks) OR !empty($sidemenu)) : ?>
	<div id="right">

		<?php if (!empty($sidemenu)) : ?>
		<?php echo $sidemenu; ?>
		<?php endif ?>

		<?php if (!empty($blocks)) : ?>
		<div id="blocks">
			<?php foreach($blocks as $block) : ?>

				<div class="block">
				<?php echo fuel_block($block); ?>
				</div>

			<?php endforeach; ?>
		</div>
		<?php endif; ?>

	</div>
	<?php endif; ?>


	<div id="main_inner">
		<?php echo fuel_var('body', ''); ?>
	</div>


	<div class="clear"></div>

<?php $this->load->view('_blocks/footer')?>

To load in the header and footer blocks, we use the standard CodeIgniter $this->load->view(). Alternatively, we could use the fuel_block() function. However, since we don't have plans to make those blocks editable, we leave them as static view files because fuel_block will first check the database for the view data and we don't want to incur that unnecessary overhead.

The fuel_var('body') merges the $body variable in, but allows for a default value as the second parameter if the variable name doesn't exist. Additionally, it will automatically generate the inline-editing code if a user is logged in to FUEL.

Other Layouts

FUEL comes with some other basic layouts for you to take advantage of including a site map and rss feed layout. We will cover using the site map in the next installment when we talk more about navigation structures.

For more about creating layouts, click here.

Creating Blocks

A block is a reusable part of your website that exists on multiple pages. They are located in the fuel/application/views/_blocks/ folder. Blocks can exists as static view files or can be imported later into FUEL (just like pages).

For this tutorial we've created a header, footer, showcase and quote blocks. The showcase block randomly features a single project from the showcase module. The quotes block randomly displays a quote from the quotes module. The header and footer are static view files (as stated earlier), but the featured and quotes block will be later imported into the CMS so the client can manage them (will be discussed in Part 4: Using the CMS). Of all the blocks listed above, the header is the most important so we'll dive into that one to better explain it.

Header Block

The header block is located at fuel/application/views/_blocks/header.php and contains the following:

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en-US" lang="en-US">
<head>
	<?php if (!empty($is_blog)) : ?>
	<title><?=$CI->fuel_blog->page_title($page_title, ' : ', 'right')?></title>
	<?php else : ?>
	<title><?=fuel_var('page_title', '')?></title>
	<?php endif ?>
	<meta charset="UTF-8" />
	<meta name="ROBOTS" content="ALL" />
	<meta name="MSSmartTagsPreventParsing" content="true" />

	<meta name="keywords" content="<?=fuel_var('meta_keywords')?>" />
	<meta name="description" content="<?=fuel_var('meta_description')?>" />

	<?php echo css('main'); ?>
	<?php echo css($css); ?>
	
	<?php echo js('jquery, main'); ?>
	<?php echo js($js); ?>
	
	<?php if (!empty($is_blog)) : ?>
	<?=$CI->fuel_blog->header()?>
	<?php endif; ?>
	<base href="<?php echo site_url()?>" />
	
</head>

<body class="<?php echo fuel_var('body_class', '');?>">
<div id="container">

	<div id="header">
		<a href="<?php echo site_url(); ?>" id="logo">WigiCorp</a>

		<?php echo fuel_nav(array('container_tag_id' => 'topmenu', 'item_id_prefix' => 'topmenu_')); ?>
		
	</div>
	<div id="main">

Using Variables

There are a few things in the header worth discussing. First, note the conditional statement around the page title. This is because we use this same block header file for the blog. Blog page titles are generated by the Fuel_blog class and change depending on where you are in the blog. The Blog module passes an $is_blog variable to all of it's view files, so we can test for that variables existence. Also worth noting, the variable $CI is automatically passed to the static view file and is a reference to the CodeIgniter super object (e.g. get_instance()). In the else part of that condition, the <?=fuel_var('page_title', '')?> merges in the page title variable and will automatically create the inline-editing code for that variable if it later is loaded into the CMS and becomes editable. Similarly, further down, you'll see the fuel_var('meta_keywords') and fuel_var('meta_description'). The fuel/application/views/_variables/global.php file sets the static default values for those variables. If you are using the CMS, you can create a page using a layout that has those variables (e.g. main layout) to edit them for the page.

Using css() and js() Asset functions

Also in the header file, we use the asset helpers css() and js() functions to render the css and javascript tags for our site. We do this for several reasons:

  1. Convenience. It makes for cleaner looking code.
  2. Portability. These functions use the asset paths set in the asset config file
  3. Optimization. We can optimize our assets by specifying the asset_output configuration in the fuel/application/config/asset.php file.

Using a $body_class variable

The last thing we'll point out for the header file is that it's using a class variable for the body tag. This provides us greater flexibility in our CSS allowing us to get more out of a single layout by cascading page styles to manipulate the look without changing the structure of the page. This isn't unique to FUEL of course but is something we use enough that we decided to include it as a variable you can use in your pages.

For more about blocks, click here.

Phew... that's it for Part 1. We covered a lot of ground in this post. We encourage you to join the community, sign up for our newsletter below, and/or follow us on Twitter, to stay informed on the latest FUEL CMS news. Stay tuned for Part 2: Creating Menus next.

Comments have been turned off for this post.


  Back to Top