Changes between Version 2 and Version 3 of TracTicketsCustomFields

Timestamp:

Sep 13, 2025, 3:01:44 PM (5 months ago)

Author:

trac

Comment:

--

TracTicketsCustomFields

@@ -4 +4 @@
 == Configuration
 
-Configuring custom ticket fields is done in the [wiki:TracIni trac.ini] file. All field definitions should be under a section named `[ticket-custom]`.
+Configure custom ticket fields in the [TracIni#ticket-custom-section "[ticket-custom]"] section of trac.ini.
 
 The syntax of each field definition is:
@@ -15 +15 @@
 The example below should help to explain the syntax.
 
+=== Field Names
+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.
+
+The following field names are reserved and can not be used for custom fields:
+* cc
+* changetime
+* col
+* comment
+* component
+* desc
+* description
+* format
+* group
+* groupdesc
+* id
+* keywords
+* max
+* milestone
+* or
+* order
+* owner
+* page
+* priority
+* report
+* reporter
+* resolution
+* row
+* severity
+* status
+* summary
+* time
+* type
+* verbose
+* version
+
 === Available Field Types and Options
 
@@ -20 +55 @@
    * label: Descriptive label.
    * value: Default value.
-   * order: Sort order placement; this determines relative placement in forms with respect to other custom fields.
-   * format: One of: 
-     * `plain` for plain text 
-     * `wiki` to interpret the content as WikiFormatting
-     * `reference` to treat the content as a queryable value (''since 1.0'') 
-     * `list` to interpret the content as a list of queryable values, separated by whitespace (''since 1.0'')
+   * order: Sort order placement relative to other custom fields.
+   * max_size: Maximum allowed size in characters (//Since 1.3.2//).
+   * format: One of:
+     * `plain` for plain text
+     * `wiki` for [WikiFormatting wiki formatted] content
+     * `reference` to treat the content as a queryable value
+     * `list` to interpret the content as a list of queryable values, separated by whitespace
+   * ticketlink_query: Query for linkifying ticket values.
+     Not applicable for format `plain` and `wiki`.
  * '''checkbox''': A boolean value check box.
    * label: Descriptive label.
    * value: Default value, 0 or 1.
    * order: Sort order placement.
+   * ticketlink_query: Query for linkifying ticket values.
  * '''select''': Drop-down select box. Uses a list of values.
    * label: Descriptive label.
@@ -35 +74 @@
    * value: Default value (one of the values from options).
    * order: Sort order placement.
+   * ticketlink_query: Query for linkifying ticket values.
  * '''radio''': Radio buttons. Essentially the same as '''select'''.
    * label: Descriptive label.
@@ -40 +80 @@
    * value: Default value, one of the values from options.
    * order: Sort order placement.
+   * ticketlink_query: Query for linkifying ticket values.
  * '''textarea''': Multi-line text area.
    * label: Descriptive label.
    * value: Default text.
-   * cols: Width in columns. //(Removed in 1.1.2)//
    * rows: Height in lines.
    * order: Sort order placement.
+   * max_size: Maximum allowed size in characters (//Since 1.3.2//).
    * format: Either `plain` for plain text or `wiki` to interpret the content as WikiFormatting.
- * '''time''': Date and time picker. (''Since 1.1.1.'')
+ * '''time''': Date and time picker. (//Since 1.1.1//)
    * label: Descriptive label.
    * value: Default date.
@@ -60 +101 @@
 Macros will be expanded when rendering `textarea` fields with format `wiki`, but not when rendering `text` fields with format `wiki`.
 
+For applicable fields, the `ticketlink_query` option
+overrides [[TracIni#query-ticketlink_query-option|"[query] ticketlink_query"]], and the format is the same as
+that option. When the `ticketlink_query` option
+is not specified, `[query]` `ticketlink_query` is used to
+linkify the field.
+
 === Sample Configuration
 
@@ -84 +131 @@
 test_five = radio
 test_five.label = Radio buttons are fun
-test_five.options = uno|dos|tres|cuatro|cinco
+test_five.options = |uno|dos|tres|cuatro|cinco
 test_five.value = dos
 
@@ -109 +156 @@
 }}}
 
-'''Note''': To make a `select` type field optional, specify a leading `|` in the `fieldname.options` option.
+'''Note''': To make a `select` type field optional, specify a leading `|` in `fieldname.options` (e.g. `test_five`).
 
 === Reports Involving Custom Fields
@@ -143 +190 @@
 Note in particular the `LEFT OUTER JOIN` statement here.
 
-Note that if your config file uses an '''uppercase''' name:
+Note that option names in trac.ini are case-insensitive, so even if your option name includes uppercase characters:
 {{{#!ini
 [ticket-custom]
-
 Progress_Type = text
 }}}
-you would use '''lowercase''' in the SQL: `AND c.name = 'progress_type'`.
+you must use '''lowercase''' in the SQL: `AND c.name = 'progress_type'`.
 
 ----