| 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 | * label: Descriptive label. |
---|
| 26 | * options: List of values, separated by '''|''' (vertical pipe). |
---|
| 27 | * value: Default value (Item #, starting at 0). |
---|
| 28 | * order: Sort order placement. |
---|
| 29 | * '''radio''': Radio buttons. Essentially the same as '''select'''. |
---|
| 30 | * label: Descriptive label. |
---|
| 31 | * options: List of values, separated by '''|''' (vertical pipe). |
---|
| 32 | * value: Default value (Item #, starting at 0). |
---|
| 33 | * order: Sort order placement. |
---|
| 34 | * '''textarea''': Multi-line text area. |
---|
| 35 | * label: Descriptive label. |
---|
| 36 | * value: Default text. |
---|
| 37 | * cols: Width in columns. |
---|
| 38 | * rows: Height in lines. |
---|
| 39 | * order: Sort order placement. |
---|
| 40 | |
---|
| 41 | === Sample Config === |
---|
| 42 | {{{ |
---|
| 43 | [ticket-custom] |
---|
| 44 | |
---|
| 45 | test_one = text |
---|
| 46 | test_one.label = Just a text box |
---|
| 47 | |
---|
| 48 | test_two = text |
---|
| 49 | test_two.label = Another text-box |
---|
| 50 | test_two.value = Just a default value |
---|
| 51 | |
---|
| 52 | test_three = checkbox |
---|
| 53 | test_three.label = Some checkbox |
---|
| 54 | test_three.value = 1 |
---|
| 55 | |
---|
| 56 | test_four = select |
---|
| 57 | test_four.label = My selectbox |
---|
| 58 | test_four.options = one|two|third option|four |
---|
| 59 | test_four.value = 2 |
---|
| 60 | |
---|
| 61 | test_five = radio |
---|
| 62 | test_five.label = Radio buttons are fun |
---|
| 63 | test_five.options = uno|dos|tres|cuatro|cinco |
---|
| 64 | test_five.value = 1 |
---|
| 65 | |
---|
| 66 | test_six = textarea |
---|
| 67 | test_six.label = This is a large textarea |
---|
| 68 | test_six.value = Default text |
---|
| 69 | test_six.cols = 60 |
---|
| 70 | test_six.rows = 30 |
---|
| 71 | }}} |
---|
| 72 | |
---|
| 73 | ''Note: To make entering an option for a `select` type field optional, specify a leading `|` in the `fieldname.options` option.'' |
---|
| 74 | |
---|
| 75 | === Reports Involving Custom Fields === |
---|
| 76 | |
---|
| 77 | 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. |
---|
| 78 | |
---|
| 79 | The following example includes a custom ticket field named `progress` in the report: |
---|
| 80 | {{{ |
---|
| 81 | #!sql |
---|
| 82 | SELECT p.value AS __color__, |
---|
| 83 | id AS ticket, summary, component, version, milestone, severity, |
---|
| 84 | (CASE status WHEN 'assigned' THEN owner||' *' ELSE owner END) AS owner, |
---|
| 85 | time AS created, |
---|
| 86 | changetime AS _changetime, description AS _description, |
---|
| 87 | reporter AS _reporter, |
---|
| 88 | (CASE WHEN c.value = '0' THEN 'None' ELSE c.value END) AS progress |
---|
| 89 | FROM ticket t |
---|
| 90 | LEFT OUTER JOIN ticket_custom c ON (t.id = c.ticket AND c.name = 'progress') |
---|
| 91 | JOIN enum p ON p.name = t.priority AND p.type='priority' |
---|
| 92 | WHERE status IN ('new', 'assigned', 'reopened') |
---|
| 93 | ORDER BY p.value, milestone, severity, time |
---|
| 94 | }}} |
---|
| 95 | |
---|
| 96 | Note in particular the `LEFT OUTER JOIN` statement here. |
---|
| 97 | |
---|
| 98 | ---- |
---|
| 99 | See also: TracTickets, TracIni |