トップ | バージョン2 最新版 | バージョン3 β版

初期バージョン から バージョン 1 における更新: TracReports

差分発生行の前後
無視リスト:
更新日時:
2009/01/08 04:02:11 (12 年 前)
更新者:
trac (IP アドレス: 127.0.0.1)
コメント:

--

凡例:

変更なし
追加
削除
変更
  • TracReports

    v1 v1  
     1= レポート = #TracReports 
     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  ''これによって、ナビゲーションバーの "チケットを見る" (英語版では "View Tickets") でのデフォルトのハンドラがクエリモジュールになります。もし可能ならば、この設定を有効にして、レポート機能がなくなることによって生じる不都合を報告してください。'' 
     18 
     19  '''''ほとんど確実に httpd を再起動する必要があるでしょう。''''' 
     20 
     21レポートは以下の基本的なパーツから構成されます: 
     22 * '''ID''' -- ユニークな (連番の) 識別子 
     23 * '''レポート名 (Title)''' -- レポートのタイトル 
     24 * '''説明 (Description)''' -- WikiFormatting で記述された、レポートの説明。 
     25 * '''レポート本体 (Report Body)''' -- 後に述べるフォーマットで規定された、レポートクエリの結果。 
     26 * '''フッタ (Footer)''' -- レポート本体を異なる形式でダウンロードするためのリンク。 
     27 
     28== ソートの並び順変更 == #ChangingSortOrder 
     29単純なレポート (特にグループ化されていないもの) では、カラムのヘッダをクリックすれば、そのカラムでソートすることが出来ます。 
     30 
     31カラムのヘッダがハイパーリンク (赤) になっていれば、クリックすることでそのカラムでのソートができます。並び順を逆にするには、もう一度クリックします。 
     32 
     33== レポートの番号を変更する == #ChangingReportNumbering 
     34レポートの ID を変更する必要がある場合があるかもしれませんが、おそらくレポート自体を編集する方がベターです。というのも Trac のデータベースを変更する必要があるからです。 ''report'' 表は以下のようなスキーマとなっています (0.10 相当): 
     35 * id integer PRIMARY KEY 
     36 * author text 
     37 * title text 
     38 * query text 
     39 * description text 
     40ID を変更すると ''レポート一覧 (Available Reports)'' での表示順と番号、レポートのパーマリンクが変更されます。以下のような SQL を実行すると ID が変更されます: 
     41{{{ 
     42update report set id=5 where id=3; 
     43}}} 
     44メンテナンス結果、データベースの一貫性を保つ必要があることに留意してください (例えば ID はユニークでなければなりませんし、 SQLite などデータベースの上限値を超えることはできません)。 
     45 
     46== チケットをナビゲート == #NavigatingTickets 
     47レポートクエリ結果の 1 チケットをクリックするとそのチケットが表示されるでしょう。表示されたチケットのメインメニューバーのすぐ下にある ''次のチケット'' (英語版では ''Next Ticket'') または ''前のチケット'' (英語版では ''Previous Ticket'') リンクをクリックすることによって他のチケットに移動するか、''レポートに戻る'' (英語版では ''Back to Report'') リンクをクリックしてレポートページに戻ることができます。 
     48 
     49あなたは安全にチケットを編集することができます。またチケットの編集結果を保存した後で、 次のチケット/前のチケット/レポートに戻る (英語版では Next/Previous/Back to Report) のリンクを使用して結果を行き来することが可能です。しかし、あなたがチケットへの操作を終えてレポートに戻るときに、どのチケットが変更されたかのヒントは表示されません。この動作はカスタムクエリの動作とは異なります。 (カスタムクエリについては TracQuery#NavigatingTickets を参照して下さい) 。 ''(0.11 以降 )'' 
     50 
     51== ダウンロードできるフォーマット == #AlternativeDownloadFormats 
     52通常表示される HTML でのビューの加え、レポートはいろいろな形式で使用することができます。 
     53レポートページの一番下に、利用可能なデータ形式の一覧があります。望む形式のリンクをクリックすれば、 
     54その形式でのレポートをダウンロードすることができます。 
     55 
     56=== カンマ区切りテキスト - CSV (Comma Separated Values) === #Comma-delimited-CSVCommaSeparatedValues 
     571 レコードを 1 行として、各カラムをカンマ (',') で区切ったプレーンテキストとしてダウンロードできます。 
     58'''Note:''' CSV 形式を保つため、各カラムのデータに改行文字やカンマがある場合、その位置で切り取られます。 
     59 
     60=== タブ区切り === #Tab-delimited 
     61CSV と似ていますが、水平タブ文字 (\t) で区切られる点が違います。 
     62 
     63=== RSS - XML コンテンツ配信 === #RSS-XMLContentSyndication 
     64全てのレポートは、 XML/RSS 2.0 での配信が可能です。 RSS フィードを購読するにはページ下部にある、オレンジ色の 'XML' アイコンをクリックしてください。 Trac での RSS 対応についての一般的な情報は、 TracRss に記述しています。 
     65 
     66---- 
     67 
     68== カスタムレポートを作成する == #CreatingCustomReports 
     69 
     70''カスタムレポートを作成するためには、 SQL を楽に書ける程度の知識が必要です。'' 
     71 
     72レポートは基本的に、 Trac が実行できる形式の、名前がついた特定 SQL です。 
     73レポートに指定された SQL は、直接 Web インタフェースから閲覧したり、 
     74作成したりできます。 
     75 
     76通常のレポートは、 'ticket' 表に対する、カラムの選択や、ソート指定を伴った  
     77SELECT 文となります。 
     78 
     79== Ticket 表のカラム == #Ticketcolumns 
     80''ticket'' 表は、以下のカラムを持ちます: 
     81 * id           -- チケットID 
     82 * type         -- チケット分類 
     83 * time         -- 登録日時 
     84 * changetime   -- 最終更新日時 
     85 * component    -- コンポーネント 
     86 * severity     -- 重要度 
     87 * priority     -- 優先度 
     88 * owner        -- 担当者 
     89 * reporter     -- 報告者 
     90 * cc           -- 関係者 
     91 * version      -- バージョン 
     92 * milestone    -- マイルストーン 
     93 * status       -- ステータス 
     94 * resolution   -- 解決方法 
     95 * summary      -- チケットの概要 
     96 * description  -- チケットについての完全な説明 
     97 * keywords     -- キーワード 
     98 
     99各カラムに対応する属性の詳細な説明は、 TracTickets に記述しています。 
     100 
     101'''優先度順、登録日時順の全未解決チケット''' 
     102 
     103'''例:''' ''優先度順、登録日時順の全未解決チケット'' 
     104{{{ 
     105SELECT id AS ticket, status, severity, priority, owner,  
     106       time as created, summary FROM ticket  
     107  WHERE status IN ('new', 'assigned', 'reopened') 
     108  ORDER BY priority, time 
     109}}} 
     110 
     111 
     112---- 
     113 
     114 
     115== 上級トピック: 動的変数の使用 == #AdvancedReports:DynamicVariables 
     116レポートに汎用性を持たせる手段として、 ''動的変数'' をレポート SQL で使用する方法があります。 
     117簡単に言うと、動的変数とは、クエリを実行する前に置き換えられる ''特別な'' 文字列のことです。 
     118 
     119=== クエリで動的変数を使う方法 === #UsingVariablesinaQuery 
     120動的変数を使うためのシンタックスは単純です。 '$' に続いて、大文字で変数名となる語を挿入してください。 
     121 
     122例: 
     123{{{ 
     124SELECT id AS ticket,summary FROM ticket WHERE priority=$PRIORITY 
     125}}} 
     126 
     127レポート閲覧時、 $PRIORITY に値を当てはめるためには、レポートの URL に引数として変数を与えてください。この変数名に '$' を入れてはいけません。 
     128 
     129例: 
     130{{{ 
     131 http://trac.edgewall.org/reports/14?PRIORITY=high 
     132}}} 
     133 
     134複数の値を使用する場合、各値を '&' で区切ります。 
     135 
     136例: 
     137{{{ 
     138 http://trac.edgewall.org/reports/14?PRIORITY=high&SEVERITY=critical 
     139}}} 
     140 
     141 
     142=== 特殊な定数 === #SpecialConstantVariables 
     143実用的なレポートのために、定義済みの動的変数が用意されています。これらは URL に値を設定しなくても、自動的に値が割り当てられます。 
     144 
     145 * $USER -- ログインに使用したユーザ名。 
     146 
     147例 (''私が担当になっているチケット一覧''): 
     148{{{ 
     149SELECT id AS ticket,summary FROM ticket WHERE owner=$USER 
     150}}} 
     151 
     152 
     153---- 
     154 
     155 
     156== 上級トピック: 表示形式のカスタマイズ == #AdvancedReports:CustomFormatting 
     157Trac には、レイアウトのカスタマイズや、グルーピング、ユーザ定義の CSS 利用などによる 
     158もっと複雑なレポートの作成も可能です。このようなレポートを作成するには、  
     159Trac のレポートエンジンが出力を制御するためのステートメントを含む、特別な SQL を使用します。 
     160 
     161== 特別なカラム == #SpecialColumns 
     162レポートを整形するため、 TracReports はクエリの結果から '特定の' カラム名を 
     163探します。このような '特定の' 名前で、最終的なレポートのレイアウトやスタイルが 
     164処理され、変更されます。 
     165 
     166=== 自動的に整形されるカラム名 === #Automaticallyformattedcolumns 
     167 * '''ticket''' -- チケットの ID が入っているカラムで使用します。該当する ID のカラムにハイパーリンクされます。 (訳注: `summary` というカラム名もチケットにハイパーリンクされます。日本語版では `概要` でもリンクします。) 
     168 * '''created, modified, date, time''' -- 日付や時刻に整形されます。 (訳注: `datetime` という列名にすると日時で整形されます。日本語版では `時刻` で終わるカラムは `time` に、 `日付` で終わるカラムは `date` に、 `日時` で終わるカラムは `datetime` に、それぞれ整形されます。) 
     169 
     170 * '''description''' -- チケットの説明が入っているカラムで使用します。 Wiki エンジンで処理されます。 (訳注: 日本語版では `説明` でも整形されます。) 
     171 
     172'''例:''' 
     173{{{ 
     174SELECT id as ticket, created, status, summary FROM ticket  
     175}}} 
     176 
     177'''訳注''': Trac-0.11.1.ja1 以降のバージョンで作成した Environment では、デフォルトのレポートに日本語での整形ルールが適用されています。このような Environment を本家版 Trac で使用したい場合は各レポートの SQL を編集し、上記の日本語のカラム別名を英語に変更してください。 
     178 
     179=== 整形されるカラムのカスタマイズ === #Customformattingcolumns 
     180カラム名の前後に 2 つのアンダースコアがついている場合 (例: '''`__color__`''') は、  
     181''整形用のヒント'' として扱われ、レコードの整形が行われます。 
     182  
     183 * '''`__group__`''' -- 指定されたカラムで、表示がグループ化されます。各グループは、それぞれセクションヘッダとクエリ結果の表を持ちます。 
     184 * '''`__color__`''' -- 1 から 5 の数値である必要があります。値によって、あらかじめ定義された色付けが行われます。一般的な使用法は、優先度別の色付けです。 
     185{{{ 
     186#!html 
     187<div style="margin-left:7.5em">デフォルトの色付け:  
     188<span style="border: none; color: #333; background: transparent;  font-size: 85%; background: #fdc; border-color: #e88; color: #a22">Color 1</span> 
     189<span style="border: none; color: #333; background: transparent;  font-size: 85%; background: #ffb; border-color: #eea; color: #880">Color 2</span> 
     190<span style="border: none; color: #333; background: transparent;  font-size: 85%; background: #fbfbfb; border-color: #ddd; color: #444">Color 3</span> 
     191<span style="border: none; color: #333; background: transparent; font-size: 85%; background: #e7ffff; border-color: #cee; color: #099">Color 4</span> 
     192<span style="border: none; color: #333; background: transparent;  font-size: 85%; background: #e7eeff; border-color: #cde; color: #469">Color 5</span> 
     193</div> 
     194}}} 
     195 * '''`__style__`''' -- CSS 形式でレコードを整形できます。 
     196 
     197'''例:''' ''マイルストーン別未解決チケット (優先度別色付け)'' 
     198{{{ 
     199SELECT p.value AS __color__, 
     200     t.milestone AS __group__, 
     201     (CASE owner WHEN 'daniel' THEN 'font-weight: bold; background: red;' ELSE '' END) AS __style__, 
     202       t.id AS ticket, summary 
     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'''Note:''' ''ticket'' 表の優先度に対応する数値は、 ''enum'' 表を結合することで 
     210取り出しています。 
     211 
     212=== 行単位のレイアウト変更 === #Changinglayoutofreportrows 
     213デフォルトでは、全てのカラムで1行を使い、上記の指定がされていれば、 
     214フォーマットされた形式で HTML に表示されます。それだけでなく、 
     215これから挙げる指定によって、複数行にわたってのレイアウトを行うことができます。 
     216 
     217 * '''`column_`''' -- ''改行''。 カラム名の語尾にアンダースコア ('_') を付与した場合、以降のカラムは次の行で表示されます。 
     218 
     219 * '''`_column_`''' -- ''全行表示''。 カラム名の前後にアンダースコア ('_') を付与した場合、そのカラムは続く行で全てのカラム幅を使って表示されます。 
     220 
     221 * '''`_column`'''  --  ''データを非表示にする''。 カラム名の語頭にアンダースコア ('_') を付与した場合、 HTML 出力では非表示になります。これは (CSV や RSS のような) 別フォーマットでのダウンロード時にだけ見たい情報であるときに使います。 
     222 
     223'''例:''' ''アクティブなチケットを、マイルストーンでグループ化し、優先度で色付け、チケットの説明を multi-line レイアウトでリスト表示する'' 
     224 
     225{{{ 
     226SELECT p.value AS __color__, 
     227       t.milestone AS __group__, 
     228       (CASE owner  
     229          WHEN 'daniel' THEN 'font-weight: bold; background: red;'  
     230          ELSE '' END) AS __style__, 
     231       t.id AS ticket, summary AS summary_,             -- ## ここで改行する 
     232       component,version, severity, milestone, status, owner, 
     233       time AS created, changetime AS modified,         -- ## 日付形式で整形 
     234       description AS _description_,                    -- ## 全行を使用して表示 
     235       changetime AS _changetime, reporter AS _reporter -- ## HTML 出力では表示しない 
     236  FROM ticket t,enum p 
     237  WHERE t.status IN ('new', 'assigned', 'reopened')  
     238    AND p.name=t.priority AND p.type='priority' 
     239  ORDER BY t.milestone, p.value, t.severity, t.time 
     240}}} 
     241 
     242=== カスタムフィールドをレポートで使用する === #Reportingoncustomfields 
     243 
     244チケットにカスタムフィールドを追加した場合(バージョン 0.8 以降の機能。 TracTicketsCustomFields 参照)、カスタムフィールドを含む SQL クエリを書くことができます。 ticket_custom テーブルを join をする必要がありますが、これは取り立てて簡単というわけではありません。 
     245 
     246追加のフィールドを trac.ini に宣言する ''前に'' 、チケットがデータベースに存在する場合、 ticket_custom テーブルには関連するデータを持たないことになります。これに起因する問題を回避するためには SQL の "LEFT OUTER JOIN" 節を使用してください。 
     247 
     248'''Note レポートの追加、編集をするボタンを表示するためには権限を設定する必要があります。''' 
     249 
     250---- 
     251See also: TracTickets, TracQuery, TracGuide, [http://www.sqlite.org/lang_expr.html Query Language Understood by SQLite]