Malaika System

XOOPS Cube テンプレート仕様

Malaika System 早川知道 (Tom_G3X)

2006.3.18

Malaika System

注意事項

• 今後、正式版に向け大幅な仕様変更も充分あり！– これらは、あくまで Xcube 2.1Alpha1 の時点での仕様解説という位置付けです。

– 今後、正式版公開に向け大幅な仕様変更等の可能性も充分にありますので、この内容の永続的な有効性を保障する事は出来ません。

– これらの内容について、取り扱いには充分に注意してください。• 無断転載禁止

– 上記の理由などにより、無断転載は禁止します。– 万が一間違っても、出版物・セミナー等での、利用・参照・引用等は行わないでください。

• 資料中のイラストについて– 資料中のイラストは、 OCEAN-NETのmatchan氏が書かれた画像を承諾をえて使用させていただいております。快く承諾いただいたmatchan氏に心より感謝しております。ありがとうございました。

• XOOP Cube 2.1の最終的な仕様が固まったら、正式なドキュメントを公開する予定です。

Malaika System

Xcubeのテーマ・テンプレート仕様概要

• テーマ・テンプレート全般– Smartyのバージョンアップ– 定数の変数アサイン– オブジェクトの変数アサイン– テーマ・テンプレートでサニタイズする– XOOPS Cube 独自 Smartyプラグインの追加

• 通常表示画面– 従来の systemテンプレートを再構築

• 従来のデザインを継承し、互換性の維持• 管理画面

– テーマ・テンプレート方式に変更– ホールバック・オーバーライド機能の実装– ＣＳＳクラスの指針– ヘルプ機能の実装

Malaika System

Smarty 最新バージョンに

• Smarty 2.6.12 にバージョンアップ– 特に機能追加等はない– 主に、バグフィックス等

XOOPSv2 rc1　～　 XOOPS 2.0.2 Smarty 2.3.0XOOPS 2.0.3　～　 XOOPS 2.0.7.3 Smarty 2.5.0XOOPS 2.0.9　～　 XOOPS 2.0.13a-JP Smarty 2.6.5-dev

XOOPS Cube 2.1 alpha1 Smarty 2.6.12

最新版に更新

Malaika System

定数の変数アサイン

• 言語定数等の変数アサインを多用 $smarty.const– 実は、 XOOPS2.0.3 (Smarty2.0.5) から使えた。– XOOPSの互換性維持の為、従来あまり使われてなかった（知られてなかった）– 従来の変数 ($xoops_url 等 )も使えるので、互換性は維持している。

例 : <{$smarty.const .XOOPS_URL}> は <{$xoops_url}> と同じ （共に使用可能）

言語定数のアサインを簡略化

言語ファイル（言語定数の定義）define(‘_MD_USER_LANG_AVATAR’, “ ”アバター );

実行ファイル（テンプレート変数のアサイン）$xoopsTpl->assign(“lang_avatar”, _MD_USER_LANG_AVATAR);

テンプレート（変数の記述）<{$lang_avatar}>

～今まで一般的だった記述方法～

言語ファイル（言語定数の定義）define(‘_MD_USER_LANG_AVATAR’, “ ”アバター );

テンプレート（変数の記述）<{$smarty.const. _MD_USER_LANG_AVATAR}>

～ XOOPS Cube で多用される記述方法～

Malaika System

オブジェクトの変数アサイン

• オブジェクトの変数アサイン– XOOPS2.0系では、オブジェクトを変数アサイン出来なかった。– XCube2.1では、テンプレートが使われるまでコンパイルを行なわないようにし、オブジェクトを変数アサイン出来るようにした。

テンプレート記述例 : <{$thi sUser->getVar( ‘u id ’)}>

// XOOPS Object でデータ取得$handler =& xoops_gethandler('user');

// Objeact から配列に置換え　　（面倒な処理）(^^ゞ

// 配列をテンプレート変数にアサイン$xoopsTpl->assign(“thisUser”, $thisUser);

Objectをそのままアサイン可能

