toolrules

The Tool Rules bundle provides a way to set tool properties based on rules. To make tools context sensitive, arbitrary information can be used for rule evaluation.

With the types provided by this bundle rules can be used to ...

... control tool visibility and other tool's properties.
... control active state of grouped tools.

The actual rules are implemented by tool rules processors. Some common tool rule processors are delivered with this bundle. They allow to control a tool's properties depending on ...

... the user's membership of a certain role.
... the presence of a certain store.
... the current state of the map (scale and visibility of layers).

Usage

To make a tool visible only if the logged in user is member of the role maAdmin or maEditor, configure this bundle as demonstrated in the following app.json file excerpt:

"toolrules": {
    "ToolRuleManager": {
        "_rules" : {
            "<toolId>": {
                "ruleSuccessProperty": "visibility",
                //set visible only if user has role maAdmin or maEditor
                "roles": ["maAdmin","maEditor"]
            }
        }
    }
}

See Defining rules to control a tool's properties for details.

Use Cases

Defining rules to control a tool's properties

Rules for tools are defined on the ToolRuleManager component.

ToolRuleManager

The _rules property assigns tool IDs to rule objects:

"toolrules": {
    "ToolRuleManager": {
        "_rules" : {
            "<toolId>": <rule_object>,
        }
    }
}

If a tool rule is evaluated, the tool with the corresponding <toolId> is updated as specified by the <rule_object>.

Rule Objects

The <rule_object> defines condition and effect of a rule evaluation for a tool.

{
    "ruleSuccessProperty": "<tool_property>",   //optional
    "<rule_type>": <rule_condition_match>,
    "<rule_type>": <rule_condition_match>
}

Property `ruleSuccessProperty`

The property of a tool to be set to true or false according to the rule evaluation result.

Accepted <tool_property> values are:

enabled (default)
visibility
active

Property `<rule_type>`

The type of the rule.

All tool rule processors registered for a rule type are called to evaluate the rule. The tool rule processors available in this bundle are described in the following.

The content of <rule_condition_match> depends on the actual rule type. This can be a simple value, an array, or an object.

If multiple different <rule_type> properties are defined, the rule evaluates to true only if all rule types evaluate to true.

Rule Types

This section describes the rules that are evaluated by tool rule processors provided by this bundle. Other bundles might provide additional rule types and according processors.

`roles`

Rules of type roles evaluate to true, if the user is member of a certain role.

In the following sample, the tool with ID <toolId> is activated if the user is in role maAdmin or maEditor. This feature requires the authentication bundle to be initiated at the allowedBundles section inside the app.json file.

"_rules": {
  "<toolId>": {
    "roles": ["maAdmin","maEditor"]
  }
}

`<useIn_property>StoreAvailable`

Tool rules can also check if stores for selection and/or omnisearch are available.

"_rules": {
  "<toolId>": {
    "omnisearchStoreAvailable": true,
    "selectionStoreAvailable": true
  }
}

Other available tool rules

The following table presents tool rules provided by other bundles. For detailed usage information, see the according bundle documentation.

Tool rule name	Description	Bundle
`viewmode`	Rule depending on the current viewmode (2D/3D).	map-widget
`layerVisible`	Rule depending on visibility of layers.	map-widget
`minScale` / `maxScale`	Rule depending on the current scale of the map.	map-widget
`subLayoutNames`	Rule depending on the current sub-layout (for example 'tablet_landscape'). Use this rule inside an `app.json` file, as the rule is layout-template dependent.	templatelayout
`layoutBreakPointNames`	Rule depending on the current layout-breakpoint name. Use this rule when defining a tool rule inside a bundle's `manifest.json` file to be layout-template independent.	templatelayout

Combining rules with `and`, `or`, `not`

To combine rules, use the logical operators and, or, not:

"_rules": {
  "<toolId>": {
    "or": [{
        "not": {
          "roles": ["maEditor"]
        }
      },
      {
        "selectionStoreAvailable": true
      }]
    }
  }
}

Grouping tools for mutual activation

All tools belonging to the same tool group are mutually activated and deactivated (there can only be one active tool in each group). To deactivate a tool when another tool is activated (for example, to activate only one sketching tool at a time), assign both tools to the same group. To allow the activation of two tools at the same time, assign them to different groups.

To assign a tool to a tool group add the groups property to the tool configuration. The names of the tool's groups are specified in an array:

"measurement-2d": {
  "MeasurementTool": {
   "groups": ["nameOfTheGroup", "nameOfTheSecondGroup"]
  }
}

To assign a tool to only one group, set the group as a string:

"measurement-2d": {
  "MeasurementTool": {
   "groups": "nameOfTheGroup"
  }
}

If no group is specified for a tool, it is added to the group default.

ToolActiveStateManager

Code sample for app.json file:

"toolrules": {
  "ToolActiveStateManager" : {
    "activateOnStartToolIds" : ["toolId1"]
  }
}

Property Overview

Property	Type	Mandatory
defaultActiveToolIds	Object	no
activateOnStartToolIds	String`[]`	no
activateOnRegistrationToolIds	String`[]`	no

Property Details

`defaultActiveToolIds`

Defines the default active tool for each tool group. The value of this property is an object where the keys are the names of the tool groups. The values of this object are the IDs of the tools, that are activated by default.

