Theme 方法 - 类別

优质

小牛编辑

129浏览

2023-12-01

Theme 类别为你的应用程序提供主题。

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

instance 方法扮演一个多例（multiton）。它会回传透过 $name 识别的实例。如果此实例不存在，它会建立一个新的 Theme 实例，使用传递的配置阵列。如果没传递参数，instance 会建立预设的 Theme 实例，使用指定在 theme 设定档中的预设配置。

静态是

参数

参数	类型	预设	描述
`$name`	字串	`'_default_'`	Theme 类别实例名称。
`$config`	阵列	`array()`	主题实例配置。如果该实例已经存在会被忽略。

回传一个 Theme 实例

範例

// 取得预设实例
$theme = \Theme::instance();

// 取得一个自订的实例
$theme = \Theme::instance(
	'custom',
	array(
		'active' => 'custom',
		'view_ext' => '.twig'
	)
);

forge(array $config = array())

forge 方法回传一个新的 Theme 实例。

如果没传递配置，该配置会从全域的配置档案载入。请注意，如果你传递部份的配置，它会与简介所示的预设值合併， 而不是在你配置档案中的预设值！

静态是

参数

参数	类型	预设	描述
`$config`	阵列	`array()`	Theme 实例配置。

回传一个 Theme 实例

範例

// 取得一个 Theme 实例
$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.

这使用 View::forge() 来回传检视。这意味着 Parser 套件也支援定义在主题中的检视。

静态否

参数

参数	类型	预设	描述
`$view`	字串	`null`	检视名称。检视档案名称应该给相对于主题的路径。
`$data`	阵列	`array()`	值的阵列
`$auto_filter`	布林	`null`	设为 true 或 false 来设定自动编码，预设是主要的配置设定（app/config/config.php）

回传一个新的 View 物件

抛出 \ThemeException，在请求的检视档案找不到时。

範例

// 取得预设实例
$theme = \Theme::instance();

// 会带预设设定载入 THEMEDIR.'/template/homepage.php'
$view = $theme->view('template/homepage');

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

presenter 方法载入并回传一个基于所传 $view 字串的 Presenter 物件。它会使用上面记录的 view 方法来传递主题检视到该表现控件。

静态否

参数

参数	类型	预设	描述
`$view`	字串	`null`	表现控件名称。更多资讯见 Presenter。
`$method`	字串	`'view'`	在 Presenter 实例中优先于呈现检视，会被呼叫来处理资料的方法名称。
`$auto_filter`	布林	`null`	设为 true 或 false 来设定自动编码，预设是主要的配置设定（app/config/config.php）

回传新的 Presenter 物件

抛出 \ThemeException，在请求的检视档案找不到时。

範例

// 取得预设实例
$theme = \Theme::instance();

/**
 * 在预设设定，会载入定义在
 * APPPATH.'classes/view/template/homepage.php' 的 Presenter，使用
 * THEMEDIR.'/template/homepage.php' 检视档案
 */
$presenter = $theme->presenter('template/homepage');

asset_path($path)

asset_path 方法回传指向在 $path 中请求的 asset 路径，相对于 DOCROOT。如果配置的 asset 文件夹是一个指向请求 $path 的 URL 会回传 $path。

静态否

参数

参数	类型	预设	描述
`$path`	字串	必要	请求的资产。

回传字串

範例

// 取得预设实例
$theme = \Theme::instance();

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

请注意，每个 Theme 类别实例都有指派一个 Asset 类别实例。如何使用 Asset 类别实例详见进阶页面。

add_path($path)

add_path 方法能让你在执行阶段添加一个主题路径。

静态否

参数

参数	类型	预设	描述
`$path`	字串	必要	指向包含主题文件夹的路径。

回传空

範例

// 取得预设实例
$theme = \Theme::instance();

// 添加 'mythemes' 文件夹到主题搜寻路径
$theme->add_path(DOCROOT.'mythemes');

add_paths(array $paths)

add_paths 方法能让你在执行阶段添加多个主题路径。

静态否

参数

参数	类型	预设	描述
`$paths`	阵列	必要	指向包含主题文件夹的路径。

