トップ 差分 一覧 Farm ソース 検索 ヘルプ RSS ログイン

BugTrack-plugin/286

ページの作成や編集にはユーザ登録が必要です。

レイアウト・プラグイン

  • 投稿者: KG
  • カテゴリ: 新規
  • 優先度: 普通
  • 状態: 提案
  • 日時: 2006年05月02日 23時11分21秒

 内容

※このプラグインをどう説明してよいかちょっと分かりませんが(笑)、以下のようなものです。

当プラグインは、ページデザインを自由に設計する為の物です。様々な(HTML::Template 形式の)テンプレートを用意することで、その表現方法は幅広く広がります。

テンプレート設計時に Layout プラグイン固有の記述方法をヘッダとして埋め込むことで、プラグイン利用時にパラメータを指定できるようになります。パラメータに指定する情報は、入力チェックを追加することもできます。このチェックに利用する情報はテンプレートに正規表現で埋め込みます。

また、テンプレート内には以下のような固有の情報をテンプレート変数として利用できます。

SOURCE            : Wikiソース変換結果(HTMLソース)SOURCE種別(TEXT or WIKI)によって変わります。
LOGIN             : ログイン済みの場合は 1
LOGIN_ID          : ログイン・ユーザーID
LOGIN_TYPE        : ログイン種別(0:管理者, 1:一般)
IS_HANDYPHONE     : 携帯アクセスの場合は 1
IS_FIRST_TMPL     : 同一テンプレート利用で1回目の呼び出し時に 1
IS_FIRST_LAYOUT   : Layoutプラグインの1回目の呼び出し時に 1
COUNT_TMPL        : 同一テンプレートの呼び出し回数(ID属性のカウンターなどに利用)
COUNT_LAYOUT      : Layoutプラグインの呼び出し回数(ID属性のカウンターなどに利用)
CURRENT_TIMESTAMP : 現在時刻(Util::format_date()形式)
SCRIPT_NAME       : スクリプト・パス
CURRENT_PAGE      : 表示中のページ名
FSWIKI_HOME       : FSWIKI ホームURI(例:/fswiki)
FSWIKI_HOME_DIR   : FSWIKI ホームディレクトリ(例:ルートWikiでは '.'、子Wikiでは './..' となる)
SITE_THEME_URI    : テーマディレクトリへのURI
SITE_THEME_NAME   : テーマ名
SITE_TMPL_NAME    : テンプレート名
PATH_INFO         : CGIの PATH_INFO 環境変数値
WIKI_ACTION       : CGIパラメータのactionで指定された名称(アクションなしの場合はブランク)
WIKI_ACTION_...   : ...で指定したアクションがCGIパラメータで指定されているかどうか(1:パラメータあり)
EXIST_PAGE_...    : ...で指定した / を含まないページ名が存在するかどうか(1:存在する)
CGI_PARAM_...     : ...で指定したCGIパラメータの設定値(無ければFALSEになる)?page=xxxx の場合は CGI_PARAM_page に xxx が設定される
CGI_PARAMS_...    : ...で指定した配列要素のCGIパラメータの設定値 ?abc=xxx&abc=yyy の場合は CGI_PARAMS_abc に CGI_PARAM_abc として各値が設定される

これらの情報を利用して、テンプレートを設計することで様々な表現に対応していきます。

EXIST_PAGE_...は、標準のサイトテンプレートで対応されている

<!-- FSWIKI_INCLUDE PAGE="<ページ名>" -->
<!-- TMPL_IF NAME="EXIST_PAGE_<ページ名>" -->〜<!--/TMPL_IF-->

と同じ機能です。

WIKI_ACTION_...は、URIパラメータの action=... に対応しており、action 指定でアクセスされた場合の制御がテンプレートで行えるようになります。

また、管理メニューの「レイアウト変数の設定」で登録した任意のキー/値をテンプレート内で使用できます。

さらに、当プラグインを利用した記述方法に対して別名を管理メニューの「プラグイン別名の設定」登録することにより、短縮名(@<別名>)として利用することも出来ます。

[重要]fswiki 3.6.3 開発版をご利用の方へ 現在ベータ版はありません(2010/11/30)

