= レポート = #TracReports
[[TracGuideToc]]

レポートモジュールは、簡単かつ強力なレポーティング機能を提供します。
この機能によって、 Trac データベースのチケット情報を取得することができます。

TracReports ではレポートの形式を定義するための方法として、独自フォーマットではなく、 
SQL の `SELECT` 文を使用することにしました。

  '''Note:''' ''現在の形式のレポートモジュールは、 Trac 開発チームでデータベースのスキーマにあわせる作業が必要になるという深刻な制限事項があるため、段階的に廃止します。より柔軟性に富みユーザビリティに優れた [wiki:TracQuery クエリモジュール] が代替手段として提供されます。どこかの時点でレポートモジュールを完全に削除することが出来るように、クエリモジュールで実現できないレポートがある間は、私たちはクエリモジュールを強化していくつもりです。また、これはレポートモジュールへの重要な機能追加は行わないことを意味します。''

  ''以下の [wiki:TracIni trac.ini] のように無効化するだけで、レポートモジュールをクエリモジュールで完全に置き換えることができます:''
  {{{
  [components]
  trac.ticket.report.* = disabled
  }}}
  ''これによって、ナビゲーションバーの "チケットを見る" (英語版では "View Tickets") でのデフォルトのハンドラがクエリモジュールになります。もし可能ならば、この設定を有効にして、レポート機能がなくなることによって生じる不都合を報告してください。''

  '''''ほとんど確実に httpd を再起動する必要があるでしょう。'''''

レポートは以下の基本的なパーツから構成されます:
 * '''ID''' -- ユニークな (連番の) 識別子
 * '''レポート名 (Title)''' -- レポートのタイトル
 * '''説明 (Description)''' -- WikiFormatting で記述された、レポートの説明。
 * '''レポート本体 (Report Body)''' -- 後に述べるフォーマットで規定された、レポートクエリの結果。
 * '''フッタ (Footer)''' -- レポート本体を異なる形式でダウンロードするためのリンク。

== ソートの並び順変更 == #ChangingSortOrder
単純なレポート (特にグループ化されていないもの) では、カラムのヘッダをクリックすれば、そのカラムでソートすることが出来ます。

カラムのヘッダがハイパーリンク (赤) になっていれば、クリックすることでそのカラムでのソートができます。並び順を逆にするには、もう一度クリックします。

== レポートの番号を変更する == #ChangingReportNumbering
レポートの ID を変更する必要がある場合があるかもしれませんが、おそらくレポート自体を編集する方がベターです。というのも Trac のデータベースを変更する必要があるからです。 ''report'' 表は以下のようなスキーマとなっています (0.10 相当):
 * id integer PRIMARY KEY
 * author text
 * title text
 * query text
 * description text
ID を変更すると ''レポート一覧 (Available Reports)'' での表示順と番号、レポートのパーマリンクが変更されます。以下のような SQL を実行すると ID が変更されます:
{{{
update report set id=5 where id=3;
}}}
メンテナンス結果、データベースの一貫性を保つ必要があることに留意してください (例えば ID はユニークでなければなりませんし、 SQLite などデータベースの上限値を超えることはできません)。

== チケットをナビゲート == #NavigatingTickets
レポートクエリ結果の 1 チケットをクリックするとそのチケットが表示されるでしょう。表示されたチケットのメインメニューバーのすぐ下にある ''次のチケット'' (英語版では ''Next Ticket'') または ''前のチケット'' (英語版では ''Previous Ticket'') リンクをクリックすることによって他のチケットに移動するか、''レポートに戻る'' (英語版では ''Back to Report'') リンクをクリックしてレポートページに戻ることができます。

あなたは安全にチケットを編集することができます。またチケットの編集結果を保存した後で、 次のチケット/前のチケット/レポートに戻る (英語版では Next/Previous/Back to Report) のリンクを使用して結果を行き来することが可能です。しかし、あなたがチケットへの操作を終えてレポートに戻るときに、どのチケットが変更されたかのヒントは表示されません。この動作はカスタムクエリの動作とは異なります。 (カスタムクエリについては TracQuery#NavigatingTickets を参照して下さい) 。 ''(0.11 以降 )''

== ダウンロードできるフォーマット == #AlternativeDownloadFormats
通常表示される HTML でのビューの加え、レポートはいろいろな形式で使用することができます。
レポートページの一番下に、利用可能なデータ形式の一覧があります。望む形式のリンクをクリックすれば、
その形式でのレポートをダウンロードすることができます。

=== カンマ区切りテキスト - CSV (Comma Separated Values) === #Comma-delimited-CSVCommaSeparatedValues
1 レコードを 1 行として、各カラムをカンマ (',') で区切ったプレーンテキストとしてダウンロードできます。
'''Note:''' CSV 形式を保つため、各カラムのデータに改行文字やカンマがある場合、その位置で切り取られます。

=== タブ区切り === #Tab-delimited
CSV と似ていますが、水平タブ文字 (\t) で区切られる点が違います。

=== RSS - XML コンテンツ配信 === #RSS-XMLContentSyndication
全てのレポートは、 XML/RSS 2.0 での配信が可能です。 RSS フィードを購読するにはページ下部にある、オレンジ色の 'XML' アイコンをクリックしてください。 Trac での RSS 対応についての一般的な情報は、 TracRss に記述しています。

----

== カスタムレポートを作成する == #CreatingCustomReports

''カスタムレポートを作成するためには、 SQL を楽に書ける程度の知識が必要です。''

レポートは基本的に、 Trac が実行できる形式の、名前がついた特定 SQL です。
レポートに指定された SQL は、直接 Web インタフェースから閲覧したり、
作成したりできます。

通常のレポートは、 'ticket' 表に対する、カラムの選択や、ソート指定を伴った 
SELECT 文となります。

== Ticket 表のカラム == #Ticketcolumns
''ticket'' 表は、以下のカラムを持ちます:
 * id           -- チケットID
 * type         -- チケット分類
 * time         -- 登録日時
 * changetime   -- 最終更新日時
 * component    -- コンポーネント
 * severity     -- 重要度
 * priority     -- 優先度
 * owner        -- 担当者
 * reporter     -- 報告者
 * cc           -- 関係者
 * version      -- バージョン
 * milestone    -- マイルストーン
 * status       -- ステータス
 * resolution   -- 解決方法
 * summary      -- チケットの概要
 * description  -- チケットについての完全な説明
 * keywords     -- キーワード

各カラムに対応する属性の詳細な説明は、 TracTickets に記述しています。

'''優先度順、登録日時順の全未解決チケット'''

'''例:''' ''優先度順、登録日時順の全未解決チケット''
{{{
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
レポートに汎用性を持たせる手段として、 ''動的変数'' をレポート SQL で使用する方法があります。
簡単に言うと、動的変数とは、クエリを実行する前に置き換えられる ''特別な'' 文字列のことです。

=== クエリで動的変数を使う方法 === #UsingVariablesinaQuery
動的変数を使うためのシンタックスは単純です。 '$' に続いて、大文字で変数名となる語を挿入してください。

例:
{{{
SELECT id AS ticket,summary FROM ticket WHERE priority=$PRIORITY
}}}

レポート閲覧時、 $PRIORITY に値を当てはめるためには、レポートの URL に引数として変数を与えてください。この変数名に '$' を入れてはいけません。

例:
{{{
 http://trac.edgewall.org/reports/14?PRIORITY=high
}}}

複数の値を使用する場合、各値を '&' で区切ります。

例:
{{{
 http://trac.edgewall.org/reports/14?PRIORITY=high&SEVERITY=critical
}}}


=== 特殊な定数 === #SpecialCo