Changes between Version 42 and Version 43 of DynamicFieldsPlugin
- Timestamp:
- Mar 17, 2015, 10:31:41 AM (9 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
DynamicFieldsPlugin
v42 v43 1 1 [[PageOutline(2-5,Contents,pullout)]] 2 2 3 = Dynamically hide, default, copy, clear, validate, set ticket fields = 4 5 == Description == 6 7 This plugin dynamically changes fields in ticket views based on simple rules using !JavaScript / jQuery (required for this plugin). Example dynamic behavior: 8 3 = Dynamically hide, default, copy, clear, validate, set ticket fields 4 5 == Description 6 7 This plugin dynamically changes fields in ticket views based on simple rules using !JavaScript / jQuery (required for this plugin). 8 9 Key features: 9 10 * Hide a field based on another field's value 10 11 * Default a field's value per user preference … … 14 15 * Set a field's value based on another field's value 15 16 16 17 == Configuration == 18 1. Install the plugin (after downloading and unzipping): 17 == Bugs/Feature Requests == 18 19 Existing bugs and feature requests for DynamicFieldsPlugin are 20 [report:9?COMPONENT=DynamicFieldsPlugin here]. 21 22 If you have any issues, create a 23 [http://trac-hacks.org/newticket?component=DynamicFieldsPlugin&owner=robguttman new ticket]. 24 25 [[TicketQuery(component=DynamicFieldsPlugin&group=type,format=progress)]] 26 27 == Download == 28 29 Download the zipped source from [download:dynamicfieldsplugin here]. 30 31 == Source == 32 33 You can check out DynamicFieldsPlugin from [http://trac-hacks.org/svn/dynamicfieldsplugin here] using Subversion, or [source:dynamicfieldsplugin browse the source] with Trac. 34 35 Install from the [source:dynamicfieldsplugin/trunk trunk] when running Trac 1.0 and later. 36 37 == Installation 38 39 1. Install the plugin after downloading and unzipping: 19 40 {{{ 20 41 #!sh … … 24 45 }}} 25 46 26 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.47 See [http://trac.edgewall.org/wiki/TracPlugins TracPlugins] for more installation details and options. You will likely need to restart Trac's web server after installation. 27 48 28 49 2. Enable the plugin: … … 36 57 37 58 See the examples section [wiki:DynamicFieldsPlugin#Examples below] for how to specify rules. 38 39 40 == Bugs/Feature Requests == 41 42 Existing bugs and feature requests for DynamicFieldsPlugin are 43 [report:9?COMPONENT=DynamicFieldsPlugin here]. 44 45 If you have any issues, create a 46 [http://trac-hacks.org/newticket?component=DynamicFieldsPlugin&owner=robguttman new ticket]. 47 48 == Download == 49 50 Download the zipped source from [download:dynamicfieldsplugin here]. 51 52 == Source == 53 54 You can check out DynamicFieldsPlugin from [http://trac-hacks.org/svn/dynamicfieldsplugin here] using Subversion, or [source:dynamicfieldsplugin browse the source] with Trac. 55 56 Install from the [source:dynamicfieldsplugin/trunk trunk] when running Trac 1.0 and later. 57 58 == Examples == 59 60 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. 61 62 ==== Hide rule ==== 63 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'': 59 60 == Examples 61 62 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. 63 64 ==== Hide rule 65 66 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'': 64 67 {{{ 65 68 #!ini … … 82 85 }}} 83 86 84 You may also hide fields based on group membership. 87 You may also hide fields based on group membership. For example, if only members of the production team should see a custom {{{duedate}}} field: 85 88 {{{ 86 89 #!ini … … 89 92 }}} 90 93 91 Some of your fields may be auto-generated or used by very few people. 94 Some of your fields may be auto-generated or used by very few people. To always hide a field: 92 95 {{{ 93 96 #!ini … … 97 100 }}} 98 101 99 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:102 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: 100 103 {{{ 101 104 #!ini … … 105 108 }}} 106 109 107 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.108 109 110 ==== Clear rule ==== 110 The default is that hidden fields are ''not'' enabled to be shown, ie {{{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. 111 112 ==== Clear rule 113 111 114 In the version/milestone example above, if the {{{milestone}}} changes then we want the {{{version}}} field to be cleared: 112 115 {{{ … … 118 121 Note that 'clearing' a select field will actually reset it to its default value if no 'empty' option is available. 119 122 120 121 ==== Copy rule ==== 122 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. 123 ==== Copy rule 124 125 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: 123 126 {{{ 124 127 #!ini … … 134 137 }}} 135 138 136 137 ==== Default rule ==== 138 Let's say your QA team usually creates defect tickets and your product managers usually create enhancement tickets. 139 ==== Default rule 140 141 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}}}: 139 142 {{{ 140 143 #!ini … … 155 158 The above example introduces the plugin's user preference facility described below. 156 159 157 158 ==== Validate rule ==== 159 Some fields may be required (i.e., can't be empty) or must not contain some specific values.For example:160 ==== Validate rule 161 162 Some fields may be required, ie can't be empty, or must not contain some specific values. For example: 160 163 {{{ 161 164 #!ini … … 165 168 }}} 166 169 167 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.170 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. 168 171 169 172 You can also specify a condition under which the validation should be applied: … … 177 180 }}} 178 181 179 The above example is for the [wiki:CodeReviewerPlugin CodeReviewer plugin] when using its ticket reference macro to prevent a ticket moving a custom {{{phase}}} field past "codereview" if there are either pending reviews or the last changeset has not passed review. The value is a jQuery selector - if it returns one or more items then the validation is applied, else it's skipped. The {{{.1}}} and {{{.2}}} suffix for the option keys are to group the {{{invalid_if}}} and {{{invalid_when}}} parts together. 180 181 ==== Set rule ==== 182 The above example is for the [wiki:CodeReviewerPlugin CodeReviewer plugin] when using its ticket reference macro to prevent a ticket moving a custom {{{phase}}} field past "codereview" if there are either pending reviews or the last changeset has not passed review. The value is a jQuery selector - if it returns one or more items then the validation is applied, else it's skipped. The {{{.1}}} and {{{.2}}} suffix for the option keys are to group the {{{invalid_if}}} and {{{invalid_when}}} parts together. 183 184 ==== Set rule 185 182 186 When a developer starts working on a ticket, you may want to make sure she sets the milestone accordingly: 183 187 {{{ … … 213 217 An {{{(overwrite)}}} must precede a {{{(pref)}}} as shown above. 214 218 215 216 == User preferences == 217 Any rule expressed above can be configured to allow users to set preferences for them by appending ''(pref)'' to the end of the rule. 219 == User preferences 220 221 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: 218 222 {{{ 219 223 #!ini … … 222 226 }}} 223 227 224 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:228 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: 225 229 {{{ 226 230 #!ini … … 229 233 }}} 230 234 231 232 == Extensibility (implementation details) == 233 Rules are implemented as Trac extension points to allow for new rules to be added fairly easily. Six rules come packaged to provide the dynamic behaviors described above.Each rule is split between two parts:235 == Extensibility (implementation details) 236 237 Rules are implemented as Trac extension points to allow for new rules to be added fairly easily. Six rules come packaged to provide the dynamic behaviors described above. Each rule is split between two parts: 234 238 235 239 1. rule specification (Python in {{{rules.py}}}) 236 240 1. rule implementation (!JavaScript in {{{rules.js}}}) 237 241 238 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.239 240 241 == About i18n/l10n support == 242 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. 243 244 == About i18n/l10n support 245 242 246 The 0.12 branch of this plugin is prepared for localization.[[BR]] 243 247 But English message texts are still the (POSIX) default. If this isn't your preferred language, you can 244 1. look ,if it's already available from the [TracPluginTranslation Trac plugin l10n project] at [http://www.transifex.net/projects/p/Trac_Plugin-L10N/resource/dynfields Transifex] or248 1. look if it's already available from the [TracPluginTranslation Trac plugin l10n project] at [http://www.transifex.net/projects/p/Trac_Plugin-L10N/resource/dynfields Transifex] or 245 249 2. do it yourself (see the [http://trac.edgewall.org/wiki/CookBook/PluginL10N#Dotranslatorswork l10n cookbook page for Trac plugins] for more details). 246 250 247 You've done a new translation? Superb! Contributing your translation is highly appreciated.[[BR]]251 Contributing your translation is highly appreciated![[BR]] 248 252 You could send it to the plugin's maintainer or contribute to [TracPluginTranslation Trac plugin l10n project] 249 253 via [http://www.transifex.net/projects/p/Trac_Plugin-L10N/ Transifex]: … … 271 275 For more details see the [t:wiki:CookBook/PluginL10N#Compileanduseit l10n cookbook page for Trac plugins]. 272 276 273 == Recent Changes ==277 == Recent Changes 274 278 275 279 [[ChangeLog(dynamicfieldsplugin, 3)]] 276 280 277 == Author/Contributors ==281 == Author/Contributors 278 282 279 283 '''Author:''' [wiki:robguttman] [[BR]] 280 '''Maintainer:''' [ wiki:robguttman] [[BR]]284 '''Maintainer:''' [[Maintainer]] [[BR]] 281 285 '''Contributors:''' [wiki:hasienda]