Documentation

instance($name = '_default_', array $config = array())

The instance method acts as a multiton. It will return the instance identified by $name. If this instance does not exist, it will create a new Theme instance, using the configuration array passed. If no parameters are passed, instance will create the default Theme instance, using the default configuration specified in the theme config file.

'_default_'

array()

// Get the default instance
$theme = \Theme::instance();

// Get a custom instance
$theme = \Theme::instance(
	'custom',
	array(
		'active' => 'custom',
		'view_ext' => '.twig'
	)
);

forge(array $config = array())

The forge method returns a new Theme instance.

If no configuration is passed, the configuration is loaded from the global configuration file. Note that if you pass a partial configuration, it will be merged with the defaults shown in the introduction, NOT with the defaults in your configuration file!

array()

// Get a Theme instance
$theme = \Theme::forge(array(
	'active' => 'custom',
	'fallback' => 'default',
	'view_ext' => '.html',
));

view($view, $data = array(), $auto_filter = null)

The view method loads a view from the currently loaded theme. It will try to load it from the active theme first. If it doesn't exist in the active theme, and a fallback theme is defined, it will load it from the fallback theme instead. If it can't be found there either, the request is passed to the View class where it follows the normal flow of locating the view file.

This uses View::forge() to return the view. This means that the Parser package is supported for views defined in themes too.

null

array()

null

// Get the default instance
$theme = \Theme::instance();

// will load THEMEDIR.'/template/homepage.php' with the default settings
$view = $theme->view('template/homepage');

presenter($presenter, $method = 'view', $auto_filter = null, $view = null)

The presenter method loads and return a Presenter object based on the $presenter string passed. It will use the view method documented above to pass the theme view to the Presenter.

null

'view'

null

null

// Get the default instance
$theme = \Theme::instance();

/**
 * with the default settings, will load the Presenter defined in
 * APPPATH.'classes/view/template/homepage.php', using the
 * THEMEDIR.'/template/homepage.php' view file
 */
$presenter = $theme->presenter('template/homepage');

asset_path($path)

The asset_path method returns the path to the asset requested in $path, relative to the DOCROOT. If the configured asset folder is a URL to the requested $path is returned.

// Get the default instance
$theme = \Theme::instance();

// will return <img src="/THEMEDIR/assets/img/test.png" />
$img = \Html::img($theme->asset_path('img/test.png'));

Note that to every Theme class instance, an instance of the Asset class assigned. See the advanced page on how the use the Asset class instance.

add_path($path)

The add_path method allows you to add a theme path at runtime.

// Get the default instance
$theme = \Theme::instance();

// add the 'mythemes' folder to the theme search paths
$theme->add_path(DOCROOT.'mythemes');

add_paths(array $paths)

The add_paths method allows you to add multiple theme paths at runtime.

// Get the default instance
$theme = \Theme::instance();

// add the 'mythemes' folder to the theme search paths
$theme->add_paths(
	array(
		DOCROOT.'mythemes'
	),
);

active($theme = null)

The active method allows you to set the active theme. It will return the active theme definition array.

null

// Get the default instance
$theme = \Theme::instance();

// set the active theme to 'darkglow', and return its definition
$active = $theme->active('darkglow');

fallback($theme = null)

The fallback method allows you to set the fallback theme. It will return the fallback theme definition array.

null

// Get the default instance
$theme = \Theme::instance();

// set the fallback theme to 'basic', and return its definition
$fallback = $theme->fallback('basic');

get_template()

The get_template() method will return the View instance of the currently loaded theme template.

// Get the default instance
$theme = \Theme::instance();

// Retrieve the current template to set the page title
$theme->get_template()->set('title', 'This is the page title');

set_template($template)

The set_template method allows you to set the theme template for the page.

// Get the default instance
$theme = \Theme::instance();

// set the page template to the subpage layout, and set the page title
$theme->set_template('layouts/subpage')->set('title', 'Subpage title');

get_partial($section, $view)

The get_partial method allows you to get the view instance of a previously set partial in a named section of your page template.

// Get the default instance
$theme = \Theme::instance();

/**
 * Get the View instance of the 'partials/menu' view in the 'sidebar' section of the
 * currently loaded page template, and assign a variable to it.
 */
$theme->get_partial('sidebar', 'partials/menu')->set('class', 'menu green');

When you get a partial, use the name of the view you used to set it. If you assign the same view to the same section multiple times, the first one will be returned. If you have passed a View instance to set_partial(), you can get it using the number of the partial, prefixed with 'partial_'. Example: you retrieve the second partial using the view name 'partial_2'.

set_partial($section, $view, $overwrite = false)

The set_partial method allows you to set a view partial for a named section of your page template.

false

// Get the default instance
$theme = \Theme::instance();

/**
 * Assign the 'partials/menu' view to the 'sidebar' section of the
 * currently loaded page template.
 *
 * In the template, this partial is echo'd out as $partials['sidebar'];
 */