// XOOPS Object でデータ取得$handler =& xoops_gethandler('user');$this->mObject =& $handler->get($uid);

// Object を直接 テンプレート変数にアサイン$render->setAttribute("thisUser", $this->mObject);

～ XOOPS Cube 2.1 で可能になった～

Malaika System

テーマ・テンプレートでサニタイズ• テーマ・テンプレートでサニタイズする

– セキュリティ対策の為（対 XSSなど）、サニタイズする必要がある。– サニタイズするタイミングは、HTML出力直前。。つまり、テーマ・テンプレート

• escapeモディファイを使用– PHP 関数 htmlspecialchars　と同等– 文字列にHTMLエンティティが含まれる場合、それを無害化。

• 変数には、生の値をアサインする必要がある– Xoopsオブジェクトの getメソッドを利用する。

<{ $object->get(‘xxxx’) }> 　　　　　生値

<{ $object->get(‘xxxx’) | e scape }>　サニタイズ済みの値

変換前 変換後 ------- --------< 　　　　 &lt;> 　　　　 &gt;“ 　　　　 &quot;‘ ‘　　　　　& 　　　　 &amp;

Malaika System

Xcube独自 Smartyプラグイン追加

• XCube 独自追加された Smartyプラグイン– Modifier

• Xoops_user– UserIDから、 xoopsUserObjectのプロパティより必要な情報を返す。

• Xoops_user_avatarize– UserIDから、該当ユーザーアバターのＵＲＬを返す。

• Xoops_date_format– UNIX Timeを、ユーザーのタイムゾーンに変換して返す。 Xoops_getUserTimestamp

• Xoopsformattimestamp– Ｕ NIX Timeを、指定のフォーマットに変換して返す。 formatTimestamp

– Function• Xoops_input

– Input form を出力する。（ value 値のサニタイズも行なわれる）• Xoops_textarea

– textarea form を出力する。 （ value 値のサニタイズも行なわれる）• Xoops_dhtmltarea

– xoopsform の dhtmltarea を表示する。（ value 値のサニタイズも行なわれる）• Xoops_token

– Token用の input form を出力する。• Xoops_pagenavi

– Pagenavi 専用の関数では、簡単に主な関数の説明を・・・

Malaika System

Xoops_input , xoops_textarea

• Xoops_input – Input form を出力する。（ value 値においては、サニタイズも行なわれる）。

使用例： <{xoops_input type= text” value= $object->get(‘name’)” }>“ “

type = text”“ などフォームのタイプを指定する value = サニタイズが自動的に行なわれる。その他、 name , class , size , maxlength , id , default などが指定できる。<input type= text” value= <{$object->get(‘name’)|escape}>” /> “ “ と同じ。

• Xoops_textarea – textarea form を出力する。（ value 値においては、サニタイズも行なわれる）。

使用例： <{xoops_textarea name= name” value= $object->get(‘name’)” }>“ “

value = サニタイズが自動的に行なわれる。その他、 name , class , cols , rows , id , readonly などが指定できる。<textarea name= name”><{$object->get(‘name’)|escape}></textarea> “ と同じ。

追記 : key を追加 (3/15)<{assign name= id” value=$obj->get(‘id’)}> <input type= checkbox” name= hoge[<{$id}>]”>“ “ “<{xoops_input type= checkbox” name= hoge” “ “ key= $obj->get(‘id’) }>

Malaika System

Xoops_dhtmltarea , xoops_token

• Xoops_dhtmltarea– xoopsform の dhtmltarea を表示する。（ value 値においてはサニタイズも行なわれる）

• Xoops_token– Token用の input form を出力する。

<{xoops_dhtmltarea name=description value=$actionForm->get('description')}>

<{xoops_token form=$actionForm}>

<input type= hidden” name= module.user.GroupEditForm.TOKEN” value= ..token“ “ “ 値 .." />

Malaika System

Xoops_pagenavi

• Xoops_pagenavi– PageNavigator 専用の関数

<div class="pagenavi"><{xoops_pagenavi pagenavi=$pageNavi}></div>

