Changes between Version 3 and Version 4 of KeepInterfaceSimplePlugin

Timestamp:

Nov 24, 2016, 7:29:01 PM (7 years ago)

Author:

Jon Ashley

Comment:

Begin to document upcoming changes for version 2.0 of this plugin

KeepInterfaceSimplePlugin

@@ -5 +5 @@
 == Description
 
-This plugin supports complex workflows that contain lots of fields or have lots of rules about what is and isn't permitted. It can dynamically control what fields appear in the user interface depending on complex conditions that are nonetheless easy to define and configure. It can also block commits if necessary, such as when certain information hasn't been provided.
+This plugin helps manage configurations that contain lots of fields or have lots of rules about what is and isn't permitted. It can dynamically control what fields appear in the user interface depending on easily-configurable conditions. It can also block commits if necessary, such as when certain information hasn't been provided.
 
-There are two main components, named 'assistant' and 'warden'.
+There are two main components, named 'assistant' and 'warden'. The Assistant manages the user-interface side, hiding and showing fields and options, and filling in fields for the user. The Warden enforces the rules that prevent commits.
 
-The Assistant uses expressions to define what fields are presented to the user in different circumstances. For example, take the rules:
+=== Hiding a field
+
+The Assistant uses simple C-like expressions to define what fields are presented to the user in different circumstances. For example, let's assume that the tickets contain a fields named 'approval', that should be hidden if the ticket is in the 'new' or 'closed' state. Write a `kis_assistant` rule for `approval.visible`:
+{{{#!ini
+[kis_assistant]
+approval.visible = !(status == 'new' || status == 'closed')
+}}}
+The expression syntax is similar to that of C or Javascript. An acceptable alternative would be:
+{{{#!ini
+[kis_assistant]
+approval.visible = status != 'new' && status != 'closed'
+}}}
+Because lists of states are quite common however, the Assistant also provides an `in` operator, with very high precedence. So another acceptable alternative would be:
 {{{#!ini
 [kis_assistant]
 approval.visible = !status in 'new', 'closed'
-approval.options.basic_set = Not assessed, Denied
-approval.available.basic_set = true
-approval.options.full_set = Approved
-approval.available.full_set = authname has_role 'approver' || _approval == 'Approved'
 }}}
 
-This requires that a custom field named 'approval' is defined (either a Select or a Radio field) with options 'Not assessed', 'Denied' and 'Approved'. The first rule states that the field only appears when the ticket status is other than 'new' or 'closed'. The basic set of options 'Not assessed' or 'Denied' are always available, but the full set of options including 'Approved' is only available if the user is a member of the 'approver' group or if the field already had the value 'Approved' when the page was loaded.
+In expressions, 'authname' evaluates to the authenticated name of the user, and 'status' evaluates to the current ticket status.
+
+=== Hiding options
+
+Let's assume that we have a set of people on our project with the role of 'approver' (i.e. they are members of the Trac permissions group 'approver'). Let's also assume that the 'approval' field mentioned above is a Select or Radio field that has options 'Not assessed', 'Denied' and 'Approved'. The basic set of options 'Not assessed' or 'Denied' are available to all, but the full set of options including 'Approved' is only available if the user is a member of the 'approver' group or if the field already had the value 'Approved' when the page was loaded.
+{{{#!ini
+approval.options.basic_set = 'Not assessed', 'Denied'
+approval.available.basic_set = true
+approval.options.full_set = 'Approved'
+approval.available.full_set = has_role('approver') || _approval == 'Approved'
+}}}
+The condition for the basic set of options being available is therefore just 'true'. The full set of options is available if the function 'has_role' returned 'true' when called with the parameter 'approver', or if the value of 'approval' when the page was loaded was already set to 'Approved'. The underscore in front of 'approval' means "use the value of this field at the time the page was loaded".
+
+=== Using templates
+
+TBD
+
+=== Updating the contents of fields automatically
+
+TBD
+
+=== Blocking commits
 
 The Warden prevents commits from being made if certain conditions aren't met. For example, take the rules:
@@ -25 +54 @@
 [kis_warden]
 approval required to close = status == 'closed' && approval != 'Approved'
-only designated approver can approve = !authname has_role 'approver' && approval != _approval && approval == 'Approved'
+only designated approver can approve = !has_role('approver') && approval != _approval && approval == 'Approved'
 }}}
 
-The first rule means that the ticket cannot be closed if the 'approval' field has not been set to the value 'Approved'. The second rule means that only a user who is a member of the group 'approver' can change the 'approval' field to that value.
+The commit is blocked if any rule evaluates true. Therefore, the first rule means that the ticket cannot be closed if the 'approval' field has not been set to the value 'Approved'. The second rule means that only a user who is a member of the permissions group 'approver' can change the 'approval' field to that value.
+
+== Functions
+
+The 'has_role(<group>)' function is built-in, and returns true if and only if the user is a member of the named group. (A second parameter can be given, and allows a different user to be named, but this isn't normally needed.)
+
+Another built-in function is 'is_parent()', which returns true if and only if some other ticket has a field named 'parent' which contains a TracLink that points at the current ticket. It's designed to work with the TracChildTickets plugin.
+
+=== User-defined functions
+
+User functions can be defined by adding a Python file to the Trac plugins folder that implements the `IConfigFunction` interface. For example:
+{{{
+from trac.core import *
+from kis import IConfigFunction
+
+class MyConfigFunctions(Component):
+    ''' Local functions for use by 'kisplugin' configuration files.
+    '''
+    implements(IConfigFunction)
+
+    # Example: implement named string constants
+    def safety(self, req, safety_enum):
+        if safety_enum == 'YES':
+            return 'Safety related'
+        if safety_enum == 'OK':
+            return 'Safety related - OK to close'
+        if safety_enum == 'NO':
+            return 'Not safety related'
+}}}
+This example would define a function 'safety()', implementing named constants. 'safety('OK')' returns the string 'Safety related - OK to close'.
+The 'req' parameter is the HTTP request object; the remaining parameters are the parameters of the function call passed in from the configuration file.
+
+== What's new in version 2
+
+* Function calls and user-defined functions.
+* Automatic updating of fields.
+* The operator 'has_role' has been retired and replaced with the 'has_role()' function.
+* Labels and templates now have to be string expressions (in other words, they now need to be surrounded by single-quotes).
+* New operators: arithmetic and comparison operators, and the ternary operator <expression> '?' <true_expression> ':' <false_expression>
+* Changes to operator precedence: now very similar to that of Javascript.
 
 == !Bugs/Feature Requests