39
|
1 = Custom Ticket Fields =
|
|
2 Trac supports adding custom, user-defined fields to the ticket module. Using custom fields, you can add typed, site-specific properties to tickets.
|
|
3
|
|
4 == Configuration ==
|
|
5 Configuring custom ticket fields is done in the [wiki:TracIni trac.ini] file. All field definitions should be under a section named `[ticket-custom]`.
|
|
6
|
|
7 The syntax of each field definition is:
|
|
8 {{{
|
|
9 FIELD_NAME = TYPE
|
|
10 (FIELD_NAME.OPTION = VALUE)
|
|
11 ...
|
|
12 }}}
|
|
13 The example below should help to explain the syntax.
|
|
14
|
|
15 === Available Field Types and Options ===
|
|
16 * '''text''': A simple (one line) text field.
|
|
17 * label: Descriptive label.
|
|
18 * value: Default value.
|
|
19 * order: Sort order placement. (Determines relative placement in forms.)
|
|
20 * '''checkbox''': A boolean value check box.
|
|
21 * label: Descriptive label.
|
|
22 * value: Default value (0 or 1).
|
|
23 * order: Sort order placement.
|
|
24 * '''select''': Drop-down select box. Uses a list of values.
|
|
25 * options: List of values, separated by '''|''' (vertical pipe).
|
|
26 * value: Default value (Item #, starting at 0).
|
|
27 * order: Sort order placement.
|
|
28 * '''radio''': Radio buttons. Essentially the same as '''select'''.
|
|
29 * label: Descriptive label.
|
|
30 * options: List of values, separated by '''|''' (vertical pipe).
|
|
31 * value: Default value (Item #, starting at 0).
|
|
32 * order: Sort order placement.
|
|
33 * '''textarea''': Multi-line text area.
|
|
34 * label: Descriptive label.
|
|
35 * value: Default text.
|
|
36 * cols: Width in columns.
|
|
37 * rows: Height in lines.
|
|
38 * order: Sort order placement.
|
|
39
|
|
40 === Sample Config ===
|
|
41 {{{
|
|
42 [ticket-custom]
|
|
43
|
|
44 test_one = text
|
|
45 test_one.label = Just a text box
|
|
46
|
|
47 test_two = text
|
|
48 test_two.label = Another text-box
|
|
49 test_two.value = Just a default value
|
|
50
|
|
51 test_three = checkbox
|
|
52 test_three.label = Some checkbox
|
|
53 test_three.value = 1
|
|
54
|
|
55 test_four = select
|
|
56 test_four.label = My selectbox
|
|
57 test_four.options = one|two|third option|four
|
|
58 test_four.value = 2
|
|
59
|
|
60 test_five = radio
|
|
61 test_five.label = Radio buttons are fun
|
|
62 test_five.options = uno|dos|tres|cuatro|cinco
|
|
63 test_five.value = 1
|
|
64
|
|
65 test_six = textarea
|
|
66 test_six.label = This is a large textarea
|
|
67 test_six.value = Default text
|
|
68 test_six.cols = 60
|
|
69 test_six.rows = 30
|
|
70 }}}
|
|
71
|
|
72 ''Note: To make an entering an option for a `select` type field optional, specify a leading `|` in the `fieldname.options` option.''
|
|
73
|
|
74 === Reports Involving Custom Fields ===
|
|
75
|
|
76 The SQL required for TracReports to include custom ticket fields is relatively hard to get right. You need a `JOIN` with the `ticket_custom` field for every custom field that should be involved.
|
|
77
|
|
78 The following example includes a custom ticket field named `progress` in the report:
|
|
79 {{{
|
|
80 #!sql
|
|
81 SELECT p.value AS __color__,
|
|
82 id AS ticket, summary, component, version, milestone, severity,
|
|
83 (CASE status WHEN 'assigned' THEN owner||' *' ELSE owner END) AS owner,
|
|
84 time AS created,
|
|
85 changetime AS _changetime, description AS _description,
|
|
86 reporter AS _reporter,
|
|
87 (CASE WHEN c.value = '0' THEN 'None' ELSE c.value END) AS progress
|
|
88 FROM ticket t
|
|
89 LEFT OUTER JOIN ticket_custom c ON (t.id = c.ticket AND c.name = 'progress')
|
|
90 JOIN enum p ON p.name = t.priority AND p.type='priority'
|
|
91 WHERE status IN ('new', 'assigned', 'reopened')
|
|
92 ORDER BY p.value, milestone, severity, time
|
|
93 }}}
|
|
94
|
|
95 Note in particular the `LEFT OUTER JOIN` statement here.
|
|
96
|
|
97 ----
|
|
98 See also: TracTickets, TracIni |