Query Builder Specification

Table of Contents

• 1. Background
  • 1.1. The Existing Query Builder
• 2. Phases
  • 2.1. Phase 1: Code Refactor
    • 2.1.1. Requirements
    • 2.1.2. Code Migration
    • 2.1.3. Props Refactor
  • 2.2. Phase 2: Styling Update
  • 2.3. Phase 3: Integration with Promotions

Background

The purpose of this document is to lay out the technical specifications and plan for building a resuable query builder. It builds on the base query builder that was introduced as part of the Customer Groups section by removing any existing dependencies to customer groups, updating component styling, and adding query methods that are appropriate promotions.

The Existing Query Builder

The current Query Builder is a React component that exists as part of the Customer Groups feature. The main source exists at query-builder.jsx

It is a dumb component that accepts the following properties:

• conditions: a series of conditions (each line in the display of the query builder)
• isValid: a flag signifying whether a condition can be added
• setConditions: a function that passes the modified set of conditions to the caller when something is changed

Phases

Phase 1: Code Refactor

Requirements

When completed the Query Builder should meet the following requirements:

1. `QueryBuilder` should live in its own folder under `components/` in Ashes
2. It should accept and return a pure ElasticSearch queries
3. It should accept criterions as a prop
4. Flow type checking should be enabled

Those four requirements can be bundled into three distinct steps:

• Code migration: move the component to its own folder
• Props refactor: generalize props so that the component can be used in a variety of places in the codebase
• Flowtype: Add type checking

Code Migration

This one is pretty straightforward as it simply involves moving the component from under the customer groups directory and into its own standalone directory.

Acceptance Criteria

• query-builder.jsx exists under the folder components/query-builder/
• Any components needed by `QueryBuilder` should be moved out of the customer groups folder
• The ability to create dynamic customer groups is unaffected

Props Refactor

The goal of this story is to generalize the usage of the component by making the props accepted by the component simple and easy to understand, and centralize logic needed to make the component work into one place.

Most of what's needed should already exist in the codebase, this work item is just a matter of reorganizing things to make the component more reusable and understandable.

Acceptance Criteria

• Convert conditions from being an array of strings to a typed structure

  Here's an example for how we might currently think about conditions:

  type Condition: Array<string|number>;
            
  const conditions: Array<Condition> = [
    ['totalSales', 'equals', 1200],
    ['email', 'equals', 'jeff@foxcommerce.com'],
  ];

  Let's move it a typed structure, such as:

  type Condition = {
    term: string,
    operator: 'equals' | 'not equals',
    value: string|number,
  };
            
  const conditions: Condition = [
    { term: 'totalSales', operator: 'equals', value: 1200 },
    { term: 'email', operator: 'equals', value: 'jeff@foxcommerce.com' },
  ];

• QueryBuilder props accept an ElasticSearch query instead of a set of conditions

TODO Check out request-adapter.js

Phase 2: Styling Update

Phase 3: Integration with Promotions