Context Navigation

← Previous Change
Wiki History
Next Change →

Changes between Version 2 and Version 3 of TracReports

Timestamp:: 12/07/15 15:40:17 (9 years ago)
Author:: trac
Comment:: --

Legend:

: Unmodified
: Added
: Removed
: Modified

TracReports

-                      v2
+                      v3
+** Note: このページは、Tracのバージョン1.0を文書化しています、旧バージョンが必要であれば、[[0.12/TracReports]]を参照してください **
 = レポート = #TracReports
 [[TracGuideToc]]
 …
 この機能によって、 Trac データベースのチケット情報を取得することができます。
 TracReports ではレポートの形式を定義するための方法として、独自フォーマットではなく、
+TracReports ではレポートの形式を定義するための方法として、独自フォーマットではなく、
 SQL の `SELECT` 文を使用することにしました。
 …
  * '''ID''' — ユニークな (連番の) 識別子
  * '''レポート名 (Title)''' — レポートのタイトル
  * '''説明 (Description)''' — WikiFormatting で記述された、レポートの説明。
  * '''レポート本体 (Report Body)''' — 後に述べるフォーマットで規定された、レポートクエリの結果。
  * '''フッタ (Footer)''' — レポート本体を異なる形式でダウンロードするためのリンク。
+ * '''説明 (Description)''' — WikiFormatting で記述された、レポートの説明
+ * '''レポート本体 (Report Body)''' — 後に述べるフォーマットで規定された、レポートクエリの結果
+ * '''フッタ (Footer)''' — レポート本体を異なる形式でダウンロードするためのリンク
 == ソートの並び順変更 == #ChangingSortOrder
 …
 ''カスタムレポートを作成するためには、 SQL を楽に書ける程度の知識が必要です。''
+'''Note: レポートの追加、編集ボタンを表示させるためには [TracPermissions#Reports permissions] をセットアップする必要があります。'''
 レポートは基本的に、 Trac が実行できる形式の、名前がついた特定 SQL です。
 レポートに指定された SQL は、直接 Web インタフェースから閲覧したり、
 作成したりできます。
 通常のレポートは、 'ticket' 表に対する、カラムの選択や、ソート指定を伴った
+通常のレポートは、 'ticket' 表に対する、カラムの選択や、ソート指定を伴った
 SELECT 文となります。
 …
 例: '''優先度順、登録日時順の全未解決チケット'''
 {{{
 SELECT id AS ticket, status, severity, priority, owner,
        time AS created, summary FROM ticket
+SELECT id AS ticket, status, severity, priority, owner,
+       time AS created, summary FROM ticket
   WHERE status IN ('new', 'assigned', 'reopened')
   ORDER BY priority, time
 }}}
----
 == 上級トピック: 動的変数の使用 == #AdvancedReports:DynamicVariables
 …
 実用的なレポートにするために、自動的に値が設定される動的変数が用意されています。(URL で指定されると上書かれます)
  * $USER -- ログインに使用したユーザ名。
+ * $USER -- ログインに使用したユーザ名
 例 (''私が担当になっているチケット一覧''):
 …
 }}}
-----
 == 上級トピック: 表示形式のカスタマイズ == #AdvancedReports:CustomFormatting
 Trac には、レイアウトのカスタマイズや、グルーピング、ユーザ定義の CSS 利用などによる
 もっと複雑なレポートの作成も可能です。このようなレポートを作成するには、
+もっと複雑なレポートの作成も可能です。このようなレポートを作成するには、
 Trac のレポートエンジンが出力を制御するためのステートメントを含む、特別な SQL を使用します。
 == 特別なカラム == #SpecialColumns
