You can develop custom rule conditions. Developing these requires adept programming skills.

How to develop custom rule conditions

You develop a rule condition type and set up a list of conditions of that type. It is similar to the example conditions you see in the rule editor. These serve no actual purpose, but illustrate how it is done.

Open

You add a PHP class in the folder for custom rule conditions. The folder is in the customization directory in

/rule_condition_types/

You pick a name for your condition type (like ‘Example’). The PHP class needs to be called CustomCondition followed by your type name. So for type ‘Example’ you got CustomConditionExample. The file name is called the same (CustomConditionExample.php). The class extends ConfigboxCondition. So you got class CustomConditionExample extends ConfigboxCondition.

There are a few methods that need to be implemented.

• CustomConditionExample::getConditionsPanelHtml()

• CustomConditionExample::getConditionHtml($conditionData, $forEditing = true)

• CustomConditionExample::getEvaluationResult($conditionData, $selections)

getConditionsPanelHtml()

Each type gets a panel in the rule editor. This method returns the HTML to use for it. It contains a list of conditions (the HTML of each condition has a certain structure, you will see more about that in the method getConditionHtml().

getConditionHtml($conditionData, $forEditing = true)

This method takes the Condition Data as parameter and returns the HTML for the condition. Depending on $forEditing, it returns HTML suitable for the editor or just visual HTML for the form’s property. You see an example of the HTML in Example’s PHP class, method CustomConditionExample::readMe(). The HTML structure is essentially this:

• A wrapping <span> with the CSS classes item and condition

• Condition data in form of data attributes in that <span> (attribute data-type is required, rest is up to implementation of the condition type)

• Optionally <input> elements that add to the Condition Data. They must have the CSS class ‘input' and a data attribute ‘data-data-key’ that holds the Condition Data Item’s key and an attribute ‘value’ that holds the value (and facilitates user input in the rule editor)

• You add any HTML as you see fit to make the condition practical for the administrator

Example:

See notes about data-operator later.

Note: The .condition-operator <span> is special - the rule editor JS takes care of displaying the choices on click and storing the choice in the .condition’s data attribute ‘data-operator’. Making use of the operator is optional.

The example uses … for simplicity. Use the $conditionData array which contains key/value pairs of all condition data.

How does all that play out? When the admin saves the rule, the system will scan through the conditions that it finds in the rule area, processes the data attributes in the <span>, processes the .input text fields within and and creates so called ‘Condition Data’. Together with the data of combinators (OR, AND) and the parentheses, it creates ‘Rule Data’ - essentially a JS array of objects that eventually will be saved as a JSON string.

See CustomConditionExample::readMe() for a line-by-line explanation of the HTML structure.

getEvaluationResult($conditionData, $selections)

This method is called when the condition is evaluated as part of the whole rule. $conditionData contains everything that was set as Condition Data in the previous method. $selections holds a standardised array with the current configuration that is tested.

The method has to return true or false. Developers need to take great care about performance of this method. Cache/Memoize where you can since this method may be called multiple times each time a customer makes a selection in the configurator.

See CustomConditionExample::readMe() for the concrete structure of both parameters.

What is Condition Data

Condition data is an array that has all the data to evaluate the condition during the configuration (via getEvaluationResult()). In the rule editor each value is written as HTML 5 data attribute in the conditions HTML (in getConditionHtml()).

Condition data in the Example type:

You can make as many condition data items in your condition type as you see fit. The data will be available to you in the method getEvaluationResult().