Changes between Version 3 and Version 4 of TracTicketsCustomFields


Ignore:
Timestamp:
Jan 3, 2024, 10:40:13 AM (11 months ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • TracTicketsCustomFields

    v3 v4  
    44== Configuration
    55
    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]`.
     6Configure custom ticket fields in the [TracIni#ticket-custom-section "[ticket-custom]"] section of trac.ini.
    77
    88The syntax of each field definition is:
    … …  
    1515The example below should help to explain the syntax.
    1616
     17=== Field Names
     18A 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
     20The 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
    1752=== Available Field Types and Options
    1853
    … …  
    2055   * label: Descriptive label.
    2156   * value: Default value.
    22    * order: Sort order placement; this determines relative placement in forms with respect to other custom fields.
    23    * format: One of:
    24      * `plain` for plain text
    25      * `wiki` to interpret the content as WikiFormatting
    26      * `reference` to treat the content as a queryable value (''since 1.0'')
    27      * `list` to interpret the content as a list of queryable values, separated by whitespace (''since 1.0'')
     57   * order: Sort order placement relative to other custom fields.
     58   * max_size: Maximum allowed size in characters (//Since 1.3.2//).
     59   * format: One of:
     60     * `plain` for plain text
     61     * `wiki` for [WikiFormatting wiki formatted] content
     62     * `reference` to treat the content as a queryable value
     63     * `list` to interpret the content as a list of queryable values, separated by whitespace
     64   * ticketlink_query: Query for linkifying ticket values.
     65     Not applicable for format `plain` and `wiki`.
    2866 * '''checkbox''': A boolean value check box.
    2967   * label: Descriptive label.
    3068   * value: Default value, 0 or 1.
    3169   * order: Sort order placement.
     70   * ticketlink_query: Query for linkifying ticket values.
    3271 * '''select''': Drop-down select box. Uses a list of values.
    3372   * label: Descriptive label.
    … …  
    3574   * value: Default value (one of the values from options).
    3675   * order: Sort order placement.
     76   * ticketlink_query: Query for linkifying ticket values.
    3777 * '''radio''': Radio buttons. Essentially the same as '''select'''.
    3878   * label: Descriptive label.
    … …  
    4080   * value: Default value, one of the values from options.
    4181   * order: Sort order placement.
     82   * ticketlink_query: Query for linkifying ticket values.
    4283 * '''textarea''': Multi-line text area.
    4384   * label: Descriptive label.
    4485   * value: Default text.
    45    * cols: Width in columns. //(Removed in 1.1.2)//
    4686   * rows: Height in lines.
    4787   * order: Sort order placement.
     88   * max_size: Maximum allowed size in characters (//Since 1.3.2//).
    4889   * format: Either `plain` for plain text or `wiki` to interpret the content as WikiFormatting.
    49  * '''time''': Date and time picker. (''Since 1.1.1.'')
     90 * '''time''': Date and time picker. (//Since 1.1.1//)
    5091   * label: Descriptive label.
    5192   * value: Default date.
    … …  
    60101Macros will be expanded when rendering `textarea` fields with format `wiki`, but not when rendering `text` fields with format `wiki`.
    61102
     103For applicable fields, the `ticketlink_query` option
     104overrides [[TracIni#query-ticketlink_query-option|"[query] ticketlink_query"]], and the format is the same as
     105that option. When the `ticketlink_query` option
     106is not specified, `[query]` `ticketlink_query` is used to
     107linkify the field.
     108
    62109=== Sample Configuration
    63110
    … …  
    84131test_five = radio
    85132test_five.label = Radio buttons are fun
    86 test_five.options = uno|dos|tres|cuatro|cinco
     133test_five.options = |uno|dos|tres|cuatro|cinco
    87134test_five.value = dos
    88135
    … …  
    109156}}}
    110157
    111 '''Note''': To make a `select` type field optional, specify a leading `|` in the `fieldname.options` option.
     158'''Note''': To make a `select` type field optional, specify a leading `|` in `fieldname.options` (e.g. `test_five`).
    112159
    113160=== Reports Involving Custom Fields
    … …  
    143190Note in particular the `LEFT OUTER JOIN` statement here.
    144191
    145 Note that if your config file uses an '''uppercase''' name:
     192Note that option names in trac.ini are case-insensitive, so even if your option name includes uppercase characters:
    146193{{{#!ini
    147194[ticket-custom]
    148 
    149195Progress_Type = text
    150196}}}
    151 you would use '''lowercase''' in the SQL: `AND c.name = 'progress_type'`.
     197you must use '''lowercase''' in the SQL: `AND c.name = 'progress_type'`.
    152198
    153199----