About Expression Builder#

The variants scale from lightweight e-commerce style filtering to declarative rule building, and even to advanced formula or SOQL/SQL expressions.

We also include size variants to fit a variety of use cases:

• Use the narrow version for in-context expression building, enabling users to preview their results.
• Use the full width version when expression building is a standalone task, perhaps in a modal.

Accessibility#

Markup#

Each row in the expression builder is a <fieldset> and is contained in an <li> inside of a <ul>.

<ul>
  <li class="slds-expression__row">
    <fieldset>
      <legend class="slds-expression__legend">

The first child DOM element of the <fieldset> should be the <legend>, which includes the logic operator, such as "AND" or "OR", and assistive text describing the current rule, such as "Condition 3".

<legend class="slds-expression__legend">
  <span>AND</span>
  <span class="slds-assistive-text">Condition N</span>
</legend>

Focus Management#

Adding:

When clicking Add Condition:

• Focus should move to the first combobox input in the new rule, labeled "Resource" or something similar

When clicking Add Group:

• Focus should move to the mode combobox in the new group, where "All Conditions Are Met For This Group" should be selected by default

Deleting:

When "deleting" the only row:

• When there is only one row, the delete button is disabled until a Resource is selected.
• If a Resource has been selected, then clicking the delete button resets to the Default State, since there is a one row minimum. This includes:
  1. Clear any comboboxes or inputs that have been changed from the default
  2. Use JavaScript to move focus to the "Resource" combobox input of that same row.
  3. Disable the "Operator" and "Value" inputs, as well as the Delete button

When deleting the first row or a middle row:

• Use JavaScript to move focus to the first combobox input in the next row, labeled "Resource" or something similar.

When deleting the last row:

• Use JavaScript to move focus to the first combobox input in the previous row, labeled "Resource" or something similar.

Base#

<div class="slds-expression">
  <h2 class="slds-expression__title">Conditions</h2>
  <div class="slds-expression__options">
    <div class="slds-form-element">

By default, the expression builder starts with one condition. The default option for the mode combobox is "All Conditions Are Met". Until a Resource is selected, the Operator and Value fields, as well as the Delete button, are disabled.

The expression builder has a one row minimum requirement. Therefore, clicking the delete button on a single row will only clear any populated values from the inputs.

Label Note

Be sure to show labels above all inputs. By default "Take Action When" is the label for the mode combobox. However, this should be updated based on the product or persona to best match the use case. Similarly, use “Resource”, “Operator”, and “Value” as labels in each row, but, when relevant, replace “Resource” with a more specific label for your use case (e.g. “Field”).

Initial State#

Since the options in the Operator field and the type of component used for the Value field are dependent on the Resource selected, the Operator and Value Fields are disabled in the initial state until a Resource is selected. The Delete button is also disabled until a Resource is selected.

<div class="slds-expression">
  <h2 class="slds-expression__title">Conditions</h2>
  <div class="slds-expression__options">
    <div class="slds-form-element">

Resource Selected#

Once a resource is selected, the values for the Operator field update to correspond with the type of Resource selected. Similarly, the component used for the Value field can be an input, combobox, picklist, or lookup, depending on what Resource was chosen.

<div class="slds-expression">
  <h2 class="slds-expression__title">Conditions</h2>
  <div class="slds-expression__options">
    <div class="slds-form-element">

New Condition Added#

<div class="slds-expression">
  <h2 class="slds-expression__title">Conditions</h2>
  <div class="slds-expression__options">
    <div class="slds-form-element">

Error State#

<div class="slds-expression">
  <h2 class="slds-expression__title">Conditions</h2>
  <div class="slds-expression__options">
    <div class="slds-form-element">

All or Any Conditions#

When the user selects "All Conditions Are Met" from the mode combobox and adds a second condition, the expression builder will use AND logic:

<div class="slds-expression">
  <h2 class="slds-expression__title">Conditions</h2>
  <div class="slds-expression__options">
    <div class="slds-form-element">

If the user selects "Any Condition Is Met" from the mode combobox, the expression builder will use OR logic:

<div class="slds-expression">
  <h2 class="slds-expression__title">Conditions</h2>
  <div class="slds-expression__options">
    <div class="slds-form-element">

