Version 28 (modified by 12 years ago) (diff) | ,
---|
Contents
Dynamically hide, default, copy, clear, validate, set ticket fields
NOTE: I suggest you use the 0.11 branch only even for Trac 0.12 installations. The Trac 0.12 branch has some issues. The plan is to merge the two branches to support both Trac 0.11 and 0.12 on one branch. Thanks. - robguttman
Description
This plugin dynamically changes fields in ticket views based on simple rules using JavaScript / jQuery (required for this plugin). Example dynamic behavior:
- Hide a field based on another field's value
- Default a field's value per user preference
- Clear a field's value when another field's value changes
- Copy one field's value to another field
- Validate a field's value
- Set a field's value based on another field's value
Configuration
- Install the plugin (after downloading and unzipping):
cd dynamicfieldsplugin/0.11 sudo python setup.py bdist_egg sudo cp dist/TracDynamicFields*.egg /your/trac/location/plugins/
See TracPlugins for more installation details and options. You'll likely need to restart Trac's web server after installation.
- Enable the plugin:
[components] dynfields.* = enabled
You can alternatively use the Trac Web Admin GUI to enable any or all rules.
See the examples section below for how to specify rules.
Bugs/Feature Requests
Existing bugs and feature requests for DynamicFieldsPlugin are here.
If you have any issues, create a new ticket.
Download
Download the zipped source from [download:dynamicfieldsplugin here].
Source
You can check out DynamicFieldsPlugin from here using Subversion, or browse the source with Trac.
Examples
This plugin currently includes six rules. Each rule is specified by modifying the [ticket-custom]
section of trac.ini
. Below are several examples to motivate using each rule.
Hide rule
Let'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:
[ticket-custom] effort.show_when_type = enhancement
If effort is specified for either enhancement or defect ticket types, then use pipe-delimited syntax to list both of them:
[ticket-custom] effort.show_when_type = enhancement|defect
If your version field is based upon the milestone, then this rule hides the version
field when the milestone
field's value is empty:
[ticket-custom] version.hide_when_milestone =
Some of your fields may be auto-generated or used by very few people. To always hide a field:
[ticket-custom] alwayshidden.hide_always = true alwayshidden.clear_on_hide = false
Fields that are always hidden will also be hidden on the custom query (/query
) page. The clear_on_hide
option above specifies that the field's value should not be cleared when hidden (clearing is the default behavior). Sometimes you want to allow users to get access to hidden fields. You can enable specific fields to be shown in ticket views when a user clicks a "Show hidden fields" link:
[ticket-custom] mostlyhidden.show_when_type = enhancement mostlyhidden.link_to_show = true
The default is that hidden fields are not enabled to be shown (i.e., link_to_show
defaults to false
). The "Show hidden fields" link is only shown when there are hidden fields and at least one of them is enabled to be shown.
Clear rule
In the version/milestone example above, if the milestone
changes then we want the version
field to be cleared:
[ticket-custom] version.clear_on_change_of = milestone
Note that 'clearing' a select field will actually reset it to its default value if no 'empty' option is available.
Copy rule
Let'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:
[ticket-custom] captain.copy_from = owner captain.overwrite = false
The default copy behavior is to not overwrite a value if one already exists. To always copy the value, set the overwrite
option to true.
Default rule
Let'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
:
[ticket-custom] type.default_value = (pref)
For text fields, if the field's value is not empty, the default value will not be applied unless you set an append
option to true:
[ticket-custom] cc.default_value = (pref) cc.append = true
Using append
presumes the field is a comma-delimited list and will append any missing values from the default preference value (which can also be a comma-delimited list) to that field's list.
The above example introduces the plugin's user preference facility described below.
Validate rule
Some fields may be required (i.e., can't be empty) or must not contain some specific values. For example:
[ticket-custom] owner.invalid_if = severity.invalid_if = pick one
The above will prevent the ticket from being submitted if either the owner
field is empty or the severity
field's value equals pick one. The value for the invalid_if
rule can be empty or any regular expression. Hidden fields do not get validated.
Set rule
When a developer starts working on a ticket, you may want to make sure she sets the milestone accordingly:
[ticket-custom] milestone.set_when_phase = implementation|verifying|releasing milestone.set_to = milestone3 milestone.overwrite = false
When the phase
field changes to either implementation, verifying, or releasing, then the milestone
will get set to milestone3. To avoid needing to update the current milestone's value, you can alternatively use the special "!" value which specifies to set the field to the first non-empty value:
milestone.set_to = !
If you want to enable each user to set the value as a preference, you should omit the set_to
option entirely and instead specify the rule as follows:
milestone.set_when_phase = implementation|verifying|releasing (pref) milestone.overwrite = false
Learn more about user preferences below. The default set behavior is to not overwrite a value if one already exists. To always set the value, set the overwrite
option to true.
User preferences
Any 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:
[ticket-custom] alwayshidden.show_when_type = invalid_value (pref)
The (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 for him/her. If you wish to disable a rule as the default preference, append (pref:disable) to the end of the rule like so:
[ticket-custom] alwayshidden.show_when_type = invalid_value (pref:disable)
Extensibility (implementation details)
Rules 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:
- rule specification (Python in
rules.py
) - rule implementation (JavaScript in
rules.js
)
The 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.
About i18n/l10n support
The 0.12 branch of this plugin is prepared for localization.
But English message texts are still the (POSIX) default. If this isn't your preferred language, you can
- look, if it's already available from the Trac plugin l10n project at Transifex or
- do it yourself (see the l10n cookbook page for Trac plugins for more details).
You've done a new translation? Superb! Contributing your translation is highly appreciated.
You could send it to the plugin's maintainer or contribute to Trac plugin l10n project
via Transifex:
Top translations: Trac_Plugin-L10N » dynfields
Preparing the plugin from source now requires the additional step of compiling message catalog files. As long as you stick to the message catalogs served with this plugin directly, there is still nothing special to be done. Just package your plugin from source the standard way:
cd dynamicfieldsplugin python ./setup.py bdist_egg
and the proper helper function calls to a suitable Babel install will be issued automatically for you. Beware, there is a Trac ticket strongly suggesting to do Babel install before Trac 0.12 install, or your Babel will not be functional with Trac. You're hit by this bug, if your message compilation does not produce any usable catalog.
Only if you encounter message catalogs with translations marked 'fuzzy', including them would require special treatment, since automatic compilation trashes them by default. Walk through:
cd dynamicfieldsplugin python ./setup.py compile_catalog -f python ./setup.py bdist_egg
Again, this is almost obsolete, and only needed to include translations marked as #, fuzzy
by the translator.
For more details see the l10n cookbook page for Trac plugins.
Recent Changes
Author/Contributors
Author: robguttman
Maintainer: robguttman
Contributors: hasienda