Changes between Version 1 and Version 2 of TracReports


Ignore:
Timestamp:
Aug 13, 2014, 12:08:17 AM (10 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • TracReports

    v1 v2  
     1** Note: このページは、Tracのバージョン1.0を文書化しています、旧バージョンが必要であれば、[[0.12/TracReports]]を参照してください **
    12= レポート = #TracReports
    23[[TracGuideToc]]
    … …  
    56この機能によって、 Trac データベースのチケット情報を取得することができます。
    67
    7 TracReports ではレポートの形式を定義するための方法として、独自フォーマットではなく、 
     8TracReports ではレポートの形式を定義するための方法として、独自フォーマットではなく、
    89SQL の `SELECT` 文を使用することにしました。
    910
    … …  
    1718  ''これによって、ナビゲーションバーの "チケットを見る" (英語版では "View Tickets") でのデフォルトのハンドラがクエリモジュールになります。もし可能ならば、この設定を有効にして、レポート機能がなくなることによって生じる不都合を報告してください。''
    1819
    19 
    2020レポートは以下の基本的なパーツから構成されます:
    21  * '''ID''' -- ユニークな (連番の) 識別子
    22  * '''レポート名 (Title)''' -- レポートのタイトル
    23  * '''説明 (Description)''' -- WikiFormatting で記述された、レポートの説明。
    24  * '''レポート本体 (Report Body)''' -- 後に述べるフォーマットで規定された、レポートクエリの結果。
    25  * '''フッタ (Footer)''' -- レポート本体を異なる形式でダウンロードするためのリンク。
     21 * '''ID''' — ユニークな (連番の) 識別子
     22 * '''レポート名 (Title)''' — レポートのタイトル
     23 * '''説明 (Description)''' — WikiFormatting で記述された、レポートの説明
     24 * '''レポート本体 (Report Body)''' — 後に述べるフォーマットで規定された、レポートクエリの結果
     25 * '''フッタ (Footer)''' — レポート本体を異なる形式でダウンロードするためのリンク
    2626
    2727== ソートの並び順変更 == #ChangingSortOrder
    … …  
    3131
    3232== レポートの番号を変更する == #ChangingReportNumbering
    33 レポートの ID を変更する必要がある場合があるかもしれませんが、おそらくレポート自体を編集する方がベターです。というのも Trac のデータベースを変更する必要があるからです。 ''report'' 表は以下のようなスキーマとなっています (0.10 相当):
     33レポートの ID を変更する必要がある場合があるかもしれませんが、おそらくレポート自体を編集する方がベターです。というのも Trac のデータベースを変更する必要があるからです。 ''report'' 表は以下のようなスキーマとなっています ''(0.10 以降)'':
    3434 * id integer PRIMARY KEY
    3535 * author text
    … …  
    4848レポートクエリ結果の 1 チケットをクリックするとそのチケットが表示されるでしょう。表示されたチケットのメインメニューバーのすぐ下にある ''次のチケット'' (英語版では ''Next Ticket'') または ''前のチケット'' (英語版では ''Previous Ticket'') リンクをクリックすることによって他のチケットに移動するか、''レポートに戻る'' (英語版では ''Back to Report'') リンクをクリックしてレポートページに戻ることができます。
    4949
    50 あなたは安全にチケットを編集することができます。またチケットの編集結果を保存した後で、 次のチケット/前のチケット/レポートに戻る (英語版では Next/Previous/Back to Report) のリンクを使用して結果を行き来することが可能です。しかし、あなたがチケットへの操作を終えてレポートに戻るときに、どのチケットが変更されたかのヒントは表示されません。この動作はカスタムクエリの動作とは異なります。 (カスタムクエリについては TracQuery#NavigatingTickets を参照して下さい) 。 ''(0.11 以降 )''
     50あなたは安全にチケットを編集することができます。またチケットの編集結果を保存した後で、 ''次のチケット/前のチケット/レポートに戻る'' (英語版では ''!Next/Previous/Back to Report'') のリンクを使用して結果を行き来することが可能です。しかし、あなたがチケットへの操作を終えてレポートに戻るときに、どのチケットが変更されたかのヒントは表示されません。この動作はカスタムクエリの動作とは異なります。 (カスタムクエリについては TracQuery#NavigatingTickets を参照して下さい) 。 ''(0.11 以降 )''
    5151
    5252== ダウンロードできるフォーマット == #AlternativeDownloadFormats
    … …  
    5757=== カンマ区切りテキスト - CSV (Comma Separated Values) === #Comma-delimited-CSVCommaSeparatedValues
    58581 レコードを 1 行として、各カラムをカンマ (',') で区切ったプレーンテキストとしてダウンロードできます。
    59 '''Note:''' CSV 形式を保つため、各カラムのデータに改行文字やカンマがある場合、その位置で切り取られます。
     59'''Note:''' 各カラムのデータに改行文字やカンマがある場合、エスケープされて出力されます。
    6060
    6161=== タブ区切り === #Tab-delimited
    … …  
    7070
    7171''カスタムレポートを作成するためには、 SQL を楽に書ける程度の知識が必要です。''
     72
     73'''Note: レポートの追加、編集ボタンを表示させるためには [TracPermissions#Reports permissions] をセットアップする必要があります。'''
    7274
    7375レポートは基本的に、 Trac が実行できる形式の、名前がついた特定 SQL です。
    … …  
    7577作成したりできます。
    7678
    77 通常のレポートは、 'ticket' 表に対する、カラムの選択や、ソート指定を伴った 
     79通常のレポートは、 'ticket' 表に対する、カラムの選択や、ソート指定を伴った
    7880SELECT 文となります。
    7981
    … …  
    100102各カラムに対応する属性の詳細な説明は、 TracTickets に記述しています。
    101103
    102 '''優先度順、登録日時順の全未解決チケット'''
    103 
    104 '''例:''' ''優先度順、登録日時順の全未解決チケット''
    105 {{{
    106 SELECT id AS ticket, status, severity, priority, owner,
    107        time as created, summary FROM ticket
     104例: '''優先度順、登録日時順の全未解決チケット'''
     105{{{
     106SELECT id AS ticket, status, severity, priority, owner,
     107       time AS created, summary FROM ticket
    108108  WHERE status IN ('new', 'assigned', 'reopened')
    109109  ORDER BY priority, time
    110110}}}
    111 
    112 
    113 ----
    114111
    115112
    … …  
    142139
    143140=== 特殊な定数 === #SpecialConstantVariables
    144 実用的なレポートのために、定義済みの動的変数が用意されています。これらは URL に値を設定しなくても、自動的に値が割り当てられます。
    145 
    146  * $USER -- ログインに使用したユーザ名。
     141実用的なレポートにするために、自動的に値が設定される動的変数が用意されています。(URL で指定されると上書かれます)
     142
     143 * $USER -- ログインに使用したユーザ名
    147144
    148145例 (''私が担当になっているチケット一覧''):
    … …  
    151148}}}
    152149
    153 
    154 ----
    155150
    156151
    157152== 上級トピック: 表示形式のカスタマイズ == #AdvancedReports:CustomFormatting
    158153Trac には、レイアウトのカスタマイズや、グルーピング、ユーザ定義の CSS 利用などによる
    159 もっと複雑なレポートの作成も可能です。このようなレポートを作成するには、 
     154もっと複雑なレポートの作成も可能です。このようなレポートを作成するには、
    160155Trac のレポートエンジンが出力を制御するためのステートメントを含む、特別な SQL を使用します。
    161156
    162 == 特別なカラム == #SpecialColumns
     157=== 特別なカラム === #SpecialColumns
    163158レポートを整形するため、 TracReports はクエリの結果から '特定の' カラム名を
    164159探します。このような '特定の' 名前で、最終的なレポートのレイアウトやスタイルが
    … …  
    166161
    167162=== 自動的に整形されるカラム名 === #Automaticallyformattedcolumns
    168  * '''ticket''' -- チケットの ID が入っているカラムで使用します。該当する ID のカラムにハイパーリンクされます。 (訳注: `summary` というカラム名もチケットにハイパーリンクされます。日本語版では `概要` でもリンクします。)
    169  * '''id''' -- '''realm''' が指定されない場合は、 '''ticket''' と同じです。
    170  * '''realm''' -- '''id''' と同時に使用します。チケット以外のリソースにリンクを行う場合に使用します。 (e.g. ''wiki'' のレルムに ''id'' としてページ名を組み合わせると、 Wiki ページへのリンクを生成します)
    171  * '''created, modified, date, time''' -- 日付や時刻に整形されます。 (訳注: `datetime` という列名にすると日時で整形されます。日本語版では `時刻` で終わるカラムは `time` に、 `日付` で終わるカラムは `date` に、 `日時` で終わるカラムは `datetime` に、それぞれ整形されます。)
    172  * '''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 エンジンで処理されます (訳注: 日本語版では `説明` でも整形されます)
    173168
    174169'''例:'''
    175170{{{
    176 SELECT id as ticket, created, status, summary FROM ticket
     171SELECT id AS ticket, created, status, summary FROM ticket
    177172}}}
    178173
    179174これらのカラムは定義しても非表示にすることができます。方法は [#column-syntax 下記] を参照してください。
    180175
     176''ticket'' 以外のレルムに対するレポートの作成方法については [trac:CookBook/Configuration/Reports CookBook/Configuration/Reports] を参照してください。
     177
    181178'''訳注''': Trac-0.11.1.ja1 以降のバージョンで作成した Environment では、デフォルトのレポートに日本語での整形ルールが適用されています。このような Environment を本家版 Trac で使用したい場合は各レポートの SQL を編集し、上記の日本語のカラム別名を英語に変更してください。
    182179
    183180=== 整形されるカラムのカスタマイズ === #Customformattingcolumns
    184 カラム名の前後に 2 つのアンダースコアがついている場合 (例: '''`__color__`''') は、 
     181カラム名の前後に 2 つのアンダースコアがついている場合 (例: '''`__color__`''') は、
    185182''整形用のヒント'' として扱われ、レコードの整形が行われます。
    186  
    187  * '''`__group__`''' -- 指定されたカラムで、表示がグループ化されます。各グループは、それぞれセクションヘッダとクエリ結果の表を持ちます。
    188  * '''`__color__`''' -- 1 から 5 の数値である必要があります。値によって、あらかじめ定義された色付けが行われます。一般的な使用法は、優先度別の色付けです。
     183
     184 * '''`__group__`''' — 指定されたカラムで、表示がグループ化されます。各グループは、それぞれセクションヘッダとクエリ結果の表を持ちます
     185 * '''`__grouplink__`''' — グループ化した場合の各グループのヘッダで生成するリンク先の URL を指定します。この URL は各グループの最初の行にだけ付与されます
     186 * '''`__color__`''' — 1 から 5 の数値である必要があります。値によって、あらかじめ定義された色付けが行われます。一般的な使用法は、優先度別の色付けです
    189187{{{
    190188#!html
    191 <div style="margin-left:7.5em">デフォルトの色付け: 
     189<div style="margin-left:7.5em">デフォルトの色付け:
    192190<span style="border: none; color: #333; background: transparent;  font-size: 85%; background: #fdc; border-color: #e88; color: #a22">Color 1</span>
    193191<span style="border: none; color: #333; background: transparent;  font-size: 85%; background: #ffb; border-color: #eea; color: #880">Color 2</span>
    … …  
    197195</div>
    198196}}}
    199  * '''`__style__`''' -- CSS 形式でレコードを整形できます。
    200 
    201 '''例:''' ''マイルストーン別未解決チケット (優先度別色付け)''
     197 * '''`__style__`''' — `<tr>` 要素を使用して CSS 形式でレコードを整形できます
     198 * '''`__class__`''' — `<tr>` 要素でセットされた0以上の空白で区切られた CSS のクラス名です。これらのクラスは `__color__` に由来するクラス名と偶数/奇数の指標に追加されます
     199
     200'''例:''' ''マイルストーン別未解決チケット (優先度別色付け, グループのヘッダでマイルストーンにリンク)''
    202201{{{
    203202SELECT p.value AS __color__,
    204203     t.milestone AS __group__,
     204     '../milestone/' || t.milestone AS __grouplink__,
    205205     (CASE owner WHEN 'daniel' THEN 'font-weight: bold; background: red;' ELSE '' END) AS __style__,
    206206       t.id AS ticket, summary
    207207  FROM ticket t,enum p
    208   WHERE t.status IN ('new', 'assigned', 'reopened') 
     208  WHERE t.status IN ('new', 'assigned', 'reopened')
    209209    AND p.name=t.priority AND p.type='priority'
    210210  ORDER BY t.milestone, p.value, t.severity, t.time
    … …  
    219219これから挙げる指定によって、複数行にわたってのレイアウトを行うことができます。
    220220
    221  * '''`column_`''' -- ''改行''。 カラム名の語尾にアンダースコア ('_') を付与した場合、以降のカラムは次の行で表示されます。
    222 
    223  * '''`_column_`''' -- ''全行表示''。 カラム名の前後にアンダースコア ('_') を付与した場合、そのカラムは続く行で全てのカラム幅を使って表示されます。
    224 
    225  * '''`_column`'''  --  ''データを非表示にする''。 カラム名の語頭にアンダースコア ('_') を付与した場合、 HTML 出力では非表示になります。これは (CSV や RSS のような) 別フォーマットでのダウンロード時にだけ見たい情報であるときに使います。
    226    この機能ではあらゆるカラムを非表示にできます。リソースの特定などで他のカラムが異存しているような場合に有用です。たとえば `id as _id` とすることで、 '''Id''' カラムは非表示となりますが、チケットへのリンクは正しく生成されます。
     221 * '''`column_`''' — ''改行''。 カラム名の語尾にアンダースコア ('_') を付与した場合、以降のカラムは次の行で表示されます
     222
     223 * '''`_column_`''' — ''全行表示''。 カラム名の前後にアンダースコア ('_') を付与した場合、そのカラムは続く行で全てのカラム幅を使って表示されます
     224
     225 * '''`_column`'''  —  ''データを非表示にする''。 カラム名の語頭にアンダースコア ('_') を付与した場合、 HTML 出力では非表示になります。これは (CSV や RSS のような) 別フォーマットでのダウンロード時にだけ見たい情報であるときに使います
     226   この機能ではあらゆるカラムを非表示にできます。リソースの特定などで他のカラムが異存しているような場合に有用です。たとえば `id as _id` とすることで、 '''Id''' カラムは非表示となりますが、チケットへのリンクは正しく生成されます
    227227
    228228'''例:''' ''アクティブなチケットを、マイルストーンでグループ化し、優先度で色付け、チケットの説明を multi-line レイアウトでリスト表示する''
    … …  
    231231SELECT p.value AS __color__,
    232232       t.milestone AS __group__,
    233        (CASE owner 
    234           WHEN 'daniel' THEN 'font-weight: bold; background: red;' 
     233       (CASE owner
     234          WHEN 'daniel' THEN 'font-weight: bold; background: red;'
    235235          ELSE '' END) AS __style__,
    236236       t.id AS ticket, summary AS summary_,             -- ## ここで改行する
    … …  
    240240       changetime AS _changetime, reporter AS _reporter -- ## HTML 出力では表示しない
    241241  FROM ticket t,enum p
    242   WHERE t.status IN ('new', 'assigned', 'reopened') 
     242  WHERE t.status IN ('new', 'assigned', 'reopened')
    243243    AND p.name=t.priority AND p.type='priority'
    244244  ORDER BY t.milestone, p.value, t.severity, t.time
    … …  
    251251追加のフィールドを trac.ini に宣言する ''前に'' 、チケットがデータベースに存在する場合、 ticket_custom テーブルには関連するデータを持たないことになります。これに起因する問題を回避するためには SQL の "LEFT OUTER JOIN" 節を使用してください。
    252252
    253 '''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}}}
    254314
    255315----