pagenavi=$pageNav は、 XCube_PagaNavigator.class.php を前提にしている。

<{ xoops_pagenavi total= 20” current= 3” url="list.php?start= }>“ “ “ という、記述も可能。

Malaika System

デバグ用モディファイ

• モディファイ debug_print_var– デバグ用のモディファイ（ Smartyに標準装備）

– オブジェクトの内容を表示するのに便利– なぜか、配列には使えない (バグ？？ )

– Smartyのマニュアルにも記載されていない

<{ $userObjec t | debug_pr in t_var }>

デバグ出力例：

Malaika System

【通常表示画面】

• 従来の systemテンプレートを再構築– Systemモジュールは、最終的に削除され、機能別に個々のモジュールに独立させる

• （ base(Legacy), user, pm,・・・・などに）

– その為、全て再構築する必要がある• 従来のデザインを継承し、互換性の維持

– 一部、ｈｔｍｌタグや使い勝手の見直しなども行なうが、アップデート時の互換性などを考慮し、出来るだけ、大幅な変更は行なわないつもりです。

Malaika System

【管理画面】

• テーマ・テンプレート方式に変更– ファイルベースのテンプレート– 旧バージョン互換モジュールにも対応

• ホールバック・オーバーライド機能の実装– デザインをカスタマイズする時に一括管理できる

• ヘルプ機能の実装– モジュール毎のヘルプ機能を実装– モジュール毎の標準の付加機能を充実・・・かな？

• (XOOPS Cube 2.1 alpha2 ?? 以降に実装予定か？・・できたらいいなぁ～ )

Malaika System

ホールバック (Fallback)

• デフォルトのテーマ・テンプレート– ユーザー側では、変更等を加えない事を前提とする。– 変更する時は、オーバーライド機能を活用する

• 各モジュール管理画面用テンプレート/modules/ (module_dir) /admin/templates/

/ ＊ .html /icons/ ＊ .gif ( モジュール専用の アイコン等 )

/modules/base/admin/theme//admin_theme.html　 (管理画面用テ－マ

) /style.css 　 　 (管理画面テーマ用 CSS) /icons/ ＊ .gif　　 (管理画面用共通アイコン ) /design/ ＊ .gif　 (テーマ専用画像 )

• デフォルト管理画面テーマ

触っちゃいけない、禁断のディレクトリ～

Malaika System

オーバーライド (Override)

• テーマ・テンプレートを上書きする– 管理画面のテーマ・テンプレートを変更する時に活用する– 変更したテーマ・テンプレートを、 /themes/admin/ 以下で、一括管理可能– /themes/admin/ は、管理画面専用の特殊なテーマ

変更したいテーマ・テンプレートだけを、これらのディレクトリに入れておけば、デフォルトを上書きした状態になり、デザインの変更が容易になる。

/themes/admin/ /admin_theme.html (override 管理画面用テ－マ) /style.css (override 管理画面テーマ用CSS) /icons/ ＊ .gif (override 理画面用共通アイコン ) /design/ ＊ .gif (override テーマ専用画像 )

• テーマ用オーバーライド

/themes/admin/modules/ (module_dir) / / ＊ .html (override 管理画面テンプレート )

• テンプレート用オーバーライド

上書き専用！失敗したら、消そう！　元に戻るよ～

Malaika System

オーバーライドの問題点

• 画像やＣＳＳの相対パスを解決する必要がある(fallback)/admin_theme.html で、 (fallback)/icons/info.gif を表示する時

通常は、こう記述するが・・・・・。

例 : <img src=“<{$smarty.const._XOOPS_URL}>/modules/base/admin/theme/icons/info.gif” />

これらを解決する為、管理画面専用の Smartyモディファイを実装。

管理画面のデザインを変更しよう！そうだ！オーバーライド機能を使おう！！だけど、まてよ？？ハテ？？

info.gif だけを変更したいのに、admin_theme.html も書き換えなければならない・・ ?

style.css を書き換えた時、背景画像のパスも書き換えなければならない・・ ?

困ったもんだぁ～～。やっとれんがやぁ～！

