Link copied!

Rule Builder API

This component of the Design System is deprecated, which means it'll be replaced or removed soon. Until that, the Design System team will support existing implementations, but please avoid implementing this component in new projects.
This component is written in TypeScript.
This component features render debouncing. You may have to wait for the next browser tick after rendering in your integration/E2E tests.
This component uses content cloning for rendering which could cause issues when using frontend frameworks.
Check the Component cloning section of the Usage with Frameworks guide for details.

API Reference e-rule-builder

HTML Attributes API

Name Description Type Required Default value
items Set items for the main group of the rule builder object * {}
excluded-items Set items for the main excluded group of the rule builder object * {}
readonly Set readonly state boolean false
disabled Set disabled state boolean false
auto-label Allow automatic labeling of groups boolean false
max-depth Define the depth main and excluded groups can reach number 3
max-rule-count Define the maximum number of rules can be used in the component number Infinity
exclude-enabled Allow the usage of the excluded group boolean false
group-header-label-hidden Allow to hide group labels boolean false
group-header-toggle-hidden Allow to hide group collapse icon boolean false
group-header-relation-label Define the label of the relation selector string
emptyStateHandler Callback function to provide custom empty state texts function *
add-rule-button-text Define the text of the add rule button string
add-rule-button-tooltip Define the text of the add rule button tooltip string
rule-editor-add-title Define the title of the rule editor in add state string
rule-editor-edit-title Define the title of the rule editor in edit state string

*: An example of an items or excluded-items property value: 

{
    label: 'Test Group 1',
    relation: 'and',
    items: [
        { label: 'Test Rule 1', blueprint: { name: 'test-blueprint-1' } },
        { label: 'Test Group 2', relation: 'or', items: [
            { label: 'Test Rule 2', blueprint: { name: 'test-blueprint-2' } },
            { label: 'Test Rule 3', blueprint: { name: 'test-blueprint-3' } },
        ] }
    ]
}

*: An example of an empty-state-handler function: 

const emptyStateHandler = ({
        isMaxDepthReached
      }: {
        isMaxDepthReached: boolean;
      }): { title: string; text: string } => {
        const case = isMaxDepthReached ? 'withoutSubGroup' : 'withSubGroup';
        const dictionary = {
          withoutSubGroup: {
            title: 'No Example Rule to show',
            text: 'Add an Example Rule to continue'
          },
          withSubGroup: {
            title: 'No Example Rule to show',
            text: 'Add an Example Rule or Example Subgroup to continue'
          }
        }
        return dictionary[case];
  };

JavaScript API

Name Type Description Arguments
value Sets the main items and excluded items at the same time object *

*: An example of value property value: 

{
    items : {
        label: 'Test Group 1' , relation: 'and', items : [
            { label: 'Test Rule 1', blueprint: { name: 'test-blueprint-1' } },
            { label: 'Test Group 2', relation: 'or', items: [
                { label: 'Test Rule 2', blueprint: { name: 'test-blueprint-2' } },
                { label: 'Test Rule 3', blueprint: { name: 'test-blueprint-3' } },
            ] }
        ]
    },
    excludedItems: {
        label: 'Test Group 1' , relation: 'and', items : [
            { label: 'Test Rule 1', blueprint: { name: 'test-blueprint-1' } },
            { label: 'Test Group 2', relation: 'or', items: [
                { label: 'Test Rule 2', blueprint: { name: 'test-blueprint-2' } },
                { label: 'Test Rule 3', blueprint: { name: 'test-blueprint-3' } },
            ] }
        ]
    }
}

Events

