Theme Class Methods

The Theme class provides theming to your application.

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.

静的 はい
パラメータ
パラメータ デフォルト 説明
$name string
'_default_'
The Theme class instance name.
$config array
array()
The theme instance configuration. Will be ignored if the instance already exists.
返り値 A Theme instance
// 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 はじめに, NOT with the defaults in your configuration file!

静的 はい
パラメータ
パラメータ デフォルト 説明
$config array
array()
The theme instance configuration.
返り値 A Theme instance
// 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.

静的 No
パラメータ
パラメータ デフォルト 説明
$view string
null
The view filename. View file names should be given relative to the theme path.
$data array
array()
array of values
$auto_filter boolean
null
set to true or false to set auto encoding, defaults to main config setting (app/config/config.php)
返り値 A new View object
例外 \ThemeException, when the requested view file could not be found.
// Get the default instance
$theme = \Theme::instance();

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

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

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

Static No
Parameters
Param Type Default Description
$view string
null
The viewmodel name. See the Viewmodel for more information.
$method string
'view'
name of the method in the Viewmodel instance that will be called to process the data prior to rendering the view.
$auto_filter boolean
null
set to true or false to set auto encoding, defaults to main config setting (app/config/config.php)
Returns A new ViewModel object
Throws \ThemeException, when the requested view file could not be found.
Example
// Get the default instance
$theme = \Theme::instance();

/**
 * with the default settings, will load the ViewModel defined in
 * APPPATH.'classes/view/template/homepage.php', using the
 * THEMEDIR.'/template/homepage.php' view file
 */
$viewmodel = $theme->viewmodel('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.

静的 No
パラメータ
パラメータ デフォルト 説明
$path string required The asset requested.
返り値 string
// 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.

静的 No
パラメータ
パラメータ デフォルト 説明
$path string required The path to a folder containing themes.
返り値 void
// 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.

静的 No
パラメータ
パラメータ デフォルト 説明
$paths array required The path to a folder containing themes.
返り値 void
// 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.

静的 No
パラメータ
パラメータ デフォルト 説明
$theme string
null
The name of the active theme to select. If null, it will return the current active theme.
返り値 array
例外 \ThemeException, when the requested theme could not be found.
// 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.

静的 No
パラメータ
パラメータ デフォルト 説明
$theme string
null
The name of the fallback theme to select. If null, it will return the current fallback theme.
返り値 array
例外 \ThemeException, when the requested theme could not be found.
// 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.

静的 No
パラメータ None
返り値 View
// 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 allow you to set the theme template for the page.

静的 No
パラメータ
パラメータ デフォルト 説明
$template string required The name of the theme template view to load.
返り値 View
// 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 allow you to get the view instance of a previously set partial in a named section of your page template.

静的 No
パラメータ
パラメータ デフォルト 説明
$section string required The name of page template section you want to get the partial from.
$view string required The name of view to use for the partial
返り値 View
// 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 allow you to set a view partial for a named section of your page template.

静的 No
パラメータ
パラメータ デフォルト 説明
$section string required The name of page template section you want to add this partial to.
$view string|View required The name of view to use for the partial, or a View object.
$overwrite boolean
false
If false, append the partial to any partials already defined for this section. If true, existing contents will be deleted.
返り値 View
// 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.

Static No
Parameters
Param Type Default Description
$section string required The name of page template section you want to check for defined partials.
Returns Integer
Example
// 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.

Static No
Parameters
Param Type Default Description
$section string required The name of page template section you want to check for defined partials.
Returns Boolean
Example
// 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 allow you to get the view instance of a previously set partial chrome.

静的 No
パラメータ
パラメータ デフォルト 説明
$section string required The name of section you want to get the partial chrome from.
返り値 View
// 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 allow you to define chrome for a partial section of your page template.

静的 No
パラメータ
パラメータ デフォルト 説明
$section string required The name of page template section you want to add this partial to.
$view string|View required The name of view to use for the chome of the partial, or a View object.
$var string
'content'
The name of the variable in the chrome view used to output the partial content.
返り値 View
// 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');

find($theme)

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

静的 No
パラメータ
パラメータ デフォルト 説明
$theme string required The name of the theme to find.
返り値 mixed. Returns the path to the theme if found, or false if not.
// 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.

静的 No
パラメータ None
返り値 array
// 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.

静的 No
Parameters
Param Type Default Description
$enable boolean | string
true
True or a string containing a folder name to enable the feature, false to disable it.
Returns Theme
Example
// 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.

静的 No
パラメータ
パラメータ デフォルト 説明
$theme string
null
The name of the theme.
返り値 array
例外 \ThemeException, when the requested theme could not be found.
// 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.

静的 No
パラメータ
パラメータ デフォルト 説明
$type string
'active'
Whether the active or fallback theme info should be saved.
返り値 boolean
例外 \ThemeException, when the requested theme could not be found.
// 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.

静的 No
パラメータ
パラメータ デフォルト 説明
$var string required The name of the info variable to retrieve.
$default mixed
null
The value to return if the requested $var does not exist.
$theme string
null
The name of the theme whose info file should be searched.
返り値 mixed
例外 \ThemeException, when the requested theme could not be found.
// 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.

静的 No
パラメータ
パラメータ デフォルト 説明
$var string required The name of the info variable to set.
$value mixed
null
The value to set.
$type string
'active'
Whether the variable should be set in the active or fallback theme.
返り値 Theme
// Get the default instance
$theme = \Theme::instance();

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