FuelPHP，PHP 5.3 框架 简体中文手册

Theme 类別

简介

Theme 类別为你的应用程序提供主題。

一个主題会集合主題樣板（檢視）和資產， 并且允許你透過切換活躍主題來變更应用程序的外表與感覺。

就像模組和套件，主題可以被儲存在多个位置。你可以在配置档案中定義到这些位置的路徑， 或在执行階段把他們添加到主題實例。一个主題是透過它的名稱來識別，必須等於在主題位置中使用的主題文件夾名稱。 如果該主題在多个位置被定義， 第一个找到的会被使用。

Theme 資訊

你可以透過主題資訊档案來为你的主題提供設置。 所有你的主題的該档案有一个固定名稱，它可以透過全域配置档案來配置。 它也有一个让該档案为必要的選項。

資訊档案的格式遵循相同的規則做为正常的配置档案，并支援相同的档案类型。 資訊档案可以包含一个稱为 'options' 的特別段落。選項可以從你的程式码被取得或設定， 可以用來控制你的主題的某些特性，例如使用的顏色，或自訂的 css 档案名稱來選擇一个顏色方案。

在这个時候，資訊档案是唯讀。你可以在执行階段改變，但你不能寫回。

Theme 資產

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.

以下邏輯是用來檢测主題資產档案的位置：

• 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.

如果你想用內建的 Asset 类別支援，你的資產文件夾必須有相容的文件夾結構：/css、/img 和 /js 子文件夾。

Theme 樣板或布局

Theme 與主題樣板或布局協作，他們是定義你頁面布局的檢視档案。

Theme 樣板局部

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 $partial, an array with an entry for each of the partial sections defined. You access a section using it's name. So for a partial section called 'sidebar', you would use echo $partial['sidebar']; in your page template.

局部 chrome

'Chrome' 是 UI 介面設計的術語，用來描述視窗邊框的風格及設計。在 Theme 类別的情境中， 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.

範例：

<?php
class Homepage extends \Controller
{
	/**
	 * 載入主題樣板，設定頁面标題及選单
	 */
	public function before()
	{
		// 載入主題樣板
		$this->theme = \Theme::instance();

		// 設定頁面樣板
		$this->theme->set_template('layouts/homepage');

		// 設定頁面标題（也可以被鍊結到 set_template()）
		$this->theme->get_template()->set('title', 'My homepage');

		// 設定 homepage 導覽選单
		$this->theme->set_partial('navbar', 'homepage/navbar');

		// 为 sidebar 部份定義有圓角窗框的 chrome
		$this->theme->set_chrome('sidebar', 'chrome/borders/rounded', 'partial');

		// 为 homepage sidebar 內容設定局部
		$this->theme->set_partial('sidebar', 'homepage/widgets/login');
		$this->theme->set_partial('sidebar', 'homepage/widgets/news')->set('news', Model_News::latest(5));

		// 呼叫 user 模型來取得登入的使用者列表，傳給 users sidebar 局部
		$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)
	{
		// 如果該 action 沒有回傳 response 物件，
		if (empty($response) or  ! $response instanceof Response)
		{
			// 呈现定義的樣板
			$response = \Response::forge(\Theme::instance()->render());
		}

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

配置

Theme 类別是透過 app/config/theme.php 配置档案進行配置。 一个有以下提及配置的預設配置档案已经存在 fuel/core/config 中。 你可以藉由複製此配置档案到你的应用程序 config 目录，并根據需求修改該档案。

'default'

'default'

array()

'assets'

'.html'

'theme.info'

false

'php'

false

配置範例：

// 在 app/config/theme.php 裡

return array(
	'active' => 'default',
	'fallback' => 'default',
	'paths' => array(			// 在这裡主題档案在 DOCROOT 之外
		APPPATH.'themes',
	),
	'assets_folder' => 'themes',	// 所以这意味著 <localpath>/public/themes/<themename>……
	'view_ext' => '.html',
	'info_file_name' => 'theme.info',
	'require_info_file' => false,
	'info_file_type' => 'php',
	'use_modules' => true,
);
	

一旦你的設定到位，你可以開始使用 Theme 类別。