With an Expression Group#

To create more complex expressions, the user can add an expression group to create something like Condition 1 AND (Condition 2 OR Condition 3)

Interaction Details:

1. New groups are added when the Add Group button is selected
2. The only mode combobox options inside of a group are All and Any
3. Only one level of groups is desirable, so there is no Add Group button inside of a Group
   • All logical expressions can be written with one level of nesting, so this maintains the best readability
4. Deleting the only rule in a group removes the entire group
5. If a group is added but the first, default rule has not been altered, the first rule is replaced by the group

Label Note

The values in the group mode combobox get "for This Group" appended, ex. "All Conditions are Met for This Group"

<div class="slds-expression">
  <h2 class="slds-expression__title">Conditions</h2>
  <div class="slds-expression__options">
    <div class="slds-form-element">

Custom Logic#

Another option for creating more complex expressions is using the Custom Logic variant. This allows users to manually type their custom logic into an input field, which references the numbered conditions below, like 1 AND 2.

Interaction Details:

• After switching the mode to "Custom Logic", the default custom logic text input should match the previous user selection.
  1. For example, if the user was previously using "match Any", the input would default to something like 1 OR 2
  2. If the user had added a group previously, the input should reflect that group as well, something like 1 AND (2 OR 3)
  3. Otherwise, the input defaults to "match All", such as 1 AND 2
• New conditions are added to the end of the list, while AND n is added to the custom logic input text
• If a rule is removed, the custom logic should automatically rewrite to maintain intended logic

<div class="slds-expression">
  <h2 class="slds-expression__title">Conditions</h2>
  <div class="slds-expression__options">
    <div class="slds-form-element">

Formula Logic#

The Formula variant provides the user the most customization for their expressions. Users can write free-form custom logic by using the insertion comboboxes and/or typing freely. By default, the formula variant does not appear with default text.

Users can also validate the syntax to check for errors.

<div class="slds-expression">
  <div class="slds-expression__options">
    <div class="slds-form-element">
      <label class="slds-form-element__label" for="combobox-id-140">Take Action When</label>

Narrow#

Use the narrow variant for in-context expression building, where users are able to immediately preview the results of their conditional logic, like a list or report.

Accessibility Requirement

Be sure to use assistive text to improve the clarity of what the user might be editing. For example, add Edit filter: to each expression button element.

<div class="demo-only" style="max-width:320px;overflow:hidden">
  <div class="slds-filters">
    <h2 class="slds-text-heading_small">Conditions</h2>
    <div class="slds-m-vertical_small">

With an Expression Group#

<div class="demo-only" style="max-width:320px;overflow:hidden">
  <div class="slds-filters">
    <h2 class="slds-text-heading_small">Conditions</h2>
    <div class="slds-m-vertical_small">

Filtering#

One example of in-context expression building is filtering. To see examples of filtering logic inside of a panel, checkout our Panel documentation

<div class="slds-filters">
  <ol class="slds-list_vertical slds-list_vertical-space">
    <li class="slds-item slds-hint-parent">
      <div class="slds-filters__item slds-grid slds-grid_vertical-align-center">

Adding a new filter#

<div class="slds-filters">
  <ol class="slds-list_vertical slds-list_vertical-space">
    <li class="slds-item slds-hint-parent">
      <div class="slds-filters__item slds-grid slds-grid_vertical-align-center">

With an error#

Accessibility Requirement

When an error message is displayed to the user, the <div> containing the error message should have the role="alert" attribute applied. This will immediately notify the user that an error has occurred.

Accessibility Requirement

The filter button that has an error is associated to that error with the use of aria-describedby. The value of aria-describedby matches the ID given to the element that contains the corresponding error message.

<div class="slds-filters">
  <div class="slds-text-color_error slds-m-bottom_x-small" role="alert">Filters could not be applied. Please fix the validation errors below.</div>
  <ol class="slds-list_vertical slds-list_vertical-space">
    <li class="slds-item slds-hint-parent">

With locked filters#

<div class="slds-filters">
  <ol class="slds-list_vertical slds-list_vertical-space">
    <li class="slds-item slds-hint-parent">
      <div class="slds-filters__item slds-grid slds-grid_vertical-align-center">