FUEL CMS User Guide : Version 1.5.2


Pages & Variables

FUEL CMS provides several ways for creating pages. To help illustrate, we'll pretend we are creating a simple website. Our website will have the following pages:

Make sure the configuration of fuel_mode is set to AUTO in the application/config/MY_fuel.php file.

Static Page - home

Opt-In Controller Method

There are several ways to create a page in FUEL. The easest way is to simply create a view file. We call this method the Opt-In Controller Method. This allows you to create pages without the need for a controller. A URI path of about/history would have a view file created at application/views/about/history.php. The method has some extra benefits like having deep path structures and hyphens in the path without the need of routing.

For this tutorial we will open up the application/views/home.php view file and replace the contents of that page with the following:

Hello World

This is our home page

The home view file is reserved as the index page for the site.

Passing Variables to a Page

FUEL provides several ways to pass variables to view files without the need of creating controllers. By default, the $vars array variable in the application/views/_variables/global.php file gets passed to every page created using the Opt-In Controller Method. For this tutorial, we would like add an additional variable to be used on each page called $bigpic. We want this variable to represent the top main picture of the page and change for each section of the site. We add this variable to the application/views/_variables/global.php file as seen below:


// declared here so we don't have to in controller variable files'
$CI =& get_instance();

// generic global page variables used for all pages
$vars = array();
$vars['layout'] = 'main';
$vars['page_title'] = '';
$vars['meta_keywords'] = '';
$vars['meta_description'] = '';
$vars['js'] = '';
$vars['css'] = '';
$vars['body_class'] = $CI->uri->segment(1).' '.$CI->uri->segment(2);

// big pic image at top of the site
$vars['bigpic'] = 'my_bigpic.jpg';

// page specific variables
$pages = array();

We then create an application/views/_variables/about.php variables file and add the following "controller-level" variable which will apply the $bigpic value of about_bigpic.jpg to all pages in the about section, overriding the global variables file:

// big pic image at top of the site
$vars['bigpic'] = 'about_bigpic.jpg';

Note that this page should automatically have a header and footer applied to it when viewed. This is because the application/views/_variables/global.php file specifies the main layout file to be applied to it. Layout files exist in the application/views/_layouts/ folder (more about layouts below as well). Often times you'll see fuel_set_var('body', ''); in a layout. This is because the variable $body holds the contents of the view file (in this case the 'about' page).

Controller Page - contact

FUEL still allows you to create pages using the standard MVC way in CodeIgniter. For the purposes of this tutorial, we will use a controller for the contact because it has a webform we may want to use for processing. We can also leverage the variables specified in the application/views/_variables/ file like so:

class About extends CI_Controller {
	
	function __construct()
	{
		parent::__construct();
	}
	
	function contact()
	{
		// set your variables
		$vars = array('page_title' => 'Contact : My Website');

		//... form code goes here
		$this->fuel->pages->render('contact', $vars);
	}
}

CMS Page - about

For the about page we will login to the CMS by going to http://mysite.com/fuel (where mysite.com is your domain) and entering the username of admin with the password (which is probably admin as well if you haven't changed it). Click on the Pages menu item on the left. For the location value type in about and for the body value, put in the value below, click save and then view the page:

About

This is our about page

Module Page: news

A module page is a combination of a static page and a module that is used to generate the contents of that page. For this example, we will have a news page that will list all the news items and a news detail page that will show the contents of those news items. This requires the following:

SQL Database Table

Run the following SQL statement to create the news table.

CREATE TABLE `news` (
  `id` int(10) unsigned NOT NULL auto_increment,
  `headline` varchar(255) collate utf8_unicode_ci NOT NULL,
  `slug` varchar(255) collate utf8_unicode_ci NOT NULL default '',
  `release_date` date NOT NULL,
  `content` text collate utf8_unicode_ci NOT NULL,
  `link` varchar(255) collate utf8_unicode_ci NOT NULL,
  `published` enum('yes','no') collate utf8_unicode_ci NOT NULL default 'yes',
  PRIMARY KEY  (`id`),
  UNIQUE KEY `permalink` (`slug`)
) ENGINE=MyISAM  DEFAULT CHARSET=utf8 COLLATE=utf8_unicode_ci ;

News Model

The following is the news model we are using. For a tutorial on creating modules specifically click here.

<?php  if (!defined('BASEPATH')) exit('No direct script access allowed');
require_once(FUEL_PATH.'models/Base_module_model.php');

