| 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 |