[[PageOutline(2-5,Contents,pullout)]] = Dynamically hide, default, copy, clear, etc. ticket fields = == 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 == Configuration == 1. 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 [http://trac.edgewall.org/wiki/TracPlugins TracPlugins] for more installation details and options. You'll likely need to restart Trac's web server after installation. 2. 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 [wiki:DynamicFieldsPlugin#Examples below] for how to specify rules. == Bugs/Feature Requests == Existing bugs and feature requests for DynamicFieldsPlugin are [report:9?COMPONENT=DynamicFieldsPlugin here]. If you have any issues, create a [http://trac-hacks.org/newticket?component=DynamicFieldsPlugin&owner=robguttman new ticket]. == Download == Download the zipped source from [download:dynamicfieldsplugin here]. == Source == You can check out DynamicFieldsPlugin from [http://trac-hacks.org/svn/dynamicfieldsplugin here] using Subversion, or [source:dynamicfieldsplugin browse the source] with Trac. == Examples == This plugin currently includes four 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.show_when_type = invalid_value alwayshidden.clear_on_hide = false }}} The {{{clear_on_hide}}} option above specifies that the field's value should not be cleared when hidden (clearing is the default behavior). ==== 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 }}} ==== 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 or the target field is hidden. To always copy the value, set the {{{overwrite}}} option to ''true''. ==== Default value 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) }}} The above example introduces the plugin's user preference facility described next. == 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. == 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: 1. rule specification (Python in {{{rules.py}}}) 1. 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.[[BR]] But English message texts are still the (POSIX) default. If this isn't your preferred language, you can 1. look, if it's already available from the [TracPluginTranslation Trac plugin l10n project] at [http://www.transifex.net/projects/p/Trac_Plugin-L10N/c/dynfields Transifex] or 2. do it yourself (see the [http://trac.edgewall.org/wiki/CookBook/PluginL10N#Dotranslatorswork l10n cookbook page for Trac plugins] for more details). You've done a new translation? Superb! Contributing your translation is highly appreciated.[[BR]] You could send it to the plugin's maintainer or contribute to [TracPluginTranslation Trac plugin l10n project] via [http://www.transifex.net/projects/p/Trac_Plugin-L10N/ Transifex]: Top translations: Trac_Plugin-L10N ยป [http://www.transifex.net/projects/p/Trac_Plugin-L10N/c/dynfields/ dynfields][[BR]] [[Image(http://www.transifex.net/projects/p/Trac_Plugin-L10N/c/dynfields/chart/image_png, title=Go to Trac_Plugin-L10N project page on Transifex.net, link=http://www.transifex.net/projects/p/Trac_Plugin-L10N/c/dynfields/)]] Kindly provided by [[Image(http://sw.transifex.net/2/static/charts/images/tx-logo-micro.png, link=http://www.transifex.net/, title=the open translation platform, valign=bottom)]] 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. 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 [t:wiki:CookBook/PluginL10N#Compileanduseit l10n cookbook page for Trac plugins]. == Recent Changes == [[ChangeLog(dynamicfieldsplugin, 3)]] == Author/Contributors == '''Author:''' [wiki:robguttman] [[BR]] '''Maintainer:''' [wiki:robguttman] [[BR]] '''Contributors:''' [wiki:hasienda]