Changes between Version 42 and Version 43 of DynamicFieldsPlugin


Ignore:
Timestamp:
Mar 17, 2015, 10:31:41 AM (9 years ago)
Author:
figaro
Comment:

Cosmetic changes

Legend:

Unmodified
Added
Removed
Modified
  • DynamicFieldsPlugin

    v42 v43  
    11[[PageOutline(2-5,Contents,pullout)]]
    22
    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
     7This plugin dynamically changes fields in ticket views based on simple rules using !JavaScript / jQuery (required for this plugin).
     8
     9Key features:
    910 * Hide a field based on another field's value
    1011 * Default a field's value per user preference
     
    1415 * Set a field's value based on another field's value
    1516
    16 
    17 == Configuration ==
    18  1. Install the plugin (after downloading and unzipping):
     17== Bugs/Feature Requests ==
     18
     19Existing bugs and feature requests for DynamicFieldsPlugin are
     20[report:9?COMPONENT=DynamicFieldsPlugin here].
     21
     22If 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
     29Download the zipped source from [download:dynamicfieldsplugin here].
     30
     31== Source ==
     32
     33You can check out DynamicFieldsPlugin from [http://trac-hacks.org/svn/dynamicfieldsplugin here] using Subversion, or [source:dynamicfieldsplugin browse the source] with Trac.
     34
     35Install 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:
    1940    {{{
    2041    #!sh
     
    2445    }}}
    2546
    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.
    2748
    2849 2. Enable the plugin:
     
    3657
    3758See 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
     62This 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
     66Let'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'':
    6467{{{
    6568#!ini
     
    8285}}}
    8386
    84 You may also hide fields based on group membership.  For example, if only members of the production team should see a custom {{{duedate}}} field:
     87You may also hide fields based on group membership. For example, if only members of the production team should see a custom {{{duedate}}} field:
    8588{{{
    8689#!ini
     
    8992}}}
    9093
    91 Some of your fields may be auto-generated or used by very few people.  To always hide a field:
     94Some of your fields may be auto-generated or used by very few people. To always hide a field:
    9295{{{
    9396#!ini
     
    97100}}}
    98101
    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:
     102Fields 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:
    100103{{{
    101104#!ini
     
    105108}}}
    106109
    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 ====
     110The 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
    111114In the version/milestone example above, if the {{{milestone}}} changes then we want the {{{version}}} field to be cleared:
    112115{{{
     
    118121Note that 'clearing' a select field will actually reset it to its default value if no 'empty' option is available.
    119122
    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.  Initially the {{{captain}}} should be set to the {{{owner}}}, so to reduce data entry in making this so:
     123==== Copy rule
     124
     125Let'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:
    123126{{{
    124127#!ini
     
    134137}}}
    135138
    136 
    137 ==== Default rule ====
    138 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==== Default rule
     140
     141Let'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}}}:
    139142{{{
    140143#!ini
     
    155158The above example introduces the plugin's user preference facility described below.
    156159
    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
     162Some fields may be required, ie can't be empty, or must not contain some specific values. For example:
    160163{{{
    161164#!ini
     
    165168}}}
    166169
    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.
     170The 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.
    168171
    169172You can also specify a condition under which the validation should be applied:
     
    177180}}}
    178181
    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 ====
     182The 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
    182186When a developer starts working on a ticket, you may want to make sure she sets the milestone accordingly:
    183187{{{
     
    213217An {{{(overwrite)}}} must precede a {{{(pref)}}} as shown above.
    214218
    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.  For example, here's one of the hide rules from above:
     219== User preferences
     220
     221Any 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:
    218222{{{
    219223#!ini
     
    222226}}}
    223227
    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:
     228The ''(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:
    225229{{{
    226230#!ini
     
    229233}}}
    230234
    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
     237Rules 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:
    234238
    235239 1. rule specification (Python in {{{rules.py}}})
    236240 1. rule implementation (!JavaScript in {{{rules.js}}})
    237241
    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 ==
     242The 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
    242246The 0.12 branch of this plugin is prepared for localization.[[BR]]
    243247But 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] or
     248 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
    245249 2. do it yourself (see the [http://trac.edgewall.org/wiki/CookBook/PluginL10N#Dotranslatorswork l10n cookbook page for Trac plugins] for more details).
    246250
    247 You've done a new translation? Superb! Contributing your translation is highly appreciated.[[BR]]
     251Contributing your translation is highly appreciated![[BR]]
    248252You could send it to the plugin's maintainer or contribute to [TracPluginTranslation Trac plugin l10n project]
    249253via [http://www.transifex.net/projects/p/Trac_Plugin-L10N/ Transifex]:
     
    271275For more details see the [t:wiki:CookBook/PluginL10N#Compileanduseit l10n cookbook page for Trac plugins].
    272276
    273 == Recent Changes ==
     277== Recent Changes
    274278
    275279[[ChangeLog(dynamicfieldsplugin, 3)]]
    276280
    277 == Author/Contributors ==
     281== Author/Contributors
    278282
    279283'''Author:''' [wiki:robguttman] [[BR]]
    280 '''Maintainer:''' [wiki:robguttman] [[BR]]
     284'''Maintainer:''' [[Maintainer]] [[BR]]
    281285'''Contributors:''' [wiki:hasienda]