Changes between Version 1 and Version 2 of TracTicketsCustomFields
- Timestamp:
- Nov 1, 2019, 11:11:25 AM (4 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
TracTicketsCustomFields
v1 v2 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.1 = Custom Ticket Fields 2 Trac supports adding custom, user-defined fields to the ticket module. With custom fields you can add typed, site-specific properties to tickets. 3 3 4 == Configuration == 4 == Configuration 5 5 6 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 … … 11 12 ... 12 13 }}} 14 13 15 The example below should help to explain the syntax. 14 16 15 === Available Field Types and Options === 17 === Field Names 18 A field name can only contain lowercase letters a-z, uppercase letters A-Z or digits 0-9, and must not start with a leading digit. 19 20 The following field names are reserved and can not be used for custom fields: 21 * cc 22 * changetime 23 * col 24 * comment 25 * component 26 * desc 27 * description 28 * format 29 * group 30 * groupdesc 31 * id 32 * keywords 33 * max 34 * milestone 35 * or 36 * order 37 * owner 38 * page 39 * priority 40 * report 41 * reporter 42 * resolution 43 * row 44 * severity 45 * status 46 * summary 47 * time 48 * type 49 * verbose 50 * version 51 52 === Available Field Types and Options 53 16 54 * '''text''': A simple (one line) text field. 17 55 * label: Descriptive label. 18 56 * value: Default value. 19 * order: Sort order placement. (Determines relative placement in forms.) 57 * order: Sort order placement; this determines relative placement in forms with respect to other custom fields. 58 * format: One of: 59 * `plain` for plain text 60 * `wiki` to interpret the content as WikiFormatting 61 * `reference` to treat the content as a queryable value (''since 1.0'') 62 * `list` to interpret the content as a list of queryable values, separated by whitespace (''since 1.0'') 20 63 * '''checkbox''': A boolean value check box. 21 64 * label: Descriptive label. 22 * value: Default value (0 or 1).65 * value: Default value, 0 or 1. 23 66 * order: Sort order placement. 24 67 * '''select''': Drop-down select box. Uses a list of values. 25 68 * label: Descriptive label. 26 69 * options: List of values, separated by '''|''' (vertical pipe). 27 * value: Default value ( Item #, starting at 0).70 * value: Default value (one of the values from options). 28 71 * order: Sort order placement. 29 72 * '''radio''': Radio buttons. Essentially the same as '''select'''. 30 73 * label: Descriptive label. 31 74 * options: List of values, separated by '''|''' (vertical pipe). 32 * value: Default value (Item #, starting at 0).75 * value: Default value, one of the values from options. 33 76 * order: Sort order placement. 34 77 * '''textarea''': Multi-line text area. 35 78 * label: Descriptive label. 36 79 * value: Default text. 37 * cols: Width in columns. 80 * cols: Width in columns. //(Removed in 1.1.2)// 38 81 * rows: Height in lines. 39 82 * order: Sort order placement. 83 * format: Either `plain` for plain text or `wiki` to interpret the content as WikiFormatting. 84 * '''time''': Date and time picker. (''Since 1.1.1.'') 85 * label: Descriptive label. 86 * value: Default date. 87 * order: Sort order placement. 88 * format: One of: 89 * `relative` for relative dates. 90 * `date` for absolute dates. 91 * `datetime` for absolute date and time values. 40 92 41 === Sample Config === 42 {{{ 93 If the `label` is not specified, it will be created by capitalizing the custom field name and replacing underscores with whitespaces. 94 95 Macros will be expanded when rendering `textarea` fields with format `wiki`, but not when rendering `text` fields with format `wiki`. 96 97 === Sample Configuration 98 99 {{{#!ini 43 100 [ticket-custom] 44 101 … … 48 105 test_two = text 49 106 test_two.label = Another text-box 50 test_two.value = Just a default value 107 test_two.value = Default [mailto:joe@nospam.com owner] 108 test_two.format = wiki 51 109 52 110 test_three = checkbox … … 57 115 test_four.label = My selectbox 58 116 test_four.options = one|two|third option|four 59 test_four.value = 2117 test_four.value = two 60 118 61 119 test_five = radio 62 120 test_five.label = Radio buttons are fun 63 121 test_five.options = uno|dos|tres|cuatro|cinco 64 test_five.value = 1122 test_five.value = dos 65 123 66 124 test_six = textarea … … 69 127 test_six.cols = 60 70 128 test_six.rows = 30 129 130 test_seven = time 131 test_seven.label = A relative date 132 test_seven.format = relative 133 test_seven.value = now 134 135 test_eight = time 136 test_eight.label = An absolute date 137 test_eight.format = date 138 test_eight.value = yesterday 139 140 test_nine = time 141 test_nine.label = A date and time 142 test_nine.format = datetime 143 test_nine.value = in 2 hours 71 144 }}} 72 145 73 '' Note: To make entering an option for a `select` type field optional, specify a leading `|` in the `fieldname.options` option.''146 '''Note''': To make a `select` type field optional, specify a leading `|` in the `fieldname.options` option. 74 147 75 === Reports Involving Custom Fields ===148 === Reports Involving Custom Fields 76 149 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.150 Custom ticket fields are stored in the `ticket_custom` table, not in the `ticket` table. So to display the values from custom fields in a report, you will need a join on the 2 tables. Let's use an example with a custom ticket field called `progress`. 78 151 79 The following example includes a custom ticket field named `progress` in the report: 80 {{{ 81 #!sql 152 {{{#!sql 153 SELECT p.value AS __color__, 154 id AS ticket, summary, owner, c.value AS progress 155 FROM ticket t, enum p, ticket_custom c 156 WHERE status IN ('assigned') AND t.id = c.ticket AND c.name = 'progress' 157 AND p.name = t.priority AND p.type = 'priority' 158 ORDER BY p.value 159 }}} 160 '''Note''': This will only show tickets that have progress set in them. This is '''not the same as showing all tickets'''. If you created this custom ticket field ''after'' you have already created some tickets, they will not have that field defined, and thus they will never show up on this ticket query. If you go back and modify those tickets, the field will be defined, and they will appear in the query. 161 162 However, if you want to show all ticket entries (with progress defined and without), you need to use a `JOIN` for every custom field that is in the query: 163 {{{#!sql 82 164 SELECT p.value AS __color__, 83 165 id AS ticket, summary, component, version, milestone, severity, … … 86 168 changetime AS _changetime, description AS _description, 87 169 reporter AS _reporter, 88 (CASE WHEN c.value = '0' THEN 'None' ELSE c.value END) AS progress170 (CASE WHEN c.value = '0' THEN 'None' ELSE c.value END) AS progress 89 171 FROM ticket t 90 172 LEFT OUTER JOIN ticket_custom c ON (t.id = c.ticket AND c.name = 'progress') … … 96 178 Note in particular the `LEFT OUTER JOIN` statement here. 97 179 180 Note that if your config file uses an '''uppercase''' name: 181 {{{#!ini 182 [ticket-custom] 183 184 Progress_Type = text 185 }}} 186 you would use '''lowercase''' in the SQL: `AND c.name = 'progress_type'`. 187 98 188 ---- 99 189 See also: TracTickets, TracIni