こちらのサイトにて、fswiki 3.6.3 開発版へ対応したバージョンをベータ版として公開しています。必要な方はご利用ください。

 重要事項

FSWiki 3.6.2以前のバージョンをご利用の方は、このプラグインを利用するには 複数行対応プラグイン を適用する必要があります。

  インストール方法

添付ファイルを解凍し、各ディレクトリに展開してください。また、プラグイン設定画面で layout を有効にしてください。

テンプレートはこちらから...
上記以外のテンプレートはこちらから...

構成

./data         : LayoutHelpのWikiページとサンプルページ
./layout       : Webアクセス可能なリソース用です。アクセス可能である必要があります。
    ├ box     : boxテンプレートが利用するリソース領域です。
    └ rollout : rolloutテンプレートが利用するリソース領域です。
./plugin
    └ layout  : layoutプラグイン本体があります。
./tmpl
    └ layout  : layoutプラグイン用のテンプレートを保管するディレクトリです。

  依存関係

本プラグインでは以下のモジュール内の関数をオーバーライドしています。

  • plugin::info::PluginHelpHandler::do_action()

これらの関数を別のパッチ等で変更を加えている方は、本プラグイン導入後に既存の変更箇所が無効になってしまいますので、本プラグインへパッチ等の変更箇所を適用する必要があります。

  利用方法

このプラグインを利用するには、Layoutプラグイン用のテンプレートを作成する必要があります。標準添付のテンプレート(./tmpl/layout/<テンプレート名>.tmpl)を参考にして、いろんなテンプレートを作成してください。各種テンプレートは ./tmpl/layout ディレクトリ内に設置します。

レイアウト・テンプレートの作成

テンプレートにはヘッダとなる情報を必要とします。以下のような形式になります。下記のソースは div.tmpl のソースの一部です。

<!--TMPL_IF--><!--
-- LAYOUTINFO_START
-- =========================================================================
-- TITLE       : 枠の作成用
-- PARAMETER   : class  , /^([\w_]+)$/
-- PARAMETER   : width  , /^([0-9\.]+)(pt|px|em|%)?$/
-- PARAMETER   : height , /^([0-9\.]+)(pt|px|em|%)?$/
-- PARAMETER   : text   , WIKI
-- SOURCE      : WIKI
-- -------------------------------------------------------------------------
-- HELP_START <= ヘルプ画面に表示する簡単な説明(WIKIフォーマット)
!!! 利用方法
 {{layout div,class:layout_div1,width:50%,text:FrontPage
 〜Wikiソース〜
 }}
-- HELP_END
-- =========================================================================
-- LAYOUTINFO_END
--><!--/TMPL_IF-->
<div <!--TMPL_IF NAME="class"-->class="<!--TMPL_VAR NAME="class"-->"<!--/TMPL_IF--> style="<!--TMPL_IF NAME="width"-->width:<!--TMPL_VAR NAME="width"-->;<!--/TMPL_IF--><!--TMPL_IF  NAME="height"-->height:<!--TMPL_VAR NAME="height"-->;<!--/TMPL_IF-->">
<!--TMPL_VAR NAME="SOURCE"-->
</div>
項目 説明
LAYOUTINFO_START〜LAYOUTINFO_END この範囲内のソースをLAYOUTテンプレートのヘッダとして扱います。これらの前後に<!--TMPL_IF-->〜<!--/TMPL_IF-->と記述してあるのは、HTML::Templateの仕様で出力時に非表示にする為です。
TITLE テンプレートの簡単な説明を1行で記述します。これは、LAYOUTHELPの一覧で表示される説明文となります。
PARAMETER layout プラグイン利用時に指定するパラメータ情報です。最初にパラメータ名で、カンマ,の後に // で囲った正規表現を記述します。この正規表現が入力チェック用となります。
SOURCE SOURCE部の形式(デフォルトではWIKI)を指定します。TEXTを指定した場合は複数行パラメータ部がそのまま適用されます。
HELP_START〜HELP_END LAYOUTHELPで表示される利用方法等を記述したヘルプ部です。通常はWiki形式で記述します。HTML形式で記述する場合は、HELP_START 部を HELP_START:HTML というように指定します。
LAYOUT_END以降 ここ以降がテンプレート部となります。
注意点

