Changes between Version 3 and Version 4 of FlexibleAssignToPlugin


Ignore:
Timestamp:
Oct 17, 2007, 4:16:27 PM (7 years ago)
Author:
gt4329b
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • FlexibleAssignToPlugin

    v3 v4  
    2525
    2626=== How do I install it? ===
    27 Just like any other Trac (0.11) plugin -- see step 1 in the 'How do I use it' section below for details. [[BR]]
    28 ''Note that by itself, this plugin won't make any visible changes to your Trac instance.''
     27Just like any other Trac (0.11) plugin.[[BR]]
     28Build the .egg file following the plugin packaging instructions [http://projects.edgewall.com/trac/wiki/TracDev/PluginDevelopment here].  If you already have setuptools (v0.6+) installed, your command is
     29{{{
     30python setup.py bdist_egg
     31}}}
     32Once you've built the .egg, copy it into your Trac environment's plugin directory.  You still need to activate the plugin -- in trac.ini, add this line to the components section:
     33{{{
     34[components]
     35flexibleassignto.* = enabled
     36}}}
     37
     38'''NOTE:''' the plugin ''by itself'' doesn't do anything -- you have to write your own plugin/component that implements IValidOwnerProvider (see 'Create your IValidOwnerProvider component' under 'How do I use it?' below).
    2939
    3040=== Prerequisites ===
     
    3242 * Python 2.5+ (I can't confirm that Python 2.5 is actually required -- but it's the version I developed under and the only one I've tested with.  If you successfully use this plugin with another version of Python, please update this wiki with your notes. - Morris)
    3343
    34 == How do I use it? ==
    35 '''1. Install !FlexibleAssignTo plugin''' [[BR]]
    36     To get started, install the base !FlexibleAssignTo plugin.  Build the .egg file following the plugin packaging instructions [http://projects.edgewall.com/trac/wiki/TracDev/PluginDevelopment here].  If you already have setuptools (v0.6+) installed, your command is
    37 {{{
    38 python setup.py bdist_egg
    39 }}}
    40     Once you've built the .egg, copy it into your Trac environment's plugin directory.  You still need to activate the plugin -- in trac.ini:
    41 {{{
    42 [components]
    43 flexibleassignto.* = enabled
    44 }}}
    45 
    46     '''NOTE:''' the plugin ''by itself'' doesn't do anything -- you have to write your own plugin/component that implements IValidOwnerProvider (step 3 below).
    47 
    48 '''2. Try out the demo''' [[BR]]
     44=== How do I use it? ===
     45'''1. Try out the demo''' [[BR]]
    4946    Once you've installed the base !FlexibleAssignTo plugin, copy the !SampleValidOwnerProvider.py file from the install package into your Trac environment's plugin directory (alongside the !FlexibleAssignTo .egg).  Restart your server and note the new (bogus) entries in your 'assign to' dropdowns.
    5047
    51 '''3. Create your IValidOwnerProvider component'''
    52          a. Create a .py file in your Trac environment's plugins directory -- this module is where you'll write your own class that implements the IValidOwnerProvider Extension point provided by FlexibleAssignTo.  This is where your custom logic goes for deciding what users should appear as valid 'assign to' targets for each state -- whether that logic involves querying a database, an LDAP directory, or getting input from your custom array of highly trained homing pigeons.  See the !SampleValidOwnerProvider.py module included with this plugin for a simple example on how it works. 
    53          b. IValidOwnerProvider component requirements
    54           If you want to just jump right in, then all you really need to know is the following:
    55           * The class should declare that it implements IValidOwnerProvider
    56           * The class should provide a getUsers method that takes a 'next_action_obj' as it's sole param and returns a list of instances of SimpleUser (or a subclass) representing valid owners of that next state.  If this sounds confusing, just look at the getUsers() method in !SampleValidOwnerProvider.py
     48'''2. Create your IValidOwnerProvider component'''
     49         a. Create a .py file in your Trac environment's plugins directory [[BR]]
     50          This module is where you'll write your own class that implements the IValidOwnerProvider Extension point provided by !FlexibleAssignTo.  This is where your custom logic goes for deciding what users should appear as valid 'assign to' targets for each state -- whether that logic involves querying a database, searching an LDAP directory, or getting some sort of data from your custom-built array of highly trained homing pigeons.  See the !SampleValidOwnerProvider.py module included with this plugin for a simple example on how it works. 
     51         b. Implement IValidOwnerProvider component requirements [[BR]]
     52          This module must contain a class that:
     53            * declares that it implements IValidOwnerProvider
     54            * provides a getUsers method that takes a 'next_action_obj' as it's sole param and returns a list of instances of !SimpleUser (or a subclass) representing valid owners of that next state.  Keep reading for details on the getUsers() method and the SimpleUser class.  If this sounds confusing and/or you just want to jump in and get your hands dirty, go check out the source for !SampleValidOwnerProvider.py. 
     55         c. the getUsers() method [[BR]]
     56          The sole param to getUsers(), next_action_obj, represents a workflow state that is available from the current ticket state AND that implements the "set_owner" operation (if you really want to get into the nitty gritty, next_action_obj is identical to the objects in the ConfigurableTicketWorkflow.actions list in trac/ticket/default_workflow.py).  next_action_obj is provided to getUsers for the sole purpose of providing a way to look up custom workflow state params.  For example, if you had a workflow state defined in your trac.ini like this:
     57{{{
     58mystate = oldstate -> mystate
     59mystate.name = my whoopass state
     60mystate.operations = set_owner
     61mystate.permissions = TICKET_MODIFY
     62; .valid_user_groups is a param that you add -- it's not part of the
     63;    default Trac workflow syntax
     64mystate.valid_user_groups = Development Managers, Admins
     65}}}
     66          Then in your getUsers method your code would look something like this, to retrieve these values from this workflow state:
     67{{{
     68allowed_groups = getlist(next_action_obj, 'valid_user_groups')
     69}}}
     70          You could then use the 'allowed_groups' list to query a database (or do whatever else you need to do) to get back a list of user information -- in this case, (presumably) return the users who are members of either the "Admins" or "Development Managers" group.  Each user's info should be packed into an instance of !SimpleUser (or a subclass).  The final return from getUsers() should be a *unique* list of !SimpleUser instances (no checks for uniqueness are guaranteed to be performed on the list of returned users).  Again, see SampleValidOwnerProvider.py for a hopefully straightforward example.  Note that individual workflow states can be disabled; see item 4, "Enable/disable individual workflow states", below.
     71         d. the SimpleUser class [[BR]]
     72          There are three fields in !SimpleUser that you *must* set.  Not having these set (e.g., left as their default, None) will lead to assert exceptions from !FlexibleAssignTo:
     73{{{
     74SimpleUser.username
     75SimpleUser.option_value
     76SimpleUser.option_display
     77}}}
     78          There are standard get/set methods for these; see the !SimpleUser class for specific method prototypes.  '''NOTE:''' the format of username values *must* match the format of usernames for logged-in users -- if John Doe logs in with the username "jdoe", then a !SimpleUser instance representing John Doe should get its username attribute set to "jdoe".  If you don't do this, !FlexibleAssignTo will not work correctly.
    5779
    5880