回传空

範例

// 取得预设实例
$theme = \Theme::instance();

// 添加 'mythemes' 文件夹到主题搜寻路径
$theme->add_paths(
	array(
		DOCROOT.'mythemes'
	),
);

active($theme = null)

active 方法能让你设定活跃主题。它会回传活跃主题的定义阵列。

静态否

参数

参数	类型	预设	描述
`$theme`	字串	`null`	要选择的活跃主题名称。如果为 null，它会回传目前活跃主题。

回传阵列

抛出 \ThemeException，当请求的主题找不到。

範例

// 取得预设实例
$theme = \Theme::instance();

// 设定活跃主题为 'darkglow'，并回传其定义
$active = $theme->active('darkglow');

fallback($theme = null)

fallback 方法能让你设定备用主题。它会回传备用主题的定义阵列。

静态否

参数

参数	类型	预设	描述
`$theme`	字串	`null`	要选择的备用主题名称。如果为 null，它会回传目前备用主题。

回传阵列

抛出 \ThemeException，当请求的主题找不到。

範例

// 取得预设实例
$theme = \Theme::instance();

// 设定备用主题为 'basic'，并回传其定义
$fallback = $theme->fallback('basic');

get_template()

get_template() 方法将回传目前载入主题样板的 View 实例。

静态	否
参数	无
回传	View
範例	`// 取得预设实例 $theme = \Theme::instance(); // 检索目前样板来设定页面标题 $theme->get_template()->set('title', 'This is the page title');`

set_template($template)

set_template 方法能让你为页面设定主题样板。

静态否

参数

参数	类型	预设	描述
`$template`	字串	必要	要载入的主题样板检视的名称。

回传 View

範例

// 取得预设实例
$theme = \Theme::instance();

// 设定页面样板为 subpage 布局，并设定页面标题
$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.

静态否

参数

参数	类型	预设	描述
`$section`	字串	必要	你想要取得局部的页面样板段落的名称。
`$view`	字串	必要	要给局部使用的检视名称

回传 View

範例

// 取得预设实例
$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.

静态否

参数

参数	类型	预设	描述
`$section`	字串	必要	The name of page template section you want to add this partial to.
`$view`	字串｜View	必要	The name of view to use for the partial, or a View object.
`$overwrite`	布林	`false`	If false, append the partial to any partials already defined for this section. If true, existing contents will be deleted.

回传 View

範例

// 取得预设实例
$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.

静态否

参数

参数	类型	预设	描述
`$section`	字串	必要	The name of page template section you want to check for defined partials.

回传整数

範例

// 取得预设实例
$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.

静态否

参数

参数	类型	预设	描述
`$section`	字串	必要	The name of page template section you want to check for defined partials.

回传布林

範例

// 取得预设实例
$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.

静态否

参数

参数	类型	预设	描述
`$section`	字串	必要	The name of section you want to get the partial chrome from.

回传 View

範例

// 取得预设实例
$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')

set_chrome 方法能让你为你页面样板的局部段落定义 chrome。

静态否

参数

参数	类型	预设	描述
`$section`	字串	必要	The name of page template section you want to add this partial to.
`$view`	字串｜View	必要	The name of view to use for the chome of the partial, or a View object.
`$var`	字串	`'content'`	The name of the variable in the chrome view used to output the partial content.

回传 View

範例

// 取得预设实例
$theme = \Theme::instance();

/**
 * 指派 'chrome/roundedcorners' 检视
 * 到目前载入页面样板的 'sidebar' 段落
 * 来给该局部段落一个圆角边框。
 *
 * 在 chrome 检视中，局部输出会输出为 $body；
 */
$theme->set_chrome('sidebar', 'chrome/roundedcorners', 'body');

find($theme)

find 方法会检索定义的搜寻路径来寻找请求的主题。

静态否

参数

参数	类型	预设	描述
`$theme`	字串	必要	要寻找的主题名称。

回传混合。如果找到回传指向主题的路径，或没有是 false。

範例

// 取得预设实例
$theme = \Theme::instance();

