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