Malaika System

モディファイ theme

• 管理画面専用のモディファイを実装装theme

記述方法： <{ “icons/info.gif” | theme }>

優先順位1.　 /themes/admin/modules/ (module_dir) /icons/info.gif

オーバーライド内の各モジュールの iconsディレクトリ2.　 /themes/admin/icons/info.gif

オーバーライド内の共通 iconsディレクトリ3.　 /modules/ (module_dir) /admin/template/icons/info.gif

各モジュールのテンプレート内の iconsディレクトリ4.　 /modules/base/admin/theme/icons/info.gif

ホールバックディレクトリ

管理画面だけで有効なモディファイである

優先順位に従ってファイルの有無をチェックし、最初に見つかったファイルを表示する。

Malaika System

モディファイ stylesheet

• 管理画面専用のモディファイを実装装stylesheet– スタイルシートにも、オーバーライド機能を適用させる必要がある

記述方法： <{s tyl e shee t f i l e=styl e . c s s}>

優先順位1　 /themes/admin/style.css

オーバーライド内の style.css2　 /modules/base/admin/theme/style.css

ホールバックディレクトリ内の style.css

優先順位に従って CSSファイルの有無をチェックし、最初に見つかった CSSファイルを使用する。

↓/modules/base/admin/css.php より実行

↓CSSの背景画像などの相対パスの問題を解決。特に、相対パスの関係を意識する必要が無くなる

管理画面だけで有効なモディファイである

Malaika System

← ・・・・・・・・・・・・・・・・・・・・　 /modules/base/admin/css.php

StyleSheetについて

• 管理画面の Style.css は特殊だす• システム上、一旦、テンプレートとして扱い/modules/base/admin/css.php　より実行する

– 背景画像の相対パスの問題等• CSS内に、 Smarty変数が使用可能である。