// 寻找 'darkglow' 主题
if ($path = $theme->find('darkglow'))
{
	// 该主题可以在 $path 中找到
}
else
{
	// 无法找到主题
}

all()

all 方法回传一个在所有主题路径中的主题阵列，按字母顺序排序。

静态	否
参数	无
回传	阵列
範例	`// 取得预设实例 $theme = \Theme::instance(); // 取回所有安装的主题 $themes = $theme->all();`

use_modules($enable = true)

use_modules 方法启用或停用模组的自动前缀功能。在载入一个主题检视时，如果启用，该检视档案会带有目前活跃模组的名称前缀。如果找不到，它会不带前缀再检查一次，允许来自模组内的全域检视。

静态否

参数

参数	类型	预设	描述
`$enable`	布林｜字串	`true`	True 和一个包含文件夹名的字串来启用该功能，false 以停用它。

回传 Theme

範例

// 取得预设实例
$theme = \Theme::instance();

// 当在 'test' 模组，这会载入主题检视 'test/controller/view'
$info = $theme->use_modules()->set_partial('content', 'controller/view')->use_modules(false);

// 当在 'test' 模组，这会载入主题检视 'modules/test/controller/view'
$info = $theme->use_modules('modules')->set_partial('content', 'controller/view')->use_modules(false);

你可以透过 theme.php 配置档案的 use_modules 键来设定一个全域的预设值。

load_info($theme = null)

load_info 方法回传主题的完整资讯阵列。如果没有指定主题，会回传活跃的主题资讯。

静态否

参数

参数	类型	预设	描述
`$theme`	字串	`null`	主题名称。

回传阵列

抛出 \ThemeException，当请求的主题找不到。

範例

// 取得预设实例
$theme = \Theme::instance();

// 取得 'basic' 主题的资讯阵列。
$info = $theme->load_info('basic');

如果找不到主题资讯档案，这个方法 Throws \ThemeException 如果 require_info_file 设为 true，或回传一个空阵列如果 require_info_file 设为 false。

save_info($type = 'active')

save_info 储存主题资讯阵列的内容回到该主题资讯档案。

静态否

参数

参数	类型	预设	描述
`$type`	字串	`'active'`	应该被储存的活跃或备用主题资讯。

回传布林

抛出 \ThemeException，当请求的主题找不到。

範例

// 取得预设实例
$theme = \Theme::instance();

// 为活跃主题储存资讯阵列
$info = $theme->save_info('active');

如果找不到主题资讯档案，这个方法 Throws \ThemeException 如果 require_info_file 设为 true，或回传一个空阵列如果 require_info_file 设为 false。

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

get_info 方法回传一个来自主题资讯阵列的指定变数。如果没有指定主题，会使用活跃主题的资讯阵列。

静态否

参数

参数	类型	预设	描述
`$var`	字串	必要	要检索的资讯变数名称。
`$default`	混合	`null`	如果请求的 $var 不存在要回传的值。
`$theme`	字串	`null`	应该被搜寻的主题资讯档案名称。

回传混合

抛出 \ThemeException，当请求的主题找不到。

範例

// 取得预设实例
$theme = \Theme::instance();

// 取得 'basic' 主题定义的 color，如果没设定，使用 'blue'
$var = $theme->get_info('color', 'blue', 'basic');

如果你指定一个主题，该值会从主题资讯档案被载入。这是真的，即使指定的主题是目前设为活跃或被动的主题。对于他们来说，不使用载入（并可能修改）的资讯！

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

set_info 方法能让你在活跃或备用主题资讯阵列中设定变数。如果没有指定主题，会使用活跃主题的资讯阵列。

静态否

参数

参数	类型	预设	描述
`$var`	字串	必要	要设定的资讯变数的名称。
`$value`	混合	`null`	要设定的值。
`$type`	字串	`'active'`	无论在活跃或备用主题中，该变数应该被设定。

回传 Theme

範例

// 取得预设实例
$theme = \Theme::instance();

// 设定 fallback 主题的 color 为 blue
$theme->set_info('color', 'blue', 'fallback');