Legend:

Rather than have its own report definition format, TracReports relies on standard SQL

8

SELECT statements for custom report definition.

8

`SELECT` statements for custom report definition.

9

10

'''Note:''' ''The report module is being phased out in its current form because it seriously limits the ability of the Trac team to make adjustments to the underlying database schema. We believe that the [wiki:TracQuery query module] is a good replacement that provides more flexibility and better usability. While there are certain reports that cannot yet be handled by the query module, we intend to further enhance it so that at some point the reports module can be completely removed. This also means that there will be no major enhancements to the report module anymore.''

11

12

''You can already completely replace the reports module by the query module simply by disabling the former in [wiki:TracIni trac.ini]:''

13

{{{

14

[components]

15

trac.ticket.report.* = disabled

16

}}}

17

''This will make the query module the default handler for the “View Tickets” navigation item. We encourage you to try this configuration and report back what kind of features of reports you are missing, if any.''

18

9

19

10

20

A report consists of these basic parts:

11

* ID -- Unique (sequential) identifier

12

* Title -- Descriptive title

13

* Description -- A brief description of the report, in WikiFormatting text.

14

* Report Body -- List of results from report query, formatted according to the methods described below.

15

* Footer -- Links to alternative download formats for this report.

16

21

* '''ID''' — Unique (sequential) identifier

22

* '''Title''' — Descriptive title

23

* '''Description''' — A brief description of the report, in WikiFormatting text.

24

* '''Report Body''' — List of results from report query, formatted according to the methods described below.

If a column header is a hyperlink (red), click the column you would like to sort by. Clicking the same header again reverses the order.

22

31

23

24

== Alternate Download Formats ==

25

Aside from the default HTML view, reports can also be exported in a number of alternate formats.

32

== Changing Report Numbering ==

33

There may be instances where you need to change the ID of the report, perhaps to organize the reports better. At present this requires changes to the trac database. The ''report'' table has the following schema ''(since 0.10)'':

34

* id integer PRIMARY KEY

35

* author text

36

* title text

37

* query text

38

* description text

39

Changing the ID changes the shown order and number in the ''Available Reports'' list and the report's perma-link. This is done by running something like:

40

{{{

41

update report set id=5 where id=3;

42

}}}

43

Keep in mind that the integrity has to be maintained (i.e., ID has to be unique, and you don't want to exceed the max, since that's managed by SQLite someplace).

44

45

You may also need to update or remove the report number stored in the report or query.

46

47

== Navigating Tickets ==

48

Clicking on one of the report results will take you to that ticket. You can navigate through the results by clicking the ''Next Ticket'' or ''Previous Ticket'' links just below the main menu bar, or click the ''Back to Report'' link to return to the report page.

49

50

You can safely edit any of the tickets and continue to navigate through the results using the ''!Next/Previous/Back to Report'' links after saving your results, but when you return to the report, there will be no hint about what has changed, as would happen if you were navigating a list of tickets obtained from a query (see TracQuery#NavigatingTickets). ''(since 0.11)''

51

52

== Alternative Download Formats ==

53

Aside from the default HTML view, reports can also be exported in a number of alternative formats.

26

54

At the bottom of the report page, you will find a list of available data formats. Click the desired link to

27

download the alternate report format.

55

download the alternative report format.

28

56

29

57

=== Comma-delimited - CSV (Comma Separated Values) ===

30

58

Export the report as plain text, each row on its own line, columns separated by a single comma (',').

31

'''Note:''' Column data is stripped from carriage returns, line feeds and commas to preserve structure.

59

'''Note:''' The output is fully escaped so carriage returns, line feeds, and commas will be preserved in the output.

By default, all columns on each row are display on a single row in the HTML

166

216

report, possibly formatted according to the descriptions above. However, it's

167

217

also possible to create multi-line report entries.

168

218

169

* '''column_''' -- ''Break row after this''. By appending an underscore ('_') to the column name, the remaining columns will be be continued on a second line.

170

171

* '''_column_''' -- ''Full row''. By adding an underscore ('_') both at the beginning and the end of a column name, the data will be shown on a separate row.

172

173

* '''_column''' -- ''Hide data''. Prepending an underscore ('_') to a column name instructs Trac to hide the contents from the HTML output. This is useful for information to be visible only if downloaded in other formats (like CSV or RSS/XML).

219

* '''`column_`''' — ''Break row after this''. By appending an underscore ('_') to the column name, the remaining columns will be be continued on a second line.

220

221

* '''`_column_`''' — ''Full row''. By adding an underscore ('_') both at the beginning and the end of a column name, the data will be shown on a separate row.

222

223

* '''`_column`''' — ''Hide data''. Prepending an underscore ('_') to a column name instructs Trac to hide the contents from the HTML output. This is useful for information to be visible only if downloaded in other formats (like CSV or RSS/XML).

224

This can be used to hide any kind of column, even important ones required for identifying the resource, e.g. `id as _id` will hide the '''Id''' column but the link to the ticket will be present.

If you have added custom fields to your tickets (a feature since v0.8, see TracTicketsCustomFields), you can write a SQL query to cover them. You'll need to make a join on the ticket_custom table, but this isn't especially easy.

248

249

If you have tickets in the database ''before'' you declare the extra fields in trac.ini, there will be no associated data in the ticket_custom table. To get around this, use SQL's "LEFT OUTER JOIN" clauses. See [trac:TracIniReportCustomFieldSample TracIniReportCustomFieldSample] for some examples.

250

251

'''Note that you need to set up permissions in order to see the buttons for adding or editing reports.'''