6.2. テンプレートのカスタマイズ

6.2.1. テンプレートディレクトリ構造

テンプレートディレクトリ構造は template という名前の最上位ディレクトリの下に、インストールされている言語の ディレクトリが作成されています。一つ目のレベルのディレクトリは、 テンプレートの言語が何かを示します。英語の Bugzilla テンプレートは、 ディレクトリ名 en となり、全体としては template/en となります。この template/en には、default ディレクトリがあり、Bugzilla の標準的なテンプレートが入っています。

data/templates も存在しますが、このディレクトリは Template Toolkit が既定のもしくはカスタムのディレクトリを、 それぞれコンパイルしたものを保存する場所ですので、絶対に このディレクトリのファイルは直接編集しないでください。 もし編集したとしても次に Template Toolkit がコンパイルした時に、 全てが失われます。

6.2.2. カスタマイズの方法の選択

Bugzilla のテンプレートを編集する場合、最初にすべき決断は、 実行するためにどうやるのか、ということです。二つの選択肢があり、 主に編集内容がどういうものであるかや、アップグレードプランによります。

一つ目は、直接 template/en/default のディレクトリにあるテンプレートを編集するという方法です。 CVS 経由で Bugzilla をアップデートするのであれば、 この方法がもっとも望ましい方法でしょう。なぜなら、 cvs update を実行した時に、あなたの変更も、 更新されたバージョンに自動的にマージされるからです。

この方法をとった場合、CVS がアップデート中に衝突を検出すると、 衝突したテンプレート (とおそらくサイトのほかの部分も) は衝突を解消するまで動作しないでしょう。

二つ目の方法は、テンプレートを template/en/custom ディレクトリの中に同じディレクトリ構造でコピーし、それを変更するものです。 このディレクトリ内のテンプレートは、自動的に同一の名前の default ディレクトリにあるテンプレートを、 上書きするものとして取り扱われます。

custom ディレクトリは最初から存在するものではなく、 必要であればまず作成する必要があります。

二つ目の方法では、アップグレード時に上書きを行う場合に利用すべきで、 そうでなければあなたの変更はなくなってしまいます。 アップグレードに CVS を利用している場合でも、 主要バージョン変更を行おうとしている場合にはこちらの方が適しています。 このアップグレードにおいても、 このディレクトリの中のファイルは影響を受けないことが保障されており、 あなたのテンプレートを利用し続けるか、もしくは、 新しいバージョンに手作業で変更を統合するかの選択が可能になります。

この方法を利用する場合でも、あなたのサイトは、 テンプレートに非互換の更新が行われた場合に動作しなくなる可能性があります。 そういった変更は、Bugzilla の安定版を利用している場合は、 リリースノートなどに記載されています。もし、開発版を利用している場合は、 変更について前の安定版のリリースノートにある同様の部分に記載されるまでは、 この更新については自分自身で十分に把握しておく必要があります。

どの方式を利用したとしても、 template/en/default ディレクトリの中にある テンプレートを作成・更新した後や、custom ディレクトリ中のテンプレートを更新した際に、 ./checksetup.pl を実行する必要があります。

custom ディレクトリに新しいテンプレートを作成したあと、 必ず ./checksetup.pl を実行してください。この時にエラーが発生していると、 不完全なエラーメッセージが表示されることになります。

6.2.3. テンプレートの編集方法

もし、テンプレートへの編集内容を Bugzilla そのものに反映させようとする場合、 開発者ガイド の関連する部分を読んでください。

Template Toolkit の言語そのものの仕様に関しては、このガイドの範囲ではありません。 現在のテンプレートを参照することで、簡単な部分を把握することは可能でしょう。 もしくは、 Template Toolkit ホームページ にあるマニュアルを参照してください。

特別の注意を払う必要がある部分は、テンプレートに渡されたデータに対する HTML フィルターを適切に行うところです。これは、 データが特別な HTML 文字列を含む可能性がある場合、 たとえば < など、このデータは HTML に導入できないので、 &lt; といったエンティティー形式に変換する必要があります。 このためには Template Toolkit の 'html' フィルターを利用できます。 処理を忘れた場合、あなたのサイトが、 クロスサイトスクリプティング攻撃の影響を受ける可能性があります。

