FuelPHP, a PHP 5.3 Framework Documentation

Theme クラス

はじめに

Theme クラスは、あなたのアプリケーションにテーマ設定を提供します。

テーマはテンプレート (ビュー) とアセットをグループ化し、アクティブなテーマを切り替える事で、 あなたのアプリケーションのルック・アンド・フィールを切り替える事ができます。

モジュールやパッケージのように、テーマを複数の場所に保存する事ができます。 あなたはこれらのパスをコンフィグファイルに定義するか、実行時にテーマのインスタンスに追加する事ができます。 テーマは名前で識別され、テーマのフォルダ名と同じでなければいけません。 テーマが複数の場所で定義されてる場合、最初に見つかったものが使用されます。

テーマ情報

テーマ情報ファイルで、テーマの設定情報を提供することができます。 このファイルは全てのテーマの固定の名前を持っており、グローバルコンフィグファイルを使用して設定する事ができます。 また、このファイルを必須にするオプションがあります。

テーマ情報ファイルの書式は、通常のコンフィグファイルと同じ書式で、ファイルタイプも同じものに対応しています。 テーマ情報ファイルは「options」とよばれる、特別なセクションを含める事ができます。 options は、 get か set がソースコードより利用でき、 テーマのいくつかの特性、例えば使用する色や、カラースキームを選択するためのカスタムCSSファイル名を操作するのに使用する事ができます。

テーマ情報ファイルは、読み込み専用です。実行時にオプションを変更する事はできますが、変更内容を書き込み保存する事はできません。

テーマアセット

あなたのテーマはアセット (画像、JavaScript、CSSファイル) を持っているでしょう。アセットはブラウザがそれらのファイルをロードできるように DOCROOT の中に配置する必要があります。テーマディレクトリ内にアセットを配置するように選択する事ができ、これは、 DOCROOT の中か、DOCROOT の外か、DOCROOT の中の別のフォルダ内にテーマファイルを持つ必要がある事を意味しています。 CDN を利用する場合など、ベースURLでアセットを指定する事もできます。

次のロジックが、テーマのアセットファイルの場所を決めるために利用されます:

• アセットフォルダが URL である場合、テーマ名がサフィックスとアセットのベース URL として利用されます。
• テーマフォルダが DOCROOT の 中 にあり、コンフィグの assets_folder に設定した名前のフォルダを持つ場合、 これがテーマのアセットのURLになります。
• テーマフォルダが DOCROOT の 中 にあり、 コンフィグの assets_folder に設定した名前のフォルダを持たない場合、 assets_folder は、テーマの名前が追加されるまで、全てのテーマのアセットのルートと仮定されるでしょう。
• テーマフォルダが DOCROOT の 外 にある場合、 assets_folder は、テーマの名前が追加されるまで、全てのテーマのアセットのルートと仮定されるでしょう。

もし標準の Asset クラスを利用したい場合、アセットフォルダは互換性のある /css 、 /img 、 /js サブフォルダ構造である必要があります。

テーマテンプレートかレイアウト

テーマは、ページのレイアウトを定義するビューファイルである、テーマテンプレートかレイアウトと連携します。

テーマテンプレートパーシャル

テンプレートの変数セクションは、テンプレートパーシャルを使用して定義する事ができ、ページのセクションを分割されたビューで構築します。 大規模なアプリケーションの設計では、パーシャルはよく別々のコードで作られ、HMVCの呼び出しからアクセスされます。

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 it's name. So for a partial section called 'sidebar', you would use echo $partials['sidebar']; in your page template.

パーシャルクローム

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

サンプル:

<?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');

		// ホームページナビゲーションメニューをセット
		$this->theme->set_partial('navbar', 'homepage/navbar');

		// 角丸のボーダーのサイドバーセクションを持つchromeを定義
		$this->theme->set_chrome('sidebar', 'chrome/borders/rounded', 'partial');

		// ホームページのサイドバーのコンテンツのパーシャルをセット
		$this->theme->set_partial('sidebar', 'homepage/widgets/login');
		$this->theme->set_partial('sidebar', 'homepage/widgets/news')->set('news', Model_News::latest(5));

		// ログインユーザのリストを取得するためにモデルを呼び出し、ユーザーサイドバーパーシャルに渡す
		$this->theme->set_partial('sidebar', 'homepage/widgets/users')->set('users', Model_User::logged_in_users());
	}

	/**
	 * 簡単な例です。通常のアクションメソッドは、おそらく、モデルからデータを取り出し、
	 * パーシャルビューにこのデータを渡すためのコードを持っているでしょう...
	 */
	public function action_index()
	{
		// ホームページにはFlashイメージのバナーがあります
		$this->theme->set_partial('banner', 'homepage/banner');

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

		// そして、2つのリンクリストとコピーライトのブロック
		$this->theme->set_partial('footerleft', 'homepage/shortcuts');
		$this->theme->set_partial('footercenter', 'homepage/links');
		$this->theme->set_partial('footerright', 'homepage/copyright');
	}

	/**
	 * アクションからのカスタムレスポンスを許容するために、出来る限り標準の after() を維持
	 */
	public function after($response)
	{
		// アクションから返すレスポンスオブジェクトが無い場合
		if (empty($response) or  ! $response instanceof Response)
		{
			// 定義されたテンプレートをレンダリングします
			$response = \Response::forge(\Theme::instance()->render());
		}

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

設定

テーマクラスのコンフィグは app/config/theme.php で設定されています。 デフォルトのコンフィグファイルは fuel/core/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 クラスを使いはじめることが出来ます。