class News_model extends Base_module_model {

	public $required = array('headline');
	public $record_class = 'News_item';
	public $parsed_fields = array('content');
	
	function __construct()
	{
		parent::__construct('news'); // table name
	}

	function list_items($limit = NULL, $offset = NULL, $col = 'release_date', $order = 'desc')
	{
		$this->db->select('id, headline, slug, published');
		$data = parent::list_items($limit, $offset, $col, $order);
		return $data;
	}


	function on_before_clean($values)
	{
		if (empty($values['slug'])) $values['slug'] = url_title($values['headline'], 'dash', TRUE);
		if (!intval($values['release_date'])) $values['release_date'] = datetime_now();
		return $values;
	}

	function form_fields($values = array())
	{
		$fields = parent::form_fields();
		$fields['slug']['comment'] = 'If no slug is provided, one will be provided for you';
		$fields['release_date']['comment'] = 'A release date will automatically be created for you of the current date if left blank';
		return $fields;
	}

	function _common_query()
	{
		parent::_common_query(); // to do active and published
		$this->db->order_by('release_date desc');
	}
}

class News_item_model extends Base_module_record {

	protected $_date_format = 'F d, Y';
	
	function get_url()
	{
		if (!empty($this->link)) return $this->link;
		return site_url('news/'.$this->slug);
	}
	
	function get_excerpt_formatted($char_limit = NULL, $readmore = '')
	{
		$this->_CI->load->helper('typography');
		$this->_CI->load->helper('text');
		$excerpt = $this->content;

		if (!empty($char_limit))
		{
			// must strip tags to get accruate character count
			$excerpt = strip_tags($excerpt);
			$excerpt = character_limiter($excerpt, $char_limit);
		}
		$excerpt = auto_typography($excerpt);
		$excerpt = $this->_parse($excerpt);
		if (!empty($readmore))
		{
			$excerpt .= ' '.anchor($this->get_url(), $readmore, 'class="readmore"');
		}
		return $excerpt;
	}
	
}
?>

MY_fuel_modules.php Configuration Change

Add the following module to the application/config/MY_fuel_modules.php file:

$config['modules']['news'] = array(
	'preview_path' => 'news/{slug}'
);

View File

You could use a controller to do the url segment logic but for this tutorial, we will just use a single view. The following view file uses the fuel_model and custom record objects.

<?php 
$slug = uri_segment(2);
if (!empty($slug))
{
	$news_item = fuel_model('news', array('find' => 'one', 'where' => array('slug' => $slug)));
	if (empty($news_item)) show_404();
}
else
{
	$news = fuel_model('news');
}
?>

News

<?php if (!empty($news_item)) : ?> <?php fuel_set_var('page_title', $news_item->headline); ?> <div class="news_item"> <h2><?=$news_item->headline?></h2> <div class="date"><?=$news_item->release_date_formatted?></div> <?=$news_item->content_formatted?> </div> <?php else: ?> <?php foreach($news as $item) : ?> <div class="news_item"> <h2><a href="<?=$item->url?>"><?=$item->headline?></a></h2> <div class="date"><?=$item->release_date_formatted?></div> <?=$item->get_excerpt_formatted(300, 'Read Full Story »')?> <hr /> </div> <?php endforeach; ?> <?php endif; ?>

Specifying a View for an Individual Record

The last thing that we need to do is tell FUEL to look for a specific view file. Without this configuration, fuel will look for a view file that matches the URI path, which normally doesn't exist (e.g. news/{slug}). There are several ways to do this:

Set max_page_params configuration in MY_fuel.php

The first method is to specify the number of parameters that can be passed to a specific URI location using the "max_page_params" configuration parameter in the fuel/application/config/MY_fuel.php file. The default value is "0" but this can be changed to an array like so:

	$config['max_page_params'] = array('news' => 1);

Set auto_search_views configuration in MY_fuel.php

In the fuel/application/config/MY_fuel.php, set the "auto_search_views" configuration parameter to TRUE:

	$config['auto_search_views'] = FALSE;

News Variables File

Another method is to create a news variables file and use the special variable view to specify the news view file for any page under the news section. This will allow us to use the same view file for both the list view and detail view of the news.

<?php 
$vars['news'] = array('view' => 'news');
?>

Global Variables File

Alternatively, you can specify a variable to the $pages array in the fuel/application/views/_variables/global.php file:

<?php 
$pages['news/:any'] = array('view' => 'news');
?>