+=== 特別なカラム === #SpecialColumns
 レポートを整形するため、 TracReports はクエリの結果から '特定の' カラム名を
 探します。このような '特定の' 名前で、最終的なレポートのレイアウトやスタイルが
 …
 === 自動的に整形されるカラム名 === #Automaticallyformattedcolumns
  * '''ticket''' — チケットの ID が入っているカラムで使用します。該当する ID のカラムにハイパーリンクされます。 (訳注: `summary` というカラム名もチケットにハイパーリンクされます。日本語版では `概要` でもリンクします。)
  * '''id''' — '''realm''' が指定されない場合は、 '''ticket''' と同じです。
  * '''realm''' — '''id''' と同時に使用します。チケット以外のリソースにリンクを行う場合に使用します。 (e.g. ''wiki'' のレルムに ''id'' としてページ名を組み合わせると、 Wiki ページへのリンクを生成します)
  * '''created, modified, date, time''' — 日付や時刻に整形されます。 (訳注: `datetime` という列名にすると日時で整形されます。日本語版では `時刻` で終わるカラムは `time` に、 `日付` で終わるカラムは `date` に、 `日時` で終わるカラムは `datetime` に、それぞれ整形されます。)
  * '''description''' — チケットの説明が入っているカラムで使用します。 Wiki エンジンで処理されます。 (訳注: 日本語版では `説明` でも整形されます。)
