Documentation

Theme class

Introduction

The Theme class provides theming to your application.

A theme will group theme templates (views) and assets, and allows you to change the look and feel of your application by switching the active theme.

Like modules and packages, themes can be stored in multiple locations. You can define the paths to these locations in the configuration file, or add them to the theme instance at runtime. A theme is identified by its name, which must be equal to the name of the theme folder used in one of the theme locations. If the theme is defined in multiple locations, the first one found will be used.

Theme information

You can provide setup information for your theme through the theme information file. This file has a fixed name for all your themes, which can be configured through the global configuration file. It also has an option to make this file required.

The format of an information file follows the same rules as normal configuration files, and supports the same file types. An information file can contain a special section called 'options'. Options can be get or set from your code, and can be used to control certain characteristics of your theme, for example a color used, or a custom css filename to select a color scheme.

At this moment, information files are read-only. You can alter the options at runtime, but you can not write them back.

Theme assets

You theme is likely to have assets (images, javascript or css files). Assets have to be installed inside the DOCROOT so that the browser can load them. You can elect to install the assets inside the theme directory, which implies this has to be inside the DOCROOT, or have the theme files outside the DOCROOT, and the theme assets in a separate folder inside the DOCROOT. Alternatively, you can specify a base URL for your assets, for example if you use a CDN.

The following logic is used to determine the location of the theme asset files:

• If your asset folder is a URL, it is suffixed by the theme name, and used as the base URL for your assets.
• If the theme folder is inside the DOCROOT, and it contains a folder with the name of the configured assets_folder, this will be the URL for all your theme assets.
• If the theme folder is inside the DOCROOT, and it does NOT contains a folder with the name of the configured assets_folder, the assets_folder will be assumed to be the root of all your theme assets, to which the name of the theme will be appended.
• If the theme folder is outside the DOCROOT, the assets_folder will be assumed to be the root of all your theme assets, to which the name of the theme will be appended.

If you want to use the built-in Asset class support, your asset folder must have a compatible folder structure, with /css, /img and /js subfolders.

Theme templates or layouts

The Theme works with theme templates or layouts, which are view files that define the layout of your page.

Theme template partials

The variable sections of the template can be defined using template partials, which are separate views build to provide a section of the page. In larger application designs, partials are often generated by separate code, accessed via HMVC calls.

The contents of a partials section can be accessed through a view variable $partials, an array with an entry for each of the partial sections defined. You access a section using its name. So for a partial section called 'sidebar', you would use echo $partials['sidebar']; in your page template.

Partial chrome

'Chrome' is a term used in UI interface design, and describes the design and styling of a window border. In the context of the Theme class, it is a view that can be used to encapsulate a template partial section, which allows you to style that section independent of the template itself and of the partial output. Chrome will only be generated if there are partials to render. A chrome template will encapsulate a partial section, which may contain multiple partials.

For example, if you have a UI with windows, some of which can be opened and closed, some of which can be moved, and some are static, you can use different chrome templates assigned to each of the template sections representing such a window. Each chrome template contains the HTML and javascript code to achieve the desired functionality. From your application code, you can control the window behaviour by simply assigning the correct chrome template. This can be particularly useful in CMS type applications, where the user can control the behaviour of the UI.

Example:

<?php
class Homepage extends \Controller
{
	/**
	 * load the theme template, set the page title and the menu's
	 */
	public function before()
	{
		// load the theme template
		$this->theme = \Theme::instance();

		// set the page template
		$this->theme->set_template('layouts/homepage');

		// set the page title (can be chained to set_template() too)
		$this->theme->get_template()->set('title', 'My homepage');

		// set the homepage navigation menu
		$this->theme->set_partial('navbar', 'homepage/navbar');

		// define chrome with rounded window borders for the sidebar section
		$this->theme->set_chrome('sidebar', 'chrome/borders/rounded', 'partial');

		// set the partials for the homepage sidebar content
		$this->theme->set_partial('sidebar', 'homepage/widgets/login');
		$this->theme->set_partial('sidebar', 'homepage/widgets/news')->set('news', Model_News::latest(5));

		// call the user model to get the list of logged in users, pass that to the users sidebar partial
		$this->theme->set_partial('sidebar', 'homepage/widgets/users')->set('users', Model_User::logged_in_users());
	}

	/**
	 * A simple example. A normal action method would probably have code to
	 * retrieve data from models and pass this to a partial view...
	 */
	public function action_index()
	{
		// the homepage has a flash image banner
		$this->theme->set_partial('banner', 'homepage/banner');

		// a block of static content
		$this->theme->set_partial('content', 'homepage/content');

		// and two link lists and a copyright block
		$this->theme->set_partial('footerleft', 'homepage/shortcuts');
		$this->theme->set_partial('footercenter', 'homepage/links');
		$this->theme->set_partial('footerright', 'homepage/copyright');
	}

	/**
	 * keep the after() as standard as possible to allow custom responses from actions
	 */
	public function after($response)
	{
		// If no response object was returned by the action,
		if (empty($response) or  ! $response instanceof Response)
		{
			// render the defined template
			$response = \Response::forge(\Theme::instance()->render());
		}

		return parent::after($response);
	}
}
	

Configuration

The Theme class is configured through the app/config/theme.php configuration file. A configuration file with the defaults mentioned below is already present in fuel/core/config. You can override this configuration by copying this config file to your application config directory, and modify that file as needed.

'default'

'default'

array()

'assets'

'.html'

'themeinfo.php'

false

false

Example config:

// Inside app/config/theme.php

return array(
	'active' => 'default',
	'fallback' => 'default',
	'paths' => array(			// theme files are outside the DOCROOT here
		APPPATH.'themes',
	),
	'assets_folder' => 'themes',	// so this implies <localpath>/public/themes/<themename>...
	'view_ext' => '.html',
	'info_file_name' => 'themeinfo.ini',
	'require_info_file' => false,
	'use_modules' => true,
);
	

Once you have your settings in place you can start using the Theme class.