Changes between Version 2 and Version 3 of TracReports


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

--

Legend:

Unmodified
Added
Removed
Modified
  • TracReports

    v2 v3  
     1** Note: このページは、Tracのバージョン1.0を文書化しています、旧バージョンが必要であれば、[[0.12/TracReports]]を参照してください ** 
    12= レポート = #TracReports 
    23[[TracGuideToc]] 
     
    56この機能によって、 Trac データベースのチケット情報を取得することができます。 
    67 
    7 TracReports ではレポートの形式を定義するための方法として、独自フォーマットではなく、  
     8TracReports ではレポートの形式を定義するための方法として、独自フォーマットではなく、 
    89SQL の `SELECT` 文を使用することにしました。 
    910 
     
    2021 * '''ID''' — ユニークな (連番の) 識別子 
    2122 * '''レポート名 (Title)''' — レポートのタイトル 
    22  * '''説明 (Description)''' — WikiFormatting で記述された、レポートの説明 
    23  * '''レポート本体 (Report Body)''' — 後に述べるフォーマットで規定された、レポートクエリの結果 
    24  * '''フッタ (Footer)''' — レポート本体を異なる形式でダウンロードするためのリンク 
     23 * '''説明 (Description)''' — WikiFormatting で記述された、レポートの説明 
     24 * '''レポート本体 (Report Body)''' — 後に述べるフォーマットで規定された、レポートクエリの結果 
     25 * '''フッタ (Footer)''' — レポート本体を異なる形式でダウンロードするためのリンク 
    2526 
    2627== ソートの並び順変更 == #ChangingSortOrder 
     
    7071''カスタムレポートを作成するためには、 SQL を楽に書ける程度の知識が必要です。'' 
    7172 
     73'''Note: レポートの追加、編集ボタンを表示させるためには [TracPermissions#Reports permissions] をセットアップする必要があります。''' 
     74 
    7275レポートは基本的に、 Trac が実行できる形式の、名前がついた特定 SQL です。 
    7376レポートに指定された SQL は、直接 Web インタフェースから閲覧したり、 
    7477作成したりできます。 
    7578 
    76 通常のレポートは、 'ticket' 表に対する、カラムの選択や、ソート指定を伴った  
     79通常のレポートは、 'ticket' 表に対する、カラムの選択や、ソート指定を伴った 
    7780SELECT 文となります。 
    7881 
     
    101104例: '''優先度順、登録日時順の全未解決チケット''' 
    102105{{{ 
    103 SELECT id AS ticket, status, severity, priority, owner,  
    104        time AS created, summary FROM ticket  
     106SELECT id AS ticket, status, severity, priority, owner, 
     107       time AS created, summary FROM ticket 
    105108  WHERE status IN ('new', 'assigned', 'reopened') 
    106109  ORDER BY priority, time 
    107110}}} 
    108111 
    109 --- 
    110112 
    111113== 上級トピック: 動的変数の使用 == #AdvancedReports:DynamicVariables 
     
    139141実用的なレポートにするために、自動的に値が設定される動的変数が用意されています。(URL で指定されると上書かれます) 
    140142 
    141  * $USER -- ログインに使用したユーザ名 
     143 * $USER -- ログインに使用したユーザ名 
    142144 
    143145例 (''私が担当になっているチケット一覧''): 
     
    146148}}} 
    147149 
    148  
    149 ---- 
    150150 
    151151 
    152152== 上級トピック: 表示形式のカスタマイズ == #AdvancedReports:CustomFormatting 
    153153Trac には、レイアウトのカスタマイズや、グルーピング、ユーザ定義の CSS 利用などによる 
    154 もっと複雑なレポートの作成も可能です。このようなレポートを作成するには、  
     154もっと複雑なレポートの作成も可能です。このようなレポートを作成するには、 
    155155Trac のレポートエンジンが出力を制御するためのステートメントを含む、特別な SQL を使用します。 
    156156 
    157 == 特別なカラム == #SpecialColumns 
     157=== 特別なカラム === #SpecialColumns 
    158158レポートを整形するため、 TracReports はクエリの結果から '特定の' カラム名を 
    159159探します。このような '特定の' 名前で、最終的なレポートのレイアウトやスタイルが 
     
    161161 
    162162=== 自動的に整形されるカラム名 === #Automaticallyformattedcolumns 
    163  * '''ticket''' — チケットの ID が入っているカラムで使用します。該当する ID のカラムにハイパーリンクされます。 (訳注: `summary` というカラム名もチケットにハイパーリンクされます。日本語版では `概要` でもリンクします。) 
    164  * '''id''' — '''realm''' が指定されない場合は、 '''ticket''' と同じです 
    165  * '''realm''' — '''id''' と同時に使用します。チケット以外のリソースにリンクを行う場合に使用します(e.g. ''wiki'' のレルムに ''id'' としてページ名を組み合わせると、 Wiki ページへのリンクを生成します) 
    166  * '''created, modified, date, time''' — 日付や時刻に整形されます。 (訳注: `datetime` という列名にすると日時で整形されます。日本語版では `時刻` で終わるカラムは `time` に、 `日付` で終わるカラムは `date` に、 `日時` で終わるカラムは `datetime` に、それぞれ整形されます。) 
    167  * '''description''' — チケットの説明が入っているカラムで使用します。 Wiki エンジンで処理されます。 (訳注: 日本語版では `説明` でも整形されます。) 
     163 * '''ticket''' — チケットの ID が入っているカラムで使用します。該当する ID のカラムにハイパーリンクされます (訳注: `summary` というカラム名もチケットにハイパーリンクされます。日本語版では `概要` でもリンクします) 
     164 * '''id''' — '''realm''' が指定されない場合は、 '''ticket''' と同じです 
     165 * '''realm''' — '''id''' と同時に使用します。チケット以外のリソースにリンクを行う場合に使用します(e.g. ''wiki'' のレルムに ''id'' としてページ名を組み合わせると、 Wiki ページへのリンクを生成します) 
     166 * '''created, modified, date, time''' — 日付や時刻に整形されます (訳注: `datetime` という列名にすると日時で整形されます。日本語版では `時刻` で終わるカラムは `time` に、 `日付` で終わるカラムは `date` に、 `日時` で終わるカラムは `datetime` に、それぞれ整形されます) 
     167 * '''description''' — チケットの説明が入っているカラムで使用します。 Wiki エンジンで処理されます (訳注: 日本語版では `説明` でも整形されます) 
    168168 
    169169'''例:''' 
    170170{{{ 
    171 SELECT id AS ticket, created, status, summary FROM ticket  
     171SELECT id AS ticket, created, status, summary FROM ticket 
    172172}}} 
    173173 
    174174これらのカラムは定義しても非表示にすることができます。方法は [#column-syntax 下記] を参照してください。 
    175175 
    176 ''ticket'' 以外のレルムに対するレポートの作成方法については [http://trac.edgewall.org/wiki/CookBook/Configuration/Reports CookBook/Configuration/Reports] を参照してください。 
     176''ticket'' 以外のレルムに対するレポートの作成方法については [trac:CookBook/Configuration/Reports CookBook/Configuration/Reports] を参照してください。 
    177177 
    178178'''訳注''': Trac-0.11.1.ja1 以降のバージョンで作成した Environment では、デフォルトのレポートに日本語での整形ルールが適用されています。このような Environment を本家版 Trac で使用したい場合は各レポートの SQL を編集し、上記の日本語のカラム別名を英語に変更してください。 
    179179 
    180180=== 整形されるカラムのカスタマイズ === #Customformattingcolumns 
    181 カラム名の前後に 2 つのアンダースコアがついている場合 (例: '''`__color__`''') は、  
     181カラム名の前後に 2 つのアンダースコアがついている場合 (例: '''`__color__`''') は、 
    182182''整形用のヒント'' として扱われ、レコードの整形が行われます。 
    183   
    184  * '''`__group__`''' — 指定されたカラムで、表示がグループ化されます。各グループは、それぞれセクションヘッダとクエリ結果の表を持ちます 
    185  * '''`__grouplink__`''' — グループ化した場合の各グループのヘッダで生成するリンク先の URL を指定します。この URL は各グループの最初の行にだけ付与されます 
    186  * '''`__color__`''' — 1 から 5 の数値である必要があります。値によって、あらかじめ定義された色付けが行われます。一般的な使用法は、優先度別の色付けです 
     183 
     184 * '''`__group__`''' — 指定されたカラムで、表示がグループ化されます。各グループは、それぞれセクションヘッダとクエリ結果の表を持ちます 
     185 * '''`__grouplink__`''' — グループ化した場合の各グループのヘッダで生成するリンク先の URL を指定します。この URL は各グループの最初の行にだけ付与されます 
     186 * '''`__color__`''' — 1 から 5 の数値である必要があります。値によって、あらかじめ定義された色付けが行われます。一般的な使用法は、優先度別の色付けです 
    187187{{{ 
    188188#!html 
    189 <div style="margin-left:7.5em">デフォルトの色付け:  
     189<div style="margin-left:7.5em">デフォルトの色付け: 
    190190<span style="border: none; color: #333; background: transparent;  font-size: 85%; background: #fdc; border-color: #e88; color: #a22">Color 1</span> 
    191191<span style="border: none; color: #333; background: transparent;  font-size: 85%; background: #ffb; border-color: #eea; color: #880">Color 2</span> 
     
    195195</div> 
    196196}}} 
    197  * '''`__style__`''' — CSS 形式でレコードを整形できます。 
     197 * '''`__style__`''' — `<tr>` 要素を使用して CSS 形式でレコードを整形できます 
     198 * '''`__class__`''' — `<tr>` 要素でセットされた0以上の空白で区切られた CSS のクラス名です。これらのクラスは `__color__` に由来するクラス名と偶数/奇数の指標に追加されます 
    198199 
    199200'''例:''' ''マイルストーン別未解決チケット (優先度別色付け, グループのヘッダでマイルストーンにリンク)'' 
     
    205206       t.id AS ticket, summary 
    206207  FROM ticket t,enum p 
    207   WHERE t.status IN ('new', 'assigned', 'reopened')  
     208  WHERE t.status IN ('new', 'assigned', 'reopened') 
    208209    AND p.name=t.priority AND p.type='priority' 
    209210  ORDER BY t.milestone, p.value, t.severity, t.time 
     
    218219これから挙げる指定によって、複数行にわたってのレイアウトを行うことができます。 
    219220 
    220  * '''`column_`''' — ''改行''。 カラム名の語尾にアンダースコア ('_') を付与した場合、以降のカラムは次の行で表示されます 
    221  
    222  * '''`_column_`''' — ''全行表示''。 カラム名の前後にアンダースコア ('_') を付与した場合、そのカラムは続く行で全てのカラム幅を使って表示されます 
    223  
    224  * '''`_column`'''  —  ''データを非表示にする''。 カラム名の語頭にアンダースコア ('_') を付与した場合、 HTML 出力では非表示になります。これは (CSV や RSS のような) 別フォーマットでのダウンロード時にだけ見たい情報であるときに使います 
    225    この機能ではあらゆるカラムを非表示にできます。リソースの特定などで他のカラムが異存しているような場合に有用です。たとえば `id as _id` とすることで、 '''Id''' カラムは非表示となりますが、チケットへのリンクは正しく生成されます 
     221 * '''`column_`''' — ''改行''。 カラム名の語尾にアンダースコア ('_') を付与した場合、以降のカラムは次の行で表示されます 
     222 
     223 * '''`_column_`''' — ''全行表示''。 カラム名の前後にアンダースコア ('_') を付与した場合、そのカラムは続く行で全てのカラム幅を使って表示されます 
     224 
     225 * '''`_column`'''  —  ''データを非表示にする''。 カラム名の語頭にアンダースコア ('_') を付与した場合、 HTML 出力では非表示になります。これは (CSV や RSS のような) 別フォーマットでのダウンロード時にだけ見たい情報であるときに使います 
     226   この機能ではあらゆるカラムを非表示にできます。リソースの特定などで他のカラムが異存しているような場合に有用です。たとえば `id as _id` とすることで、 '''Id''' カラムは非表示となりますが、チケットへのリンクは正しく生成されます 
    226227 
    227228'''例:''' ''アクティブなチケットを、マイルストーンでグループ化し、優先度で色付け、チケットの説明を multi-line レイアウトでリスト表示する'' 
     
    230231SELECT p.value AS __color__, 
    231232       t.milestone AS __group__, 
    232        (CASE owner  
    233           WHEN 'daniel' THEN 'font-weight: bold; background: red;'  
     233       (CASE owner 
     234          WHEN 'daniel' THEN 'font-weight: bold; background: red;' 
    234235          ELSE '' END) AS __style__, 
    235236       t.id AS ticket, summary AS summary_,             -- ## ここで改行する 
     
    239240       changetime AS _changetime, reporter AS _reporter -- ## HTML 出力では表示しない 
    240241  FROM ticket t,enum p 
    241   WHERE t.status IN ('new', 'assigned', 'reopened')  
     242  WHERE t.status IN ('new', 'assigned', 'reopened') 
    242243    AND p.name=t.priority AND p.type='priority' 
    243244  ORDER BY t.milestone, p.value, t.severity, t.time 
     
    250251追加のフィールドを trac.ini に宣言する ''前に'' 、チケットがデータベースに存在する場合、 ticket_custom テーブルには関連するデータを持たないことになります。これに起因する問題を回避するためには SQL の "LEFT OUTER JOIN" 節を使用してください。 
    251252 
    252 '''Note レポートの追加、編集をするボタンを表示するためには権限を設定する必要があります。''' 
     253=== SQLの書き換えについて #rewriting 
     254動的変数の比較的些細な変更によって、SQL クエリもレポートの2つの特徴のサポートのために変更されます: 
     255 1. [#sort-order ソート順の変更] 
     256 2. ページネーションのサポート (各ページの表示結果の行数の制約) 
     257一つ目の特徴をサポートするために、__group__`カラムが指定される場合にはソートカラムは `ORDER BY` 節の中の先頭位置か二番目の位置に挿入されます(必要に応じて `ORDER BY` 節は作成されます)。 ページネーションをサポートするために、 `LIMIT ... OFFSET ...` 節が追加されます。 
     258クエリは自動書き換えの機能が正常に働くには複雑すぎて、クエリは間違った結果になるかもしれません。この場合、手動で下記のトークンを挿入することにより、書き直しがどのように行われるか正確にコントロールできる可能性があります: 
     259 - `@SORT_COLUMN@`, ソートしたいカラム名です, 
     260 - `@LIMIT_OFFSET@`, ページネーションのサポートの節です 
     261Note: もしSQLコメント `--` の後に記述すると、意図したとおりの書き換えが事実上不可能になります! 
     262 
     263SQL query の例: 
     264{{{ 
     265-- ## 4: 担当者がアサインしたアクティブなチケット ## -- 
     266 
     267-- 
     268-- アサインされたチケットのリスト、チケットの担当者によるグループ化、優先度によるソート 
     269-- 
     270 
     271SELECT p.value AS __color__, 
     272   owner AS __group__, 
     273   id AS ticket, summary, component, milestone, t.type AS type, severity, time AS created, 
     274   changetime AS _changetime, description AS _description, 
     275   reporter AS _reporter 
     276  FROM ticket t,enum p 
     277  WHERE status = 'assigned' 
     278AND p.name=t.priority AND p.type='priority' 
     279  ORDER BY __group__, p.value, severity, time 
     280}}} 
     281 
     282自動書き換えの例(1ページにつき4行、2ページ、`component` によるソート): 
     283{{{ 
     284SELECT p.value AS __color__, 
     285   owner AS __group__, 
     286   id AS ticket, summary, component, milestone, t.type AS type, severity, time AS created, 
     287   changetime AS _changetime, description AS _description, 
     288   reporter AS _reporter 
     289  FROM ticket t,enum p 
     290  WHERE status = 'assigned' 
     291AND p.name=t.priority AND p.type='priority' 
     292  ORDER BY __group__ ASC, `component` ASC,  __group__, p.value, severity, time 
     293 LIMIT 4 OFFSET 4 
     294}}} 
     295 
     296書き換えのトークンと等しいSQLクエリの例: 
     297{{{ 
     298SELECT p.value AS __color__, 
     299   owner AS __group__, 
     300   id AS ticket, summary, component, milestone, t.type AS type, severity, time AS created, 
     301   changetime AS _changetime, description AS _description, 
     302   reporter AS _reporter 
     303  FROM ticket t,enum p 
     304  WHERE status = 'assigned' 
     305AND p.name=t.priority AND p.type='priority' 
     306  ORDER BY __group__, @SORT_COLUMN@, p.value, severity, time 
     307@LIMIT_OFFSET@ 
     308}}} 
     309 
     310もし、最初に常に優先度によるソートを、そしてその次にユーザが選択したカラムによるソートを希望するならば、シンプルに下記のように `ORDER BY` 節を使用してください: 
     311{{{ 
     312  ORDER BY __group__, p.value, @SORT_COLUMN@, severity, time 
     313}}} 
    253314 
    254315----