+ * '''ticket''' — チケットの ID が入っているカラムで使用します。該当する ID のカラムにハイパーリンクされます (訳注: `summary` というカラム名もチケットにハイパーリンクされます。日本語版では `概要` でもリンクします)
+ * '''id''' — '''realm''' が指定されない場合は、 '''ticket''' と同じです
+ * '''realm''' — '''id''' と同時に使用します。チケット以外のリソースにリンクを行う場合に使用します(e.g. ''wiki'' のレルムに ''id'' としてページ名を組み合わせると、 Wiki ページへのリンクを生成します)
+ * '''created, modified, date, time''' — 日付や時刻に整形されます (訳注: `datetime` という列名にすると日時で整形されます。日本語版では `時刻` で終わるカラムは `time` に、 `日付` で終わるカラムは `date` に、 `日時` で終わるカラムは `datetime` に、それぞれ整形されます)
+ * '''description''' — チケットの説明が入っているカラムで使用します。 Wiki エンジンで処理されます (訳注: 日本語版では `説明` でも整形されます)
 '''例:'''
 {{{
 SELECT id AS ticket, created, status, summary FROM ticket
+SELECT id AS ticket, created, status, summary FROM ticket
 }}}
 これらのカラムは定義しても非表示にすることができます。方法は [#column-syntax 下記] を参照してください。
 ''ticket'' 以外のレルムに対するレポートの作成方法については [http://trac.edgewall.org/wiki/CookBook/Configuration/Reports CookBook/Configuration/Reports] を参照してください。
+''ticket'' 以外のレルムに対するレポートの作成方法については [trac:CookBook/Configuration/Reports CookBook/Configuration/Reports] を参照してください。
 '''訳注''': Trac-0.11.1.ja1 以降のバージョンで作成した Environment では、デフォルトのレポートに日本語での整形ルールが適用されています。このような Environment を本家版 Trac で使用したい場合は各レポートの SQL を編集し、上記の日本語のカラム別名を英語に変更してください。
 === 整形されるカラムのカスタマイズ === #Customformattingcolumns
 カラム名の前後に 2 つのアンダースコアがついている場合 (例: '''`__color__`''') は、
+カラム名の前後に 2 つのアンダースコアがついている場合 (例: '''`__color__`''') は、
 ''整形用のヒント'' として扱われ、レコードの整形が行われます。
  * '''`__group__`''' — 指定されたカラムで、表示がグループ化されます。各グループは、それぞれセクションヘッダとクエリ結果の表を持ちます。
  * '''`__grouplink__`''' — グループ化した場合の各グループのヘッダで生成するリンク先の URL を指定します。この URL は各グループの最初の行にだけ付与されます。
  * '''`__color__`''' — 1 から 5 の数値である必要があります。値によって、あらかじめ定義された色付けが行われます。一般的な使用法は、優先度別の色付けです。
+ * '''`__group__`''' — 指定されたカラムで、表示がグループ化されます。各グループは、それぞれセクションヘッダとクエリ結果の表を持ちます
+ * '''`__grouplink__`''' — グループ化した場合の各グループのヘッダで生成するリンク先の URL を指定します。この URL は各グループの最初の行にだけ付与されます
+ * '''`__color__`''' — 1 から 5 の数値である必要があります。値によって、あらかじめ定義された色付けが行われます。一般的な使用法は、優先度別の色付けです
 {{{
 #!html
 <div style="margin-left:7.5em">デフォルトの色付け:
+<div style="margin-left:7.5em">デフォルトの色付け:
 <span style="border: none; color: #333; background: transparent;  font-size: 85%; background: #fdc; border-color: #e88; color: #a22">Color 1</span>
 <span style="border: none; color: #333; background: transparent;  font-size: 85%; background: #ffb; border-color: #eea; color: #880">Color 2</span>
 …
 </div>
 }}}
+ * '''`__style__`''' — CSS 形式でレコードを整形できます。
+ * '''`__style__`''' — `<tr>` 要素を使用して CSS 形式でレコードを整形できます
+ * '''`__class__`''' — `<tr>` 要素でセットされた0以上の空白で区切られた CSS のクラス名です。これらのクラスは `__color__` に由来するクラス名と偶数/奇数の指標に追加されます
 '''例:''' ''マイルストーン別未解決チケット (優先度別色付け, グループのヘッダでマイルストーンにリンク)''
 …
        t.id AS ticket, summary
   FROM ticket t,enum p
   WHERE t.status IN ('new', 'assigned', 'reopened')
+  WHERE t.status IN ('new', 'assigned', 'reopened')
     AND p.name=t.priority AND p.type='priority'
   ORDER BY t.milestone, p.value, t.severity, t.time
 …
 これから挙げる指定によって、複数行にわたってのレイアウトを行うことができます。
  * '''`column_`''' — ''改行''。 カラム名の語尾にアンダースコア ('_') を付与した場合、以降のカラムは次の行で表示されます。
  * '''`_column_`''' — ''全行表示''。 カラム名の前後にアンダースコア ('_') を付与した場合、そのカラムは続く行で全てのカラム幅を使って表示されます。
  * '''`_column`'''  —  ''データを非表示にする''。 カラム名の語頭にアンダースコア ('_') を付与した場合、 HTML 出力では非表示になります。これは (CSV や RSS のような) 別フォーマットでのダウンロード時にだけ見たい情報であるときに使います。
    この機能ではあらゆるカラムを非表示にできます。リソースの特定などで他のカラムが異存しているような場合に有用です。たとえば `id as _id` とすることで、 '''Id''' カラムは非表示となりますが、チケットへのリンクは正しく生成されます。
+ * '''`column_`''' — ''改行''。 カラム名の語尾にアンダースコア ('_') を付与した場合、以降のカラムは次の行で表示されます
+ * '''`_column_`''' — ''全行表示''。 カラム名の前後にアンダースコア ('_') を付与した場合、そのカラムは続く行で全てのカラム幅を使って表示されます
+ * '''`_column`'''  —  ''データを非表示にする''。 カラム名の語頭にアンダースコア ('_') を付与した場合、 HTML 出力では非表示になります。これは (CSV や RSS のような) 別フォーマットでのダウンロード時にだけ見たい情報であるときに使います
+   この機能ではあらゆるカラムを非表示にできます。リソースの特定などで他のカラムが異存しているような場合に有用です。たとえば `id as _id` とすることで、 '''Id''' カラムは非表示となりますが、チケットへのリンクは正しく生成されます
 '''例:''' ''アクティブなチケットを、マイルストーンでグループ化し、優先度で色付け、チケットの説明を multi-line レイアウトでリスト表示する''
 …
 SELECT p.value AS __color__,
        t.milestone AS __group__,
        (CASE owner
           WHEN 'daniel' THEN 'font-weight: bold; background: red;'
+       (CASE owner
+          WHEN 'daniel' THEN 'font-weight: bold; background: red;'
           ELSE '' END) AS __style__,
        t.id AS ticket, summary AS summary_,             -- ## ここで改行する
 …
        changetime AS _changetime, reporter AS _reporter -- ## HTML 出力では表示しない
   FROM ticket t,enum p
   WHERE t.status IN ('new', 'assigned', 'reopened')
+  WHERE t.status IN ('new', 'assigned', 'reopened')
     AND p.name=t.priority AND p.type='priority'
   ORDER BY t.milestone, p.value, t.severity, t.time
 …
 追加のフィールドを trac.ini に宣言する ''前に'' 、チケットがデータベースに存在する場合、 ticket_custom テーブルには関連するデータを持たないことになります。これに起因する問題を回避するためには SQL の "LEFT OUTER JOIN" 節を使用してください。
+'''Note レポートの追加、編集をするボタンを表示するためには権限を設定する必要があります。'''
+=== SQLの書き換えについて #rewriting
+動的変数の比較的些細な変更によって、SQL クエリもレポートの2つの特徴のサポートのために変更されます:
+. [#sort-order ソート順の変更]
+. ページネーションのサポート (各ページの表示結果の行数の制約)
+一つ目の特徴をサポートするために、__group__｀カラムが指定される場合にはソートカラムは `ORDER BY` 節の中の先頭位置か二番目の位置に挿入されます(必要に応じて `ORDER BY` 節は作成されます)。 ページネーションをサポートするために、 `LIMIT ... OFFSET ...` 節が追加されます。
+クエリは自動書き換えの機能が正常に働くには複雑すぎて、クエリは間違った結果になるかもしれません。この場合、手動で下記のトークンを挿入することにより、書き直しがどのように行われるか正確にコントロールできる可能性があります:
+ - `@SORT_COLUMN@`, ソートしたいカラム名です,
+ - `@LIMIT_OFFSET@`, ページネーションのサポートの節です
+Note: もしSQLコメント `--` の後に記述すると、意図したとおりの書き換えが事実上不可能になります！
+SQL query の例:
+{{{
+-- ## 4: 担当者がアサインしたアクティブなチケット ## --
+--
+-- アサインされたチケットのリスト、チケットの担当者によるグループ化、優先度によるソート
+--
+SELECT p.value AS __color__,
+   owner AS __group__,
+   id AS ticket, summary, component, milestone, t.type AS type, severity, time AS created,
+   changetime AS _changetime, description AS _description,
+   reporter AS _reporter
+  FROM ticket t,enum p
+  WHERE status = 'assigned'
+AND p.name=t.priority AND p.type='priority'
+  ORDER BY __group__, p.value, severity, time
+}}}
+自動書き換えの例(1ページにつき4行、2ページ、`component` によるソート):
+{{{
+SELECT p.value AS __color__,
+   owner AS __group__,
+   id AS ticket, summary, component, milestone, t.type AS type, severity, time AS created,
+   changetime AS _changetime, description AS _description,
+   reporter AS _reporter
+  FROM ticket t,enum p
+  WHERE status = 'assigned'
+AND p.name=t.priority AND p.type='priority'
+  ORDER BY __group__ ASC, `component` ASC,  __group__, p.value, severity, time
+ LIMIT 4 OFFSET 4
+}}}
+書き換えのトークンと等しいSQLクエリの例:
+{{{
+SELECT p.value AS __color__,
+   owner AS __group__,
+   id AS ticket, summary, component, milestone, t.type AS type, severity, time AS created,
+   changetime AS _changetime, description AS _description,
+   reporter AS _reporter
+  FROM ticket t,enum p
+  WHERE status = 'assigned'
+AND p.name=t.priority AND p.type='priority'
+  ORDER BY __group__, @SORT_COLUMN@, p.value, severity, time
+@LIMIT_OFFSET@
+}}}
+もし、最初に常に優先度によるソートを、そしてその次にユーザが選択したカラムによるソートを希望するならば、シンプルに下記のように `ORDER BY` 節を使用してください:
+{{{
+  ORDER BY __group__, p.value, @SORT_COLUMN@, severity, time
+}}}
 ----