$theme->set_partial('sidebar', 'partials/menu');

partial_count($section)

The partial_count method returns a count of the number of partials defined for the given section.

// Get the default instance
$theme = \Theme::instance();

// Get the number of partials assigned to the sidebar
$partials = $theme->partial_count('sidebar');

has_partials($section)

The has_partials method allows you to check if a template section has any partials defined.

// Get the default instance
$theme = \Theme::instance();

// Check if we have sidebar partials defined
if ( ! $theme->has_partials('sidebar'))
{
	// some code here to hide the sidebar...
}

get_chrome($section)

The get_chrome method allows you to get the view instance of a previously set partial chrome.

// Get the default instance
$theme = \Theme::instance();

/**
 * Get the View instance for the chrome assigned to the 'sidebar' of the
 * template and assign a variable to it.
 */
$theme->get_chrome('sidebar')->set('title', 'This is a sidebar');

set_chrome($section, $view, $var = 'content')

The set_chrome method allows you to define chrome for a partial section of your page template.

'content'

// Get the default instance
$theme = \Theme::instance();

/**
 * Assign the 'chrome/roundedcorners' view to the 'sidebar' section of the
 * currently loaded page template to give the partial section a border with
 * rounded corners.
 *
 * In the chrome view, the partial output is echo'd out as $body;
 */
$theme->set_chrome('sidebar', 'chrome/roundedcorners', 'body');

set_order($section, $order)

The set_order method allows you to define a custom ordering in which your partial sections will be rendered.

This can be useful if some partials depend on what happens in others, for example if your partials can generate messages, and you have a messages partial which will display them. In this case, you would want to render the messages partial after all others. Sections without a defined order are rendered before all others.

// Get the default instance
$theme = \Theme::instance();

/**
 * Make sure the messages partial is rendered after all others
 */
$theme->set_chrome('messages', 9);

find($theme)

The find method will iterate over the defined search paths to find the theme requested.

// Get the default instance
$theme = \Theme::instance();

// find the 'darkglow' theme
if ($path = $theme->find('darkglow'))
{
	// the theme can be found in $path
}
else
{
	// unable to find the theme
}

all()

The all method returns an array of all themes in all theme paths, sorted alphabetically.

// Get the default instance
$theme = \Theme::instance();

// fetch all installed themes
$themes = $theme->all();

use_modules($enable = true)

The use_modules method enables or disables the prefixing feature for views loaded from a module. If true, the views loaded via the Theme class will be prefixed by the current active module name (if any). If a string is passed, it will be prefixed as well, allowing you to store all modules in a separate directory, to avoid name conficts between module names and non-prefixed view names. If the view can not be found, it's checked again without the prefix, allowing for global views from inside a module. If that doesn't exist either, the View class will be called to load the view the regular way.

true

// Get the default instance
$theme = \Theme::instance();

// when in the module 'test', this will load the theme view 'test/controller/view'
$info = $theme->use_modules()->set_partial('content', 'controller/view')->use_modules(false);

// when in the module 'test', this will load the theme view 'modules/test/controller/view'
$info = $theme->use_modules('modules')->set_partial('content', 'controller/view')->use_modules(false);

You can set a global default value through the use_modules key of the theme.php configuration file.

load_info($theme = null)

The load_info method returns the complete info array for a theme. If no theme is specified, the info of the active theme is returned.

null

// Get the default instance
$theme = \Theme::instance();

// get the information array for the 'basic' theme.
$info = $theme->load_info('basic');

If no theme info file could be found, this method Throws \ThemeException if require_info_file is set to true, or an empty array is returned if require_info_file is set to false.

save_info($type = 'active')

The save_info saves the contents of the theme info array back to the theme info file.

'active'

// Get the default instance
$theme = \Theme::instance();

// save the information array for the active theme.
$info = $theme->save_info('active');

If no theme info file could be found, this method Throws \ThemeException if require_info_file is set to true, or an empty array is returned if require_info_file is set to false.

get_info($var, $default = null, $theme = null)

The get_info method returns a specific variable from the theme info array. If no theme is specified, the info array of the active theme is used.

null

null

// Get the default instance
$theme = \Theme::instance();

// get the color defined the the 'basic' theme, and if not set, use 'blue'
$var = $theme->get_info('color', 'blue', 'basic');

If you specify a theme, the value is loaded from the theme info file. This is true even if the theme specified is currently set as active or passive theme. For those, the loaded (and possibly modified) info is not used!

set_info($var, $value = null, $type = 'active')

The set_info method allows you to set a varaible in the active or fallback theme info array. If no theme is specified, the info array of the active theme is used.

null

'active'

// Get the default instance
$theme = \Theme::instance();

// set the color to blue of the fallback theme
$theme->set_info('color', 'blue', 'fallback');