• 背景画像の記述例（ style.css）h2 {color: #666666;background: url(<{ icons/h2bg.g i f "|theme}>“ ) repeat-x;padding-left: 5px;}

こんな記述が出来るのは、管理画面の style.cssだけです。

Malaika System

管理画面 テンプレート指針

• HTML & CSS のコーディング指針– 管理画面全体での統一感のある操作性とデザインをえる事を目的とする

• 従来、モジュール毎に異なったデザインや操作性に戸惑う事もあった– 出来る限り簡単な記述で実現できるように、詳細な（複雑な）指定を

避ける• 新設する CSSクラスは、出来るだけ少なく• モジュール開発者が使ってくれなければ意味が無い• ある程度の自由度も残しておき、これに縛られる事が無いようにしたい。

– 従来の CSS クラスとの互換も維持• XOOPS2.0系モジュールとの CSSの互換も考慮しなければならない。

• テンプレートのパターンを作成– 管理画面のデザインパターンは限られていないか・・？

• 「一覧表示」、「新規登録・編集画面」、「削除画面」– 予めパターンを作っておけば、モジュール開発者が楽できる

• 更に、 cubson での標準主力パターンにしておく

Malaika System

見出し用 HTMLタグ

• h ＊ ( 見出し )タグをテーマとテンプレートで使い分ける– テーマ用に <h1><h2> を割り当てる– テンプレート用に <h3><h4><h5> を割り当てる

h1　テーマ用 （予約タグ）h2　テーマ用 （主に、現在のモジュール名の表示用に使用）

h3　テンプレート用 （管理画面名の表示用に使用する）h4　テンプレート用 （管理画面内の見出し用）h5　テンプレート用 （管理画面内の見出し用）

Malaika System

CSSクラス

• 管理画面はリスト (table)表示が多い ( 既存の CSSクラス )

.adminnavi　各管理画面上部のナビ（バンくずナビ）に使用

.topnavi　　　　リスト表示画面上部の新規リンク等に使用

.tips　　　　　　　管理画面の簡単な説明等の表示に使用

.pagenavi　　　リスト表示画面等のページナビ箇所に使用

• 汎用性の高そうな新規クラスを設置

.outer　　　　　 tableタグに使用　 th　　　　　　　 table内の見出し用.head　　　　　 table内のヘッダー用.odd　 .even　 table内の各 td tr に使用.foot　　　　　　 table内のフッター用

Malaika System

基本フォーマット (ヘッダー )

• 各管理画面テンプレート　ヘッダー<div class="adminnavi"> <a href= ”“ >モジュール名 </a> &raquo;&raquo; <a href= ”“ >管理画面名 </a> <{ * &raquo;&raquo; ....必要に応じて ........ }>*</div>

<h3>管理画面名 </h3>

<div class="tips"> 必要に応じて、簡単なアドバイス等の表示に使用可能</div>

Malaika System

基本フォーマット (リスト )

• 一覧（ list）画面フォーマット<div class= toptab”“ >[<a href= ”“ >新規作成 </a>]</div>

<table class="outer"> <tr> <th> xxxxxx </th> ： </tr><{foreach item=obj from=$objects}> <tr class="<{cycle values='odd,even'}>"> <td> <{$obj->getVar(‘xxxx’)}> </td> ： </tr><{/foreach}></table>

<div class="pagenavi"> <{xoops_pagenavi pagenavi=$pageNavi}></div>

Malaika System

基本フォーマット ( 編集・新規追加 )• 編集・新規登録画面フォーマット

<form xxxxxxxxxxxx > <table> <tr> <th colspan="2">管理画面名 </th> </tr> <tr> <td class="head"> xxxxxx </td> <td class=“<{cycle values= odd,even”}>”“ >xxxxxx</td> </tr> ： <tr> <td colspan="2" class="foot"> xxxxxx </td> </tr></table></form>

Malaika System

管理画面ヘルプ

• 管理画面、モジュール毎にヘルプ機能を実装– 実は、 xoops_version.php にヘルプの定義だけはされていたが、

ほとんど使われてなかった。（ $modversion[‘help’] = “help.html”; ）– それを利用して、 XOOPS Cube 2.1で実装した。

• ヘルプの実装方法– 各 languageディレクトリ内に、 helpファイルを配置し、テンプレートとして扱う。

– 各言語毎に用意する必要がある。– 一般設定と同様に、管理メニューに表示。– ヘルプ内に複数のページ構造を持つ事が可能。

• ヘルプ専用 Smartyモディファイ　 helpurl

Malaika System

ヘルプ専用モディファイ helpurl

• ヘルプ専用 Smarty モディファイ イ helpurl– 複数のヘルプファイルがある時に、別のヘルプファイルへリンクさせる<a href=“<{ ‘xxxx.html’ | helpurl }>” > 次のページ </a>

( /modules/hogehoge/language/japanese/help.html )

Hogehogeモジュールヘルプ・・・・・・・・・・・・・・・・・・・・・・・<a href=“<{ ‘help2.html’ | helpurl }>” >続きは「ヘルプ２」</a>

( /modules/hogehoge/language/japanese/help2.html )

Hogehogeモジュールヘルプ２・・・・・・・・・・・・・・・・・・・・・・・<a href=“<{ ‘help.html’ | helpurl }>” > 「ヘルプ１」に戻る</a>

Malaika System

( /modules/base/admin/templates/help.html )

<div class="adminnavi"> <a href=“ ”・・・・ >モジュール名 </a> &raquo;&raquo; ヘルプ</div><h3> ヘルプ <a href=“ ”・・・・ > ( モジュール名 )</a></h3>

<div c la s s="he lp"><{$content s}></div>

ヘルプ記述ルール

• Helpはテンプレートとして扱う– 元となるテンプレートから、各ヘルプファイルを呼び出す

( /modules/hogehoge/language/japanese/help.html )

<h4>XOOPS 2.0.x 操作移行リスト </h4><ul> <li><a href="<{'xoops2.html'|helpurl}>">こちら </a>をご覧ください </li></ul>

各ヘルプファイルは、<ul><li>などの簡素な形式で記述するのが望ましい。

Malaika System

おしまい

ご参考にしていただければ幸いです御清聴ありがとうございました