The default tool group has the name "default".

"defaultActiveToolIds": {
    "<groupname>": "<toolId>"
    "default": "<toolId>"
}

`activateOnStartToolIds`

An array of tool IDs specifying the tools that are activated when the application is started. List of tools directly activated on start.

Example:

"activateOnStartToolIds": ["toolId1"]

`activateOnRegistrationToolIds`

An array of tool IDs specifying the tools that are activated whenever the tools are registered at the ToolActiveStateManager. This is different to the property activateOnStartToolIds because it activates a tool on every bundle activation and not only on the first bundle activation.

Example:

"activateOnRegistrationToolIds": ["toolId1"]

Defining rules directly on tools

Rules for tools can as well be defined using the rules property of a tool.

Code Sample for app.json file:

"coordinateconversion":{
    "CoordinateConversionToggleTool":{
        "activateOnStartup" : true,
        "activateOnRegistration" : true,
        "rules" :{
            "roles": ["my_custom_role"],
            "ruleSuccessProperty": "visibility"
        }
    }
}

Overwriting existing tool rules

The rules of many tools are already defined in the corresponding bundles. Rules defined directly in the tool configuration and rules defined in the ToolruleManager._rules property are merged, and all rules are evaluated. To override any existing rule with a configuration in the ToolruleManager._rules property, enabled the property managerRulesSupersedes like in the following sample:

"_rules": {
    "<toolId>": {
        "managerRulesSupersedes" : true,
        "roles": ["my_custom_role"]
    }
}

Implementing a tool rule processor

To implement a custom tool rule processor, create a new OSGi component in the manifest.json file of your bundle that provides the toolrules.ToolRuleProcessor interface.

{
  "name" : "MyToolRuleProcessor",
  "provides": ["toolrules.ToolRuleProcessor"]
}

The implementing class for our component must

provide an array ruleProperties containing the names of all rule types evaluated by the processor
and implement the isRuleFulfilled method.

Example:

export default class MyToolRuleProcessor {
    ruleProperties = ["myRuleProperty"];
    isRuleFulfilled(tool: any, ctx: any, rules: any): (undefined | boolean)[] | boolean | undefined {
        // ...
    }
}

`isRuleFulfilled`

This method gets called by the ToolRuleManager. It gets the following three parameters:

<tool> - The instance of the tool whose tool rule is being evaluated.
<context> - The tool rule context as provided by tool.ToolRuleContext. The tool rule context is an object that inherits from ct/Stateful and that can store attribute values and emit events when an attribute value is changed. You can use it to store environment property values that the rules are evaluated against.
<toolRuleDef> - The tool rule to evaluate.

The method may return different types of values:

<[]> - empty array. This means that there is no property or rule type respectively defined on the rule to evaluate by this processor.
<boolean[]> - The rule is fulfilled when all entries in the array are true. Otherwise, the rule is not fulfilled.
<boolean> - The rule is fulfilled when the returned value is true, and it is not fulfilled when the returned value is false.
undefined - The method should return undefined when no decision can be made whether the rule matches or not.

Example

Here is the tool rule that we want to evaluate:

{
  "myRuleProperty": "certainValue"
}

Our custom tool rule processor can implement the method isRuleFulfilled as shown below:

export default class MyToolRuleProcessor {
    ruleProperties = ["myRuleProperty"];
    isRuleFulfilled(tool: any, context: any, rule: any): (undefined | boolean)[] {
        const ruleValue = rule.myRuleProperty;
        if (ruleValue === undefined) {
            return [];
        }
        const statevalue = context.get("foo");
        if (statevalue === undefined) {
            return [undefined];
        }
        return [ruleValue === statevalue];
    }
}

The isRuleFulfilled method is called by the ToolRuleManager and the rule is passed as the third parameter. In line 2 we check whether the property we are interested in is defined in the rule. If there is no value defined for that property our tool rule processor is not responsible for that tool rule, so an empty array is returned. That means the rule is not considered in the evaluation performed by the ToolRuleManager. The ToolRuleManager has to make the decision, whether this tool rule is fulfilled or not using the next tool rule processors, if present.

In line 7 we check if there is a value defined in the tool rule context for the property to evaluate. If there is no value in the tool rule context for that property we cannot make a decision. So we return an array with one undefined entry.

Finally, if our tool rule processor is responsible for the rule and there is a value defined in the tool rule context we can evaluate the rule. The result, true or false, is returned inside an array in line 10.

toolrules

Usage

Use Cases

Defining rules to control a tool's properties

ToolRuleManager

Rule Objects

Property ruleSuccessProperty

Property <rule_type>

Rule Types

roles

<useIn_property>StoreAvailable

Other available tool rules

Combining rules with and, or, not

Grouping tools for mutual activation

ToolActiveStateManager

Property Overview

Property Details

defaultActiveToolIds

activateOnStartToolIds

activateOnRegistrationToolIds

Defining rules directly on tools

Overwriting existing tool rules

Implementing a tool rule processor

isRuleFulfilled

Example

Property `ruleSuccessProperty`

Property `<rule_type>`

`roles`

`<useIn_property>StoreAvailable`

Combining rules with `and`, `or`, `not`

`defaultActiveToolIds`

`activateOnStartToolIds`

`activateOnRegistrationToolIds`

`isRuleFulfilled`