SOURCEパラメータ部において TEXTを指定する場合には <!--TMPL_VAR 'SOURCE' ESCAPE='HTML'--> というようにESCAPE属性を付加しておかないと、「誰でも編集できる」ような公開サーバー上では危険です。アクセスが制限されたイントラネット上においては、HTMLをそのまま記述できることもあり自由度が増して利便性も上がると思われます。

layoutプラグインの利用方法

上記、テンプレートを例にした場合

{{layout div,class:area1,width:200px
!! サンプル
これはサンプルです
}}

ブロックプラグイン内のソース部が、テンプレート内の <!--TMPL_VAR NAME="SOURCE"--> の位置に挿入されます。

ソース部を必要としないようなテンプレートを利用する場合。例えば、特定の文字列やタグの出力などを定義したテンプレートをそのまま出力する場合は以下のような形式も可能です。

{{ilayout br}} ← <br>タグを出力するテンプレートなど

また、ソースを利用しないテンプレート内にパラメータで指定した文字列等を利用するテンプレートの場合は以下のような記述も出来ます。

{{ilayout h2,text:見出し}} ← <h2><!--TMPL_VAR NAME="text"--></h2>が記述されたテンプレートなど

パラメータキー無しで利用する手法

通常は上記のように 「-- PARAMETER : キー,チェック条件」でパラメータを記述し、記述には {{ilayout tmplate,key1:val1,key2:val2,...}}というように使用しますが、以下のように $n で指定することによって、パラメータのキーを指定せずに値のみ記述できるようになります。

-- PARAMETER   : $1   , /^([\w_]+)$/
-- PARAMETER   : $2   , /^([\w_]+)$/
{{ilayout tmplate,val1,val2,...}}

$n の n の部分はそれぞれパラメータの順序番号になります。$n の利用は、通常の key,val の指定方法と組み合わせて利用することも出来ます。

-- PARAMETER   : $1   , /^([\w_]+)$/
-- PARAMETER   : $2   , /^([\w_]+)$/
-- PARAMETER   : text   , WIKI

別名を利用した効果的な利用方法

付属の LayoutAlias プラグインを効果的に利用することで、layoutプラグインを既定のパラメータを定義した別名を登録して簡易的に利用することが出来ます。

別名の登録は、./config/layoutalias.dat ファイルに記述します。標準添付する layoutalias.dat には、幾つか既に登録済みとなっています。記述方法は以下の通りです。

@別名=<プラグイン名>    <パラメータ部> ← <プラグイン名>と<パラメータ部>の区切り文字はタブです。

これを、レイアウトプラグインで利用する場合は以下のようにして利用します。

@別名=[layout or ilayout]    <テンプレート名>,パラメータ,...

例えば...roll というテンプレートを利用した場合、通常は以下のように記述します

{{layout roll,text:サンプル
〜Wikiソース〜
}}

で、以下の別名を定義しておけば...

@roll=layout    roll

次のように短縮して利用できます。

{{@roll text:サンプル
〜Wikiソース〜
}}

パラメータの順序は別名定義のパラメータが優先され、プラグイン利用時のパラメータは後に追加されます。この為、パラメータの順序さえ考慮すれば他のプラグインの別名登録も可能です。layoutプラグインの場合、第一パラメータのみテンプレート名固有となり、後のパラメータは順序が関係なく利用できますので、プラグインで指定したパラメータが別名登録のパラメータと同一の場合は上書きされるということになります。(別名登録のパラメータを既定値として利用できます)

  補足事項

このプラグインの説明としては、上記項目だけでは不十分なのですが、全ての機能を説明するとかなり長くなりそうなので、ここまでとします。なお、テンプレートを記述する為に必要な知識として HTML::Template モジュールを理解する必要がありますが、これは標準のサイトテンプレートにも必要な知識なので説明を省いていますが、簡単に説明すると以下のようになります。

HTML::Template モジュール特有の記述方式

基本的な設計要素は以下の通りです。以下の記述方法以外にも幾つかありますが、詳しくは HTML::Templateモジュールの説明を参照してください。

