Changes between Initial Version and Version 1 of DynamicFieldsPlugin


Ignore:
Timestamp:
Jun 29, 2010, 4:05:07 PM (14 years ago)
Author:
Rob Guttman
Comment:

New hack DynamicFieldsPlugin, created by robguttman

Legend:

Unmodified
Added
Removed
Modified
  • DynamicFieldsPlugin

    v1 v1  
     1[[PageOutline(2-5,Contents,pullout)]]
     2
     3= Dynamically hide, default, copy, clear, etc. ticket fields =
     4
     5== Description ==
     6
     7This plugin dynamically changes fields in ticket views based on simple rules using !JavaScript / jQuery (required for this plugin).  Example dynamic behavior:
     8
     9 * Hide a field based on another field's value
     10 * Default a field's value per user preference
     11 * Clear a field's value when another field's value changes
     12 * Copy one field's value to another field
     13
     14
     15== Configuration ==
     16To enable the plugin:
     17
     18{{{
     19[components]
     20dynfields.* = enabled
     21}}}
     22
     23See the examples section next for how to specify rules.
     24 
     25
     26== Bugs/Feature Requests ==
     27
     28Existing bugs and feature requests for DynamicFieldsPlugin are
     29[report:9?COMPONENT=DynamicFieldsPlugin here].
     30
     31If you have any issues, create a
     32[http://trac-hacks.org/newticket?component=DynamicFieldsPlugin&owner=robguttman new ticket].
     33
     34== Download ==
     35
     36Download the zipped source from [download:dynamicfieldsplugin here].
     37
     38== Source ==
     39
     40You can check out DynamicFieldsPlugin from [http://trac-hacks.org/svn/dynamicfieldsplugin here] using Subversion, or [source:dynamicfieldsplugin browse the source] with Trac.
     41
     42== Example ==
     43
     44The plugin currently includes four rules which can be extended using Trac's component architecture.  Each rule is specified by modifying the {{{[ticket-custom]}}} section of {{{trac.ini}}}.  Below are several examples to motivate using each rule.
     45
     46==== Hide rule ====
     47Let's say that your team only specifies effort for enhancements, but not for defects or other ticket types.  This rule shows a custom {{{effort}}} field only when the {{{type}}} field's value is ''enhancement'':
     48{{{
     49[ticket-custom]
     50effort.show_when_type = enhancement
     51}}}
     52
     53If your version field is based upon the milestone, then this rule hides the {{{version}}} field when the {{{milestone}}} field's value is empty:
     54{{{
     55[ticket-custom]
     56version.hide_when_milestone =
     57}}}
     58
     59Some of your fields may be auto-generated or used by very few people.  To always hide a field:
     60{{{
     61[ticket-custom]
     62alwayshidden.show_when_type = invalid_value
     63alwayshidden.clear_on_hide = false
     64}}}
     65
     66The {{{clear_on_hide}}} option above specifies that the field's value should not be cleared when hidden (which is the default behavior).
     67
     68
     69==== Clear rule ====
     70In the version/milestone example above, if the {{{milestone}}} changes then we want the {{{version}}} field to be cleared:
     71{{{
     72[ticket-custom]
     73version.clear_on_change = milestone
     74}}}
     75
     76==== Copy rule ====
     77Let's say your workflow includes reassigning a ticket's {{{owner}}} to someone else for review or verification but maintain the person responsible for the work in a custom {{{captain}}} field.  Initially the {{{captain}}} should be set to the {{{owner}}}, so to reduce data entry in making this so:
     78{{{
     79[ticket-custom]
     80captain.copy_from = owner
     81}}}
     82
     83==== Default value rule ====
     84Let's say your QA team usually creates defect tickets and your product managers usually create enhancement tickets.  Here's how to allow each user to set the default value for the ticket {{{type}}}:
     85{{{
     86[ticket-custom]
     87type.default_value = (pref)
     88}}}
     89
     90The above example introduces the plugin's user preference facility described next.
     91
     92== User preferences ==
     93Any rule expressed above can be configured to allow users to set preferences for them by appending ''(pref)'' to the end of the rule - for example, here's one of the hide rules from above:
     94{{{
     95[ticket-custom]
     96alwayshidden.show_when_type = invalid_value (pref)
     97}}}
     98
     99The ''(pref)'' will cause this rule to be added to a new '''Dynamic Fields''' preference panel where the user can disable the rule by unchecking the rule's checkbox.  Some rules require user input such as the default value rule above.  In that example, the user can both enable/disable the rule as well as set the field's default value that the rule should use for him/her.
     100
     101== Extensibility (implementation details) ==
     102Rules are implemented as Trac extension points to allow for new rules to be added fairly easily.  Four rules come packaged to provide the dynamic behaviors described above.  Each rule is split between two parts:
     103
     104 1. rule specification (Python in {{{rules.py}}})
     105 1. rule implementation (!JavaScript in {{{rules.js}}})
     106
     107The two parts are linked by instantiating the !JavaScript part with the class name of the python part.  See the code for details.  !JavaScript was chosen over Genshi transforms to dynamically have fields change without requiring a form submission - hence the plugin's name, Dynamic Fields.
     108
     109
     110== Recent Changes ==
     111
     112[[ChangeLog(dynamicfieldsplugin, 3)]]
     113
     114== Author/Contributors ==
     115
     116'''Author:''' [wiki:robguttman] [[BR]]
     117'''Maintainer:''' [wiki:robguttman] [[BR]]
     118'''Contributors:'''