pickles2/px2-multitheme

	Linux	Windows
master
develop

px2-multitheme は、複数のテーマを同時に管理する機能を Pickles2 に追加します。

導入方法 - Setup

Pickles 2 をセットアップします。

composer.json と同階層に移動し、次のコマンドを実行します。

composer require pickles2/px2-multitheme

次に、px-files/config.php に設定を記述します。

$conf->funcs->processor->html = [
	// テーマ
	'theme'=>'tomk79\pickles2\multitheme\theme::exec' ,
];

コンフィグオプション - Config Options

テーマ切り替えのパラメータ名 - param_theme_switch

テーマ切り替えスイッチとして使用するGETパラメータ名を設定します。デフォルトは THEME です。

テーマ名を記憶するクッキー名 - cookie_theme_switch

切り替えたテーマ名を記憶するクッキー名を設定します。デフォルトは THEME です。

レイアウト切り替えのパラメータ名 - param_layout_switch

レイアウト切り替えスイッチとして使用するGETパラメータ名を設定します。デフォルトは LAYOUT です。

テーマコレクションディレクトリ - path_theme_collection

テーマ格納ディレクトリのパスを設定します。相対パスの起点は、.px_execute.php が置かれているパスです。

初期値は ./px-files/themes/ です。

px2-multitheme はこのディレクトリの他にも、vendor ディレクトリにロードされたパッケージの一覧を検索し、theme が実装されたパッケージを選択候補に加えます。

bowl名(コンテンツエリア名)を格納する属性名 - attr_bowl_name_by

Pickles2DesktopTool のGUI編集機能に対応する設定です。Pickles2DesktopTool は、ここに設定した属性の値からbowl名を取得し、GUI編集画面の構成するように振る舞います。デフォルトは data-contents-area です。

デフォルトのテーマID - default_theme_id

デフォルトで適用するテーマのIDです。初期値は default です。

テーマコレクションディレクトリに定義されたテーマを指定する場合は theme_id などの様にディレクトリ名を、composerパッケージからテーマを指定する場合は vendorname/packagename のように、スラッシュで区切られたパッケージ名を設定します。

オプション - options

テーマが個別に定義するオプション値を設定します。設定できるオプションはテーマによって異なります。詳しくは各テーマのドキュメントを参照してください。

コンフィグオプションの実装例 - Config Sample

$conf->funcs->processor->html = [
	// テーマ
	'theme'=>'tomk79\pickles2\multitheme\theme::exec('.json_encode([
		'param_theme_switch'=>'THEME',
		'cookie_theme_switch'=>'THEME',
		'param_layout_switch'=>'LAYOUT',
		'path_theme_collection'=>'./px-files/themes/',
		'attr_bowl_name_by'=>'data-contents-area',
		'default_theme_id'=>'pickles2',
		'options'=>array(
			'pickles2'=>array( // テーマ pickles2 に対するオプション
				'sample_param'=>'hoge' // テーマ側からは、 `$theme->get_option('sample_param')` で受け取ることができます。
			)
		)
	]).')'
];

テーマの実装

各テーマは、テーマコレクションディレクトリの直下にディレクトリとして設置します。例えば、 sample という名前のテーマは、ディレクトリ <theme_collection_dir>/sample/ の中に実装されます。

テーマディレクトリの直下には、 (レイアウト名).html という命名規則で、複数のレイアウトを定義できます。

規定のレイアウトは、 default.html (=デフォルト), popup.html, top.html, plain.html, naked.html があり、サイトマップCSV の layout 列に名前を指定して選択します。この使い方については、Pickles 2 のドキュメントを参照してください。

テーマレイアウトで使える主なAPI

Pickles 2 の API

Pickles 2 が提供するAPIのうち、テーマの実装でよく利用するAPIには、次のものがあります。詳しい使い方は、Pickles 2 の APIドキュメントを参照してください。

$px->href()
$px->mk_link()
$px->conf()
$px->bowl()->pull()
$px->site()->get_current_page_info()
$px->site()->get_children()
$px->site()->is_page_in_breadcrumb()
$px->site()->path_plugin_files()
$px->site()->get_category_top()

px2-multitheme が提供する API

Pickles 2 にある機能の他に、 px2-multitheme の独自のAPIも提供されます。

$theme->get_option()
$theme->get_layout()
$theme->get_attr_bowl_name_by()
$theme->files()
$theme->mk_global_menu()
$theme->mk_shoulder_menu()
$theme->mk_sub_menu()
$theme->mk_megafooter_menu()
$theme->mk_breadcrumb()

theme_files

テーマフォルダの直下にディレクトリ theme_files/ を設置すると、ここにテーマ固有のリソースファイル(画像やCSSなど)を置くことができます。

theme_files に置かれたファイルは、 Pickles 2 の公開キャッシュディレクトリ(デフォルトでは /caches/*) の中に複製が作られ、ブラウザから参照できるようになります。

テーマからこれらのファイルを呼び出す場合、次のように実装してください。

<p>'theme_files/hoge/fuga.png' を呼び出す</p>
<img src="<?= htmlspecialchars( $theme->files('/hoge/fuga.png') ); ?>" alt="" />

テーマパッケージの公開

テーマは、独立したパッケージとして Packagist などで公開できます。

/theme/default.html に、デフォルトのレイアウトをセットしてください。 /theme/ 以下の構成は、テーマコレクションと同じです。

更新履歴 - Change log