Changes between Version 3 and Version 4 of TracTicketsCustomFields


Ignore:
Timestamp:
Sep 16, 2025, 5:57:38 PM (5 days ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • TracTicketsCustomFields

    v3 v4  
    11= Custom Ticket Fields
     2
    23Trac supports adding custom, user-defined fields to the ticket module. With custom fields you can add typed, site-specific properties to tickets.
    34
    45== Configuration
    56
    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]`.
     7Configure custom ticket fields in the [TracIni#ticket-custom-section "[ticket-custom]"] section of trac.ini.
    78
    89The syntax of each field definition is:
    … …  
    1617
    1718=== Field Names
     19
    1820A 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.
    1921
    … …  
    5557   * label: Descriptive label.
    5658   * value: Default value.
    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'')
     59   * order: Sort order placement relative to other custom fields.
     60   * max_size: Maximum allowed size in characters (//Since 1.3.2//).
     61   * format: One of:
     62     * `plain` for plain text
     63     * `wiki` for [WikiFormatting wiki formatted] content
     64     * `reference` to treat the content as a queryable value
     65     * `list` to interpret the content as a list of queryable values, separated by whitespace
    6366 * '''checkbox''': A boolean value check box.
    6467   * label: Descriptive label.
    … …  
    7881   * label: Descriptive label.
    7982   * value: Default text.
    80    * cols: Width in columns. //(Removed in 1.1.2)//
    8183   * rows: Height in lines.
    8284   * order: Sort order placement.
     85   * max_size: Maximum allowed size in characters (//Since 1.3.2//).
    8386   * format: Either `plain` for plain text or `wiki` to interpret the content as WikiFormatting.
    84  * '''time''': Date and time picker. (''Since 1.1.1.'')
     87 * '''time''': Date and time picker. (//Since 1.1.1//)
    8588   * label: Descriptive label.
    8689   * value: Default date.
    … …  
    119122test_five = radio
    120123test_five.label = Radio buttons are fun
    121 test_five.options = uno|dos|tres|cuatro|cinco
     124test_five.options = |uno|dos|tres|cuatro|cinco
    122125test_five.value = dos
    123126
    … …  
    144147}}}
    145148
    146 '''Note''': To make a `select` type field optional, specify a leading `|` in the `fieldname.options` option.
     149'''Note''': To make a `select` type field optional, specify a leading `|` in `fieldname.options` (e.g. `test_five`).
    147150
    148151=== Reports Involving Custom Fields
    … …  
    153156SELECT p.value AS __color__,
    154157   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
     158FROM ticket t, enum p, ticket_custom c
     159WHERE status IN ('assigned') AND t.id = c.ticket AND c.name = 'progress'
     160  AND p.name = t.priority AND p.type = 'priority'
     161ORDER BY p.value
    159162}}}
    160163'''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.
    … …  
    169172   reporter AS _reporter,
    170173   (CASE WHEN c.value = '0' THEN 'None' ELSE c.value END) AS progress
    171   FROM ticket t
    172      LEFT OUTER JOIN ticket_custom c ON (t.id = c.ticket AND c.name = 'progress')
    173      JOIN enum p ON p.name = t.priority AND p.type='priority'
    174   WHERE status IN ('new', 'assigned', 'reopened')
    175   ORDER BY p.value, milestone, severity, time
     174FROM ticket t
     175   LEFT OUTER JOIN ticket_custom c ON (t.id = c.ticket AND c.name = 'progress')
     176   JOIN enum p ON p.name = t.priority AND p.type = 'priority'
     177WHERE status IN ('new', 'assigned', 'reopened')
     178ORDER BY p.value, milestone, severity, time
    176179}}}
    177180
    178181Note in particular the `LEFT OUTER JOIN` statement here.
    179182
    180 Note that if your config file uses an '''uppercase''' name:
     183Note that option names in trac.ini are case-insensitive, so even if your option name includes uppercase characters:
    181184{{{#!ini
    182185[ticket-custom]
    183 
    184186Progress_Type = text
    185187}}}
    186 you would use '''lowercase''' in the SQL: `AND c.name = 'progress_type'`.
     188you must use '''lowercase''' in the SQL: `AND c.name = 'progress_type'`.
    187189
    188190----