Bugzilla 自身もまたいくつかの Template Tookit 標準にないフィルターを定義しています。たとえば、'url_quote' フィルターは URL として無効もしくは特別な意味を持つ文字、 たとえば & を %26 などのエンコードされた形式へを変換します。 この処理は HTML 特殊文字を含む、ほとんどの文字 (ただし、 文字や数字などの普通の文字を除く) を変換しますので、 HTML フィルターに再度通す必要はありません。

テンプレートの編集は "簡単なカスタムフィールド" としても有用です。 たとえば、ステータスホワイトボードが不要で、"ビルド文字列" のために自由入力フォームが必要な場合、 テンプレートのフィールドラベルを編集することで実現できます。 内部的には status_whiteboard を呼び出してはいますが、 ユーザがそれを知ることはありません。

6.2.4. テンプレート形式と型

いくつかの CGI ではひとつ以上のテンプレートを利用しています。 たとえば、buglist.cgi はそれ自身だけで RDF や二つの形式の HTML (複雑なものと単純なもの) を出力できます。 これを提供しているメカニズムは拡張して利用することが可能です。

Bugzilla は異なる型の出力を行うことができ、 前述のように複数の形式を提供できます。特定の型の要求は、 <cginame>.cgi URL に、 &ctype=<contenttype> (rdf や html など) を付け加えることで行えます。 特定の形式の要求は、URL に &format=<format> (simple や complex など) を付け加えることで行えます。

CGI が複数の形式や型の出力をサポートしているかを判断するには、 CGI を "get_format" で検索してください。存在していなくても、 複数の形式や型のサポートは難しくはありません。config.cgi などの既に行われている CGI を参照してください。

これらをサポートしている CGI に新しい形式のテンプレートを付け加える場合、 CGI が利用する既存のテンプレートを開き、(存在していれば) INTERFACE コメントを参照してください。 このコメントはどのような変数がテンプレートに渡されるかを記述しています。 もし記述がなければ、テンプレートやソースコードを読んで、 取得したい情報がどのように渡されているかを見つける必要があります。

マークアップやテキストなどの必要な形式でテンプレートを記述してください。

あなたのテンプレートでどのような型 (Content-Type) を提供したいかを決定する必要があります。 これらの型は、Bugzilla/Constants.pm の contenttypes 定数で定義されています。 もし、利用したい型がここに存在しなければ、追加してください。 あなたが必要な型につけられている3文字もしくは4文字のタグを覚えてください。 このタグがテンプレートのファイル名の一部となります。

型を追加・変更した後、変更を反映させるために、 Bugzilla/Constants.pm を変更するのがいいでしょう。 また、このファイルはアップグレード時にも、 過去に型をカスタマイズしていた場合はそれらを反映させる必要があります。

テンプレートを <stubname>-<formatname>.<contenttypetag>.tmpl として保存してください。そして、テンプレートの試験のために CGI を <cginame>.cgi?format=<formatname>&ctype=<type> として呼んでください。

6.2.5. 特別なテンプレート

サイトでのカスタマイズの際に特別に興味を持つことになる、 いくつかのテンプレートがあります。

index.html.tmpl: Bugzilla のフロントページです。

global/header.html.tmpl: 全ての Bugzilla のページで利用されるヘッダを定義しています。 ヘッダは、ユーザの目を引き、おそらく編集したくなる、 バナーの部分を含みます。しかしながら、このヘッダには HTML HEAD セクションも含まれており、 これを参考にしてスタイルシートや META タグを追加することも可能です。

global/banner.html.tmpl: "バナー" 本体を含んでおり、全ての Bugzilla ページの先頭部分に表示されます。デフォルトのバナーは単純なものですので、 サイトの特色のある表示に差し替えることとなるでしょう。 いくつかのページに含まれる、Bugzilla バージョン番号は、 どれを実行しているかを示すもので、ユーザにとって、 どのドキュメントを読むべきかを知るのに利用できますので、残しておくべきです。

