Changes between Initial Version and Version 1 of TracReports


Ignore:
Timestamp:
06/11/06 17:57:32 (18 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • TracReports

    v1 v1  
     1= レポート = 
     2[[TracGuideToc]] 
     3 
     4レポートモジュールは、簡単かつ強力なレポーティング機能を提供します。 
     5この機能によって、 Trac データベースのチケット情報を取得することができます。 
     6 
     7TracReports ではレポートの形式を定義するための方法として、独自フォーマットではなく、 
     8SQL の `SELECT` 文を使用することにしました。 
     9 
     10  '''Note:''' ''現在の形式のレポートモジュールは、 Trac 開発チームでデータベースのスキーマにあわせる作業が必要になるという深刻な制限事項があるため、段階的に廃止します。より柔軟性に富みユーザビリティに優れた [wiki:TracQuery クエリモジュール] が代替手段として提供されます。どこかの時点でレポートモジュールを完全に削除することが出来るように、クエリモジュールで実現できないレポートがある間は、私たちはクエリモジュールを強化していくつもりです。また、これはレポートモジュールへの重要な機能追加は行わないことを意味します。'' 
     11 
     12  ''すでにレポートモジュールをクエリモジュールで完全に置き換えられる場合、 [wiki:TracIni trac.ini] に以下の記述を追加して無効化してください:'' 
     13  {{{ 
     14  [components] 
     15  trac.ticket.report.* = disabled 
     16  }}} 
     17  ''これによって、ナビゲーションバーの "チケットを見る" でのデフォルトのハンドラがクエリモジュールになります。もし可能ならば、この設定を有効にして、レポート機能がなくなることによって生じる不都合を報告してください。'' 
     18 
     19レポートは以下の基本的なパーツから構成されます: 
     20 * '''ID''' -- ユニークな (連番の) 識別子 
     21 * '''レポート名 (Title)''' -- レポートのタイトル 
     22 * '''説明 (Description)''' -- WikiFormatting で記述された、レポートの説明。 
     23 * '''レポート本体 (Report Body)''' -- 後に述べるフォーマットで規定された、レポートクエリの結果。 
     24 * '''フッタ (Footer)''' -- レポート本体を異なる形式でダウンロードするためのリンク。 
     25 
     26== ソートの並び順変更 == 
     27単純なレポート (特にグループ化されていないもの) では、カラムのヘッダをクリックすれば、そのカラムでソートすることが出来ます。 
     28 
     29カラムのヘッダがハイパーリンク (赤) になっていれば、クリックすることでそのカラムでのソートができます。並び順を逆にするには、もう一度クリックします。 
     30 
     31 
     32== ダウンロードできるフォーマット == 
     33通常表示される HTML でのビューの加え、レポートはいろいろな形式で使用することができます。 
     34レポートページの一番下に、利用可能なデータ形式の一覧があります。望む形式のリンクをクリックすれば、 
     35その形式でのレポートをダウンロードすることができます。 
     36 
     37=== カンマ区切りテキスト - CSV (Comma Separated Values) === 
     381レコードを1行として、各カラムをカンマ (',') で区切ったプレーンテキストとしてダウンロードできます。 
     39'''Note:''' CSV形式を保つため、各カラムのデータに改行文字やカンマがある場合、その位置で切り取られます。 
     40 
     41=== タブ区切り === 
     42CSV と似ていますが、水平タブ文字 (\t) で区切られる点が違います。 
     43 
     44=== RSS - XML Content Syndication === 
     45全てのレポートは、 XML/RSS 2.0 での配信をサポートしています。RSSフィードを購読するにはページ下部にある、オレンジ色の 'XML' アイコンをクリックしてください。 Trac での RSS サポートについての一般的な情報は、 TracRss に記述しています。 
     46 
     47---- 
     48 
     49== カスタムレポートを作成する == 
     50 
     51''カスタムレポートを作成するためには、 SQL を楽に書ける程度の知識が必要です。'' 
     52 
     53レポートは基本的に、 Trac が実行できる形式の、名前がついた特定 SQL です。 
     54レポートに指定された SQL は、直接 Web インタフェースから閲覧したり、 
     55作成したりできます。 
     56 
     57通常のレポートは、 'ticket' 表に対する、カラムの選択や、ソート指定を伴った 
     58SELECT 文となります。 
     59 
     60== Ticket 表のカラム == 
     61''ticket'' 表は、以下のカラムを持ちます: 
     62 * id           -- チケットID 
     63 * time         -- 登録日時 
     64 * changetime   -- 最終更新日時 
     65 * component    -- コンポーネント 
     66 * severity     -- 重要度 
     67 * priority     -- 優先度 
     68 * owner        -- 担当者 
     69 * reporter     -- 報告者 
     70 * cc           -- 関係者 
     71 * version      -- バージョン 
     72 * milestone    -- マイルストーン 
     73 * status       -- ステータス 
     74 * resolution   -- 解決方法 
     75 * summary      -- チケットの概要 
     76 * description  -- チケットについての完全な説明 
     77 
     78各カラムに対応する属性の詳細な説明は、 TracTickets に記述しています。 
     79 
     80'''優先度順、登録日時順の全未解決チケット''' 
     81 
     82'''例:''' ''優先度順、登録日時順の全未解決チケット'' 
     83{{{ 
     84SELECT id AS ticket, status, severity, priority, owner,  
     85       time as created, summary FROM ticket  
     86  WHERE status IN ('new', 'assigned', 'reopened') 
     87  ORDER BY priority, time 
     88}}} 
     89 
     90 
     91---- 
     92 
     93 
     94== 上級トピック: 動的変数の使用 == 
     95レポートに汎用性を持たせる手段として、 ''動的変数'' をレポート SQL で使用する方法があります。 
     96簡単に言うと、動的変数とは、クエリを実行する前に置き換えられる ''特別な'' 文字列のことです。 
     97 
     98=== クエリで動的変数を使う方法 === 
     99動的変数を使うためのシンタックスは単純です。 '$' に続いて、大文字で変数名となる語を挿入してください。 
     100 
     101例: 
     102{{{ 
     103SELECT id AS ticket,summary FROM ticket WHERE priority='$PRIORITY' 
     104}}} 
     105 
     106レポート閲覧時、 $PRIORITY に値を当てはめるためには、レポートの URL に引数として変数を与えてください。この変数名に '$' を入れてはいけません。 
     107 
     108例: 
     109{{{ 
     110 http://projects.edgewall.com/trac/reports/14?PRIORITY=high 
     111}}} 
     112 
     113複数の値を使用する場合、各値を'&'で区切ります。 
     114 
     115例: 
     116{{{ 
     117 http://projects.edgewall.com/trac/reports/14?PRIORITY=high&SEVERITY=critical 
     118}}} 
     119 
     120 
     121=== 特殊な定数 === 
     122実用的なレポートのために、定義済みの動的変数が用意されています。これらは URL に値を設定しなくても、自動的に値が割り当てられます。 
     123 
     124 * $USER -- ログインに使用したユーザ名。 
     125 
     126例 (''私が担当になっているチケット一覧''): 
     127{{{ 
     128SELECT id AS ticket,summary FROM ticket WHERE owner='$USER' 
     129}}} 
     130 
     131 
     132---- 
     133 
     134 
     135== 上級トピック: 表示形式のカスタマイズ == 
     136Trac には、レイアウトのカスタマイズや、グルーピング、ユーザ定義の CSS 利用などによる 
     137もっと複雑なレポートの作成も可能です。このようなレポートを作成するには、 
     138Trac のレポートエンジンが出力を制御するためのステートメントを含む、特別な SQL を使用します。 
     139 
     140== 特別なカラム == 
     141レポートを整形するため、 TracReports はクエリの結果から '特定の' カラム名を 
     142探します。このような '特定の' 名前で、最終的なレポートのレイアウトやスタイルが 
     143処理され、変更されます。 
     144 
     145=== 自動的に整形されるカラム名 === 
     146 * '''ticket''' -- チケットの ID が入っているカラムで使用します。該当する ID のカラムにハイパーリンクされます。 
     147 * '''created, modified, date, time''' -- 日付や時刻に整形されます。 
     148 
     149 * '''description''' -- チケットの説明が入っているカラムで使用します。 Wiki エンジンで処理されます。 
     150 
     151'''例:''' 
     152{{{ 
     153SELECT id as ticket, created, status, summary FROM ticket  
     154}}} 
     155 
     156=== 整形されるカラムのカスタマイズ === 
     157カラム名の前後に 2 つのアンダースコアがついている場合 (例: '''_''''''_color_''''''_''') は、 
     158''整形用のヒント'' として扱われ、レコードの整形が行われます。 
     159  
     160 * '''_''''''_group_''''''_''' -- 指定されたカラムで、表示がグループ化されます。各グループは、それぞれセクションヘッダとクエリ結果の表を持ちます。 
     161 * '''_''''''_color_''''''_''' -- 1 から 5 の数値である必要があります。値によって、あらかじめ定義された色付けが行われます。一般的な使用法は、優先度別の色付けです。 
     162 * '''_''''''_style_''''''_''' -- CSS 形式でレコードを整形できます。 
     163 
     164'''例:''' ''マイルストーン別未解決チケット (優先度別色付け)'' 
     165{{{ 
     166SELECT p.value AS __color__, 
     167     t.milestone AS __group__, 
     168     (CASE owner WHEN 'daniel' THEN 'font-weight: bold; background: red;' ELSE '' END) AS __style__, 
     169       t.id AS ticket, summary 
     170  FROM ticket t,enum p 
     171  WHERE t.status IN ('new', 'assigned', 'reopened')  
     172    AND p.name=t.priority AND p.type='priority' 
     173  ORDER BY t.milestone, p.value, t.severity, t.time 
     174}}} 
     175 
     176'''Note:''' ''ticket'' 表の優先度に対応する数値は、 ''enum'' 表を結合することで 
     177取り出しています。 
     178 
     179=== 行単位のレイアウト変更 === 
     180デフォルトでは、全てのカラムで1行を使い、上記の指定がされていれば、 
     181フォーマットされた形式で HTML に表示されます。それだけでなく、 
     182これから挙げる指定によって、複数行にわたってのレイアウトを行うことができます。 
     183 
     184 * '''column_''' -- ''改行''。 カラム名の語尾にアンダースコア ('_') を付与した場合、以降のカラムは次の行で表示されます。 
     185 
     186 * '''_column_''' -- ''全行表示''。 カラム名の前後にアンダースコア ('_') を付与した場合、そのカラムは続く行で全てのカラム幅を使って表示されます。 
     187 
     188 * '''_column'''  --  ''データを非表示にする''。 カラム名の語頭にアンダースコア ('_') を付与した場合、 HTML 出力では非表示になります。これは (CSV や RSS のような) 別フォーマットでのダウンロード時にだけ見たい情報であるときに使います。 
     189 
     190'''例:''' ''アクティブなチケットを、マイルストーンでグループ化し、優先度で色付け、チケットの説明を multi-line レイアウトでリスト表示する'' 
     191 
     192{{{ 
     193SELECT p.value AS __color__, 
     194       t.milestone AS __group__, 
     195       (CASE owner  
     196          WHEN 'daniel' THEN 'font-weight: bold; background: red;'  
     197          ELSE '' END) AS __style__, 
     198       t.id AS ticket, summary AS summary_,             -- ## ここで改行する 
     199       component,version, severity, milestone, status, owner, 
     200       time AS created, changetime AS modified,         -- ## 日付形式で整形 
     201       description AS _description_,                    -- ## 全行を使用して表示 
     202       changetime AS _changetime, reporter AS _reporter -- ## HTML 出力では表示しない 
     203  FROM ticket t,enum p 
     204  WHERE t.status IN ('new', 'assigned', 'reopened')  
     205    AND p.name=t.priority AND p.type='priority' 
     206  ORDER BY t.milestone, p.value, t.severity, t.time 
     207}}} 
     208 
     209=== カスタムフィールドをレポートで使用する === 
     210 
     211チケットにカスタムフィールドを追加した場合(バージョン0.8では実験的な機能でした。TracTicketsCustomFields 参照)、カスタムフィールドを含むSQLクエリを書くことができます。 ticket_custom テーブルを join をする必要がありますが、これは取り立てて簡単というわけではありません。 
     212 
     213追加のフィールドを trac.ini に宣言する ''前に'' 、チケットがデータベースに存在する場合、 ticket_custom テーブルには関連するデータを持たないことになります。これに起因する問題を回避するためには SQL の "LEFT OUTER JOIN" 節を使用してください。 
     214 
     215---- 
     216See also: TracTickets, TracQuery, TracGuide