Important

You are browsing the documentation for version 4.2 of OroCommerce, OroCRM and OroPlatform, which is no longer maintained. Read version 5.1 (the latest LTS version) of the Oro documentation to get up-to-date information.

See our Release Process documentation for more information on the currently supported and upcoming releases.

Condition Builder Component

This topic describes the ConditionBuilderView UI component, its usage examples, and configuration options.

Responsibility

ConditionBuilderView is responsible for rendering UI control which allows building a structure with nested conditions such as:

[
    { /* ... */ },
    "AND",
    [
        { /* ... */ },
        "OR",
        { /* ... */ }
    ]
]

Where:

• array is a Conditions Group;

• object is a Condition Item;

• string is an Operator.

Usage Example

ConditionBuilderView requires a certain predefined HTML structure:

<div class="condition-builder">
    <ul class="criteria-list">
        <li class="option" data-criteria="condition-item"
            data-module="somebundle/js/app/views/some-condition-view"
            data-options="{}">
            Condition Item
        </li>
        <li class="option" data-criteria="conditions-group">
            Conditions Group
        </li>
    </ul>
    <div class="condition-container"></div>
</div>

The example above contains a list of available condition criteria and a container for the building process. Each criterion of the list should have a data criteria attribute which allows to distinguish them.

There are two preset kinds of conditions:

• conditions-group, new sub-group (ConditionBuilderView already has a root group by itself);

• condition-item, another condition (useful if there are no other conditions).

Condition Item criteria element should have two data attributes to ConditionBuilderView could initialize a ConditionView, which is responsible for that condition-item. Attributes are:

• data-module — name of AMD module which contains a ConditionView definition;

• data-options — JSON-string with options for a ConditionView.

Condition Item with Custom Criteria

To define custom criteria, set the data-criteria attribute with your own criterion name. For example:

<div class="condition-builder">
    <ul class="criteria-list" id="criteria-list">
        <li class="option" data-criteria="matrix-condition"
            data-module="somebundle/js/app/views/matrix-condition-view"
            data-options="{}">
            Matrix Condition
        </li>
        <li class="option" data-criteria="condition-item"
            data-module="somebundle/js/app/views/some-condition-view"
            data-options="{}">
            Condition Item
        </li>
        <li class="option" data-criteria="conditions-group">
            Conditions Group
        </li>
    </ul>
</div>

The condition’s value object will be extended with extra property criteria:

[
    {/* ... */, "criteria": "matrix-condition"},
    "AND",
    [
        {/* ... */}, // usual condition-item
        "OR",
        {/* ... */, "criteria": "matrix-condition"}
    ]
]

Options for ConditionBuilderView

• value — initial value, an array of conditions

• sortable — common options for both sortable containers conditions group and criteria list, see options for jQuery-UI sortable;

• conditionsGroup — specific options for the sortable widget of conditions group;

• criteriaList — specific options for the sortable widget of criteria list;

• operations — an array with allowed operations (default [‘AND’, ‘OR’]);

• criteriaListSelector — jQuery selector for criterion criteria list (default ‘.criteria-list’);

• conditionContainerSelector — jQuery selector for criterion condition container (default ‘.condition-container’);

• helperClass — CSS class for a grabbing element (default ‘ui-grabbing’);

• validation — an object with validation rules. Where a key — criteria name, value — is an object with validation rules. See validation in OroFormBundle.

Methods

ConditionBuilderView has two public methods:

• getValue() — returns the current value (an array of conditions)

• setValue(value) — sets a new value (the existing structure will be removed and the new one will be restored from the value)

Example:

var conditionBuilderView = new ConditionBuilderView({
    autoRender: true,
    value: [{/*...*/, 'OR', /*...*/}]
});

conditionBuilderView.getValue(); // returns current value

conditionBuilderView.setValue([ // allows to change value
    [{/* ... */}, 'AND', {/* ... */}],
    'OR',
    {/* ... */}
]);