global/footer.html.tmpl: 全ての Bugzilla のページで利用されるフッタを定義しています。 Bugzilla のサイトを特色のある表示に簡単に変更するために必要な、 もう一つのファイルです。

global/variables.none.tmpl: Bugzilla ではサイトごとに "ブランド" 付けをするために利用できる、 用語のリストを定義しています。この方法により、"bugs" のような用語を Bugzilla 全体で "issues" に変換することが可能になります。 "Bugzilla" の名前や他の単語を変更することができます。

list/table.html.tmpl: このテンプレートは、Bugzilla によるバグリストの表示方法を定義しています。 このテンプレートを利用することで、カラム毎の幅や、タイトル、 各内容の最大表示長さ、長い文の折りたたみ方法を変更することが可能です。 長いバグリストでは、Bugzilla は既定では 100 行ごとに '区切り' を挿入しますが、この動作もこのテンプレートで制御でき、 この値も変更することができます。

bug/create/user-message.html.tmpl: バグ報告ページの先頭部分に表示されるメッセージです。 これを編集することで、ユーザにどのようにバグ報告を行うべきかを伝えられます。

bug/process/midair.html.tmpl: 同じバグに複数のユーザが似たような変更を加えようとした時に利用されるページです。 二人目のユーザが変更した時、一人目がどのような変更を加えたかを表示し、 その変更を上書きするか、もしくはバグに戻ってやり直すかを、 ユーザが選択できるようになります。ページの既定のタイトルとヘッダは、 "衝突が検出されました !" です。もし、航空業界や、 その他のこのメッセージが攻撃的と思える環境 (注: 英語版の直訳は、 "空中衝突検出 !" です) であれば (もちろんそういうことは十分にありえます) このメッセージをより環境にあった他のものに変更することになるでしょう。

bug/create/create.html.tmpl と bug/create/comment.txt.tmpl: Bugzilla でのカスタムフィールドの恩恵を受けたくないと考えている場合でも、 特別なフィールドを利用するのではなく、いくつかの重要な情報を、 バグ報告に含むようにしたいと考えることがあるかもしれません。 バグ登録システムは、ドロップダウンリスト、テキストボックスなど、 自由に HTML ウイジェットを追加できるような拡張性のある設計になっており、 それらに初期コメントとして値を入れることも可能です。 隠しフィールド "format" は、 テンプレートを正常に動作させるためにフォームの中に入れておく必要があります。 この値はテンプレートのファイル名を接頭辞とします。 たとえば、ファイルが create-cust.html.tmpl の場合、

<input type="hidden" name="format" value="cust">

このサンプルには mozilla.org の ガイドつきバグ登録フォーム があります。このコードは、 Bugzilla 配布物の中にサンプルとして含まれています。 create-guided.html.tmpl と comment-guided.html.tmpl です。

この機能を利用するには、enter_bug.cgi 向けのカスタムテンプレートも必要です。ベースとして利用できる、 既定のテンプレートは、 custom/bug/create/create.html.tmpl となります。これを create-<formatname>.html.tmpl とし、 ビルド番号や再現手順など、 収集したい情報それぞれのためのウィジェットを追加してください。

そして、テンプレートを custom/bug/create/comment.txt.tmpl の場所に、 comment-<formatname>.txt.tmpl として置いてください。 このテンプレートでは [% form.<fieldname> %] の形式で、作成したフォームフィールドの値を参照できるようになります。 バグ報告の登録があると、バグ報告につけられる最初のコメントは、 このテンプレートに従ってフォーマットされたものとなります。

たとえば、あなたの enter_bug テンプレートが

<input type="text" name="buildid" size="30">

BuildID: [% form.buildid %]

BuildID: 20020303

6.2.6. Bugzilla をユーザの利用言語を考慮するよう設定する

Bugzilla は Accept: HTTP ヘッダを参照します。 他の言語のテンプレートも導入でき、Bugzilla はあなたが指定した順序に従い、 最適な言語を選択します。さまざまな言語のテンプレートを http://www.bugzilla.org/download.html#localizations から入手できます。 新しい言語の登録方法に関しても上記ページにあります。