Changes between Initial Version and Version 1 of TracTicketsCustomFields


Ignore:
Timestamp:
Oct 15, 2008, 1:05:22 PM (16 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • TracTicketsCustomFields

    v1 v1  
     1= Custom Ticket Fields =
     2Trac 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 ==
     5Configuring custom ticket fields is done in the [wiki:TracIni trac.ini] file. All field definitions should be under a section named `[ticket-custom]`.
     6
     7The syntax of each field definition is:
     8{{{
     9 FIELD_NAME = TYPE
     10 (FIELD_NAME.OPTION = VALUE)
     11 ...
     12}}}
     13The 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
     45test_one = text
     46test_one.label = Just a text box
     47
     48test_two = text
     49test_two.label = Another text-box
     50test_two.value = Just a default value
     51
     52test_three = checkbox
     53test_three.label = Some checkbox
     54test_three.value = 1
     55
     56test_four = select
     57test_four.label = My selectbox
     58test_four.options = one|two|third option|four
     59test_four.value = 2
     60
     61test_five = radio
     62test_five.label = Radio buttons are fun
     63test_five.options = uno|dos|tres|cuatro|cinco
     64test_five.value = 1
     65
     66test_six = textarea
     67test_six.label = This is a large textarea
     68test_six.value = Default text
     69test_six.cols = 60
     70test_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
     77The 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
     79The following example includes a custom ticket field named `progress` in the report:
     80{{{
     81#!sql
     82SELECT 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
     96Note in particular the `LEFT OUTER JOIN` statement here.
     97
     98----
     99See also: TracTickets, TracIni