Event Description Returns
rule.open Fires when a rule is opened (i.e. created or edited). 
{
    detail: {
        rule: {
            blueprint: {
                name: 'blueprintA'
            },
            fields: {
                inputKeyA: 'value1',
                inputKeyB: 'value2'
            }
        }
}
rule.close Fires when a rule is closed (i.e. saved or an edit is cancelled).
rule.change Fires when a rule is saved.
group.open Fires when a group is opened. 
{
    detail: {
            group: {
                label: 'Test Group 1',
                    relation: 'and',
                    items : [
                        { label: 'Test Rule 1', blueprint: { name: 'test-blueprint-1' } },
                        { label: 'Test Group 2', relation: 'or', items: [
                            { label: 'Test Rule 2', blueprint: { name: 'test-blueprint-2' } },
                            { label: 'Test Rule 3', blueprint: { name: 'test-blueprint-3' } },
                        ] }
                    ]
            }
    }
}
group.close Fires when a group is closed.
group.change Fires when a group or a group item is changed.
change Fires when any rule or group is changed in the rule builder. 
{
    detail: {
        value: {
            items : {
                label: 'Test Group 1' , relation: 'and', items : [
                    { label: 'Test Rule 1', blueprint: { name: 'test-blueprint-1' } },
                    { label: 'Test Group 2', relation: 'or', items: [
                        { label: 'Test Rule 2', blueprint: { name: 'test-blueprint-2' } },
                        { label: 'Test Rule 3', blueprint: { name: 'test-blueprint-3' } },
                    ] }
                ]
            },
            excludedItems: {
                label: 'Test Group 1' , relation: 'and', items : [
                    { label: 'Test Rule 1', blueprint: { name: 'test-blueprint-1' } },
                    { label: 'Test Group 2', relation: 'or', items: [
                        { label: 'Test Rule 2', blueprint: { name: 'test-blueprint-2' } },
                        { label: 'Test Rule 3', blueprint: { name: 'test-blueprint-3' } },
                    ] }
                ]
            }
        }
    }
}

API Reference e-validation

Custom component with name and validation properties, that could be connect through the name for custom validation.

Name Type Description Arguments Return
name Defines the name, that help to match for validation
validation Run custom validation function for the current blueprint (validation run on item setter/rule creation/rule edit) Rule boolean

API Reference e-rule-blueprint

The e-rule-blueprint element defines a blueprint based on which it is possible to add new rules to the rule builder. The e-rule-blueprint element can contain an e-rule-blueprint-template, an e-rule-blueprint-summary and multiple e-rule-blueprint-action elements but these are optional.

If the e-rule-blueprint-template is missing the blueprint will generate empty rules.

HTML Attributes API

Name Description Type Required Default value
name Internal id of the blueprint string true
label The label for the blueprint that is shown to the users string true
validation Defines the connecting e-validation name string optional

API Reference e-rule-blueprint-template

The HTML markup inside the e-rule-blueprint-template element is rendered whenever a rule is created based on the blueprint or when such a rule is edited. HTML inputs inside the template that have a data-field="field-name" attribute will be used as values for the rule. The value of the data-field attribute is used to identify the given value.

API Reference e-rule-blueprint-summary

The HTML markup inside the e-rule-blueprint-summary element is rendered when a rule is closed. It is possible to add placeholders to this markup with the e-rule-blueprint-summary-value element.

API Reference e-rule-blueprint-summary-value

  • Use the <e-rule-blueprint-summary-value type="field" field="field-name"> element in the summary to render a value that is saved for the rule.
    • You can use the property attribute to choose what property of the referenced field will get rendered in the summary.
    • You can use the formatter attribute to choose what formatter function would be used on the value.
  • Use the <e-rule-blueprint-summary-value type="blueprint"> element to display the human-readable label (name) of the rule.
  • Use the <e-rule-blueprint-summary-value type="index"> to display the index of the rule. The indexing of the rules within a subgroup will start from 1 as well.

See the Rule Builder With Custom Summary example for usage.

HTML Attributes API

Name Description Type Required Default value
type Type of the placeholder string true
field Defines the name of the field to use (type="field" only) string true
property Name of the property of the field of blueprint to display string value for type="field"
label for type="blueprint"

API Reference e-rule-blueprint-action

This renders a new button for the closed rule. The rendered button is a basic HTML element to which it is possible to bind any custom event handler.

HTML Attributes API

Name Description Type Required Default value
id Defines unique id for action string true
tooltip Defines hover tooltip text string
icon Defines the button icon string
disabled Controls the disabled state of the button boolean false

API Reference e-rule-relation

Adds a custom relation to the available relations for groups. Adding any e-rule-relation elements to a rule-builder will disable the default relations ("Match all (AND)", "Match any (OR)").

HTML Attributes API

Name Description Type Required Default value
description Defines the description that is showed in the relationship selector of the groups string true
value Defines the unique value that is stored for the group string true
icon Defines the icon that is shown on the group when the relation is selected string
label The label that is visible inside a group in front of rows and subgroups string