<!--TMPL_IF NAME="変数"-->〜1〜<!--TMPL_ELSE-->〜2〜<!--/TMPL_IF-->
これは、変数の値が真であれば 〜1〜 の部分を表示し、偽であれば 〜2〜 の部分を表示します。
<!--TMPL_UNLESS NAME="変数"-->〜<!--TMPL_ELSE-->〜2〜<!--/TMPL_UNLESS-->
これは、変数の値が偽であれば 〜1〜 の部分を表示し、真であれば 〜2〜 の部分を表示します。
<!--TMPL_VAR NAME="変数"-->
変数の値を表示します。

FSWiki特有の記述方法

変数 EXIST_PAGE_<ページ名>
<ページ名>があるかどうかの判断に利用します。TMPL_IF or TMPL_UNLESSと一緒に利用します。
<!--FSWIKI_INCLUDE PAGE="<ページ名>"-->
<ページ名>で指定したページの変換結果を挿入します。
<!--FSWIKI_SOURCE-->〜WIKIソース〜<!--/FSWIKI_SOURCE-->
〜WIKIソース〜で指定したWIKI形式の書式の変換結果を挿入します。
<!--FSWIKI_HEAD_INFO-->〜ソース〜<!--/FSWIKI_HEAD_INFO-->
〜ソース〜で指定したテキスト(javascriptなど)を<HEAD>タグに挿入します。

  ライセンス

GPLです。

  サンプル

この辺で、当プラグインの最新情報とサンプルを見ることが出来るかもしれません。

  テンプレート募集

当プラグインで利用するテンプレートを募集します。実用的なものや、面白いものなどを作成された方は、レイアウト・テンプレートの投稿 ページより是非投稿してください。

  変更履歴

テンプレートは別ファイルに添付しています。

2006/05/02 - layout_20060502.zip(769)
  • 新規投稿
2006/05/06 - 置換え
  • fontsize,fontcolorテンプレートを修正しました。
  • fontテンプレートの追加しました。
2006/05/19 - layout_20060519.zip(753)
  • WIKI書式パラメータへの対応しました。
  • パラメータ値に":"を含む場合、正しく取得できないバグを修正しました。
2006/07/10 - layout_20060710.zip(734)
  • パラメータ名にハイフン"-"が指定できるようにしました。
  • font.tmpl を更新し、かなりのテキスト属性をサポートしました。
2006/09/13 - layout_20060913.zip(744), layout_tmpl.zip(848)
  • キーなしで値のみのパラメータ指定に対応しました。
  • PATH_INFO を追加しました。
  • WIKI_ACTION_... を追加しました。
  • 管理画面で登録した任意のキー/値を利用できるようにしました。
  • プラグイン別名設定用ファイル(layoutalias.dat)の設定用管理画面を作成しました。
  • レイアウト・テンプレートの配布用ZIPファイルを分割しました。
2007/01/26 - layout_20070126.zip(724)
  • テンプレート変数 FSWIKI_HOME_DIR を追加しました。
  • テンプレート変数 CGI_PARAM_xxxx としてCGIパラメータ xxxx を取得できるようにしました。
  • <!--FSWIKI_SOURCE-->〜WIKIソース〜<!--/FSWIKI_SOURCE-->として記述したWIKIソースを変換できるようにしました。
  • <!--FSWIKI_INCLUDE PAGE=xxxx-->で指定するページの / なし制限を外しました。
2007/04/16 - layout_20070416.zip(752)
  • テンプレートのヘッダ部に SOURCE種別(WIKI or TEXT)を指定できるようにしました。
    • TEXTを指定している場合は複数行内のソースがそのまま出力されます。(公開サーバーでの利用時には注意してください。)
2008/02/29 - layout_20080229.zip(864)
  • <!--FSWIKI_HEAD_INFO-->〜ソース〜<!--/FSWIKI_HEAD_INFO-->として記述したソースをHEADタグ内に挿入することが出来るようにしました。
  • 上記機能追加に伴うテンプレートファイルの修正 - layout_tmpl_20080229.zip(1006)
2010/11/30 - layout_20101130_fswiki362.zip(321), layout_20101130.zip(380)
  • CGI_PARAM_xxxのテンプレートキー設定に関するバグ修正
2013/03/07 - layout_20130307_fswiki362.zip(209), layout_20130307.zip(290)
  • テンプレート内で定義したパラメータ変数の値をUtil::url_encode()でエンコードした値を「変数名#url」で取得できるようにした。
    • 上記対応はFSWiki標準の添付ファイルが"."もエンコードしてしまう事に対応するためです。

 コメント

  • 幾つかのテンプレートのバグを修正しました。新たに font テンプレートを追加しました。 - KG (2006年05月06日 17時56分41秒)
  • レイアウト・テンプレート募集を開始しました。 - KG (2006年05月18日 01時31分28秒)
  • WIKI書式パラメータ(1行)へ対応しました。 - KG (2006年05月19日 21時24分08秒)
  • パラメータ名にハイフン"-"が指定できるようにしました。また、font.tmpl を更新して、かなりのテキスト属性をサポートしました。 - KG (2006年07月10日 20時40分03秒)
  • いくつかの機能を追加しました。詳細は上記履歴をご覧ください。 - KG (2006年09月13日 19時46分24秒)
  • いくつかの機能を追加しました。詳細は上記履歴をご覧ください。 - KG (2007年01月26日 21時02分44秒)
  • いくつかの機能を追加しました。詳細は上記履歴をご覧ください。 - KG (2007年04月18日 13時52分08秒)
  • 今回の機能追加と共に「dp.SyntaxHighlighter でソースコードに色付けするテンプレート」も公開しました。興味のある方はご利用ください。 - KG (2007年04月18日 13時55分46秒)
  • BBS-サポート掲示板/797 にて指摘のあった部分を修正しています。 - KG (2008年02月29日 11時02分32秒)
  • お忙しい中失礼致します。設置してみたのですが、テンプレートファイルを見失っているらしく「テンプレート(indent)が見つかりません」と出るので、質問させて下さい。設置位置ですが、『構成』の.(ピリオド)は、wiki.cgiがあるディレクトリで合っておりますか?もし僕の解釈が違うようでしたら正しい設置位置をお教え願えますでしょうか。FSWiki3.6.3正式版+Layoutプラグイン3.6.3用β+複数行対応プラグイン3.6.3用β で運営しています。 - 里井 (2009年06月15日 16時35分32秒)
  • 合ってます。ページ内に{{layouthelp}}と記述すれば、使用可能なテンプレート一覧が表示されるはずですが、どうでしょうか? - KG (2009年06月15日 17時52分47秒)
  • お忙しい中、ご返答ありがとうございます。 が、ページ内に{{layouthelp}}を記載してみたものの、全く使用可能なテンプレが出てきません(編集画面下に出るヘルプも同じ状態です); 作ったページは http://sena-s.mydns.jp/wwwiki/wiki.cgi/SatoiWrite?page=testlayouts です。 いわゆる子Wikiですが、親Wikiもプラグインは有効にしてあります。そしてレイアウト用テンプレートファイルは全て、./tmpl/layoutに入れています…なのに表示もされません。 - 里井 (2009年06月16日 10時09分41秒)
  • まずは、layoutディレクトリおよびlayoutテンプレートファイルへのアクセス権限があるかどうかを調べてください。(←こっそり覗いてみましたが、これが一番怪しそうです。) - KG (2009年06月16日 10時35分31秒)
  • アクセス権を確認したところ、/tmpl/layoutディレクトリに実行権限がなかったので、付与して確認したら正しく表示されました(最初の2つは表示されないのが正解です)。 今ではレイアウトヘルプも表示されるようになりました。 おつきあい頂きまして本当にありがとうございました、そしてこんな原因に気付けず時間貰ってしまって、ごめんなさい; - 里井 (2009年06月16日 11時36分35秒)
  • CGI_PARAM_xxx のテンプレートキー設定に関するバグを修正しました。 - KG (2010年11月30日 12時00分08秒)
  • 久しぶりに機能追加しました。サイトに添付したファイルのエンコード方式への対応になります。ついでにFLV Playerテンプレートをひとつ追加しました。 - KG (2013年03月07日 21時07分37秒)
お名前: コメント: