Changes between Version 1 and Version 2 of TracTicketsCustomFields


Ignore:
Timestamp:
Apr 9, 2008, 4:17:48 PM (17 years ago)
Author:
trac
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • TracTicketsCustomFields

    v1 v2  
    11= Custom Ticket Fields =
    2 Trac support adding custom, user-defined, fields to the ticket module. Using custom fields, you can add typed, site-specific, properties to tickets.
     2Trac supports adding custom, user-defined fields to the ticket module. Using custom fields, you can add typed, site-specific properties to tickets.
    33
    4 '''Note: In Trac 0.8, this feature is still experimental.'''
    5 
    6 == Configuriation ==
    7 Configuring custom ticket fields is done in the TracIni config file.
    8 
    9 All field definitions should be under a section named [ticket-custom] in the ini-file.
     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]`.
    106
    117The syntax of each field definition is:
    … …  
    1511 ...
    1612}}}
    17 Looking at the example below should help explain the syntax.
     13The example below should help to explain the syntax.
    1814
    1915=== Available Field Types and Options ===
    … …  
    2117   * label: Descriptive label.
    2218   * value: Default value.
    23    * order: Sort order placement. (Determines relative placement in forms.)
     19   * order: Sort order placement. (Determines relative placement in forms with respect to other custom fields.)
    2420 * '''checkbox''': A boolean value check box.
    2521   * label: Descriptive label.
    … …  
    2723   * order: Sort order placement.
    2824 * '''select''': Drop-down select box. Uses a list of values.
     25   * label: Descriptive label.
    2926   * options: List of values, separated by '''|''' (vertical pipe).
    30    * value: Default value (Item #, starting at 0).
     27   * value: Default value (one of the values from options).
    3128   * order: Sort order placement.
    3229 * '''radio''': Radio buttons. Essentially the same as '''select'''.
    … …  
    3835   * label: Descriptive label.
    3936   * value: Default text.
    40    * width: Width in columns.
    41    * height: Height in lines.
     37   * cols: Width in columns.
     38   * rows: Height in lines.
    4239   * order: Sort order placement.
    4340
    … …  
    4542{{{
    4643[ticket-custom]
     44
    4745test_one = text
    4846test_one.label = Just a text box
    … …  
    5957test_four.label = My selectbox
    6058test_four.options = one|two|third option|four
    61 test_four.value = 2
     59test_four.value = two
    6260
    6361test_five = radio
    … …  
    6967test_six.label = This is a large textarea
    7068test_six.value = Default text
    71 test_six.width = 60
    72 test_six.height = 30
     69test_six.cols = 60
     70test_six.rows = 30
    7371}}}
     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
     77Custom 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
     79{{{
     80#!sql
     81SELECT p.value AS __color__,
     82   id AS ticket, summary, owner, c.value AS progress
     83  FROM ticket t, enum p, ticket_custom c
     84  WHERE status IN ('assigned') AND t.id = c.ticket AND c.name = 'progress'
     85AND p.name = t.priority AND p.type = 'priority'
     86  ORDER BY p.value
     87}}}
     88'''Note''' that this will only show tickets that have progress set in them, which 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. If that's all you want, you're set.
     89
     90However, 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.
     91{{{
     92#!sql
     93SELECT p.value AS __color__,
     94   id AS ticket, summary, component, version, milestone, severity,
     95   (CASE status WHEN 'assigned' THEN owner||' *' ELSE owner END) AS owner,
     96   time AS created,
     97   changetime AS _changetime, description AS _description,
     98   reporter AS _reporter,
     99  (CASE WHEN c.value = '0' THEN 'None' ELSE c.value END) AS progress
     100  FROM ticket t
     101     LEFT OUTER JOIN ticket_custom c ON (t.id = c.ticket AND c.name = 'progress')
     102     JOIN enum p ON p.name = t.priority AND p.type='priority'
     103  WHERE status IN ('new', 'assigned', 'reopened')
     104  ORDER BY p.value, milestone, severity, time
     105}}}
     106
     107Note in particular the `LEFT OUTER JOIN` statement here.
    74108
    75109----