QueryBuilder Component

The QueryBuilder is a versatile utility component designed for constructing database queries. it supports multiple operation modes, including a visual UI builder and direct SQL entry. It is designed to be highly compact and embeddable within sidebar settings or small UI subsections.

Location

valstorm-components-15/components/AppBuilder/components/Utility/QueryBuilder

---

Features

• Multiple Editor Modes:
  • UI Builder: A human-readable interface for building queries without writing code.
  • Custom SQL: A direct text-entry area for advanced SQL queries.
  • Mongo Query: (Coming Soon) Direct MongoDB query support.
• Collapsible Interface: Can be collapsed to save space, showing a truncated preview of the compiled query in the header.
• Smart SQL Compiler: Automatically converts UI configurations into valid SQL strings, handling operator-specific syntax (e.g., LIKE '%val%', IN (a, b)).
• Live Preview: Displays the resulting SQL query in real-time as you use the visual builder.
• Debounced Updates: Typing in custom SQL or rule values is debounced by 750ms to prevent overwhelming backends with partial queries during active editing.
• Controlled & Uncontrolled Support: Can be used as a standalone App Builder node or as a controlled input within other components (like ListViewSettings).

---

Props

Prop	Type	Default	Description
props	object	-	Standard App Builder props including appId, node, and handleClick.
value	object	-	(Optional) The current state object. Including this makes the component controlled.
onChange	function	-	(Optional) Callback fired when the query configuration changes.
showRunButton	boolean	true	Whether to display the "Run Query" button.
defaultCollapsed	boolean	false	Whether the component should start in a collapsed state.

---

State Structure (value)

The component manages a complex JSON object that represents both the UI state and the compiled output:

{
  "query_mode": "UI Builder",
  "sql_query": "SELECT * FROM users WHERE status = 'active' LIMIT 25 OFFSET 0",
  "ui_configuration": {
    "select": ["*"],
    "from": "users",
    "where": {
      "logical_operator": "AND",
      "rules": [
        { "field": "status", "operator": "=", "value": "active" }
      ]
    },
    "limit": 25,
    "offset": 0
  }
}

---

Usage Examples

1. Controlled Usage (Inside another component)

import { QueryBuilder } from "./QueryBuilder.component";

const MySettings = ({ filter, onUpdate }) => {
  return (
    <QueryBuilder
      value={{
        query_mode: filter.query_mode,
        sql_query: filter.query,
        ui_configuration: filter.ui_configuration
      }}
      onChange={(newValue) => {
        onUpdate({
          query_mode: newValue.query_mode,
          query: newValue.sql_query,
          ui_configuration: newValue.ui_configuration
        });
      }}
      defaultCollapsed={true}
      showRunButton={false}
    />
  );
}

2. Standard App Builder Node

When added to an App Builder page, the component uses the node.props.data for its state and behaves as an interactive widget.

---

Key Sub-Components

VisualQueryBuilder

Handles the rendering of the "UI Builder" mode.

• Select Fields: Multi-select autocomplete for table properties.
• From Table: Selection of available system schemas.
• Filters (Where): Dynamic list of rule rows.
• Adjustments: Vertical stack for Limit and Offset inputs.

Header Actions

The header includes an expand/collapse toggle and an Editor Mode selector. The mode selector allows users to "Eject" from the UI builder into Custom SQL.

Note: Switching from UI Builder to Custom SQL will populate the textarea with the compiled SQL. However, manually editing the SQL and then switching back to the UI Builder may result in a loss of manual SQL changes as the UI Builder state takes precedence when re-active.

ListViewSettings Component

The ListViewSettings component provides a comprehensive management interface for list_filter records. It allows users to configure how data is queried, displayed, and interacted with across various view modes (Table, List, Kanban).

Location

valstorm-components-15/components/AppBuilder/components/Utility/ListViewSettings

---

Features

• Filter Management:
  • Save/Update: Persist changes to the list_filter record.
  • Clone: Create a new copy of the current filter configuration.
  • Delete: Remove the current filter record.
• Dynamic Schema Integration: Automatically fetches and maps fields based on the selected target object.
• Multi-View Support:
  • General: Configure filter name and the underlying data object.
  • Query: Integrated QueryBuilder for visual or SQL-based data sourcing.
  • Default View: Set the starting view mode (Table, Kanban, List, or JSON).
  • Field Selection: Choose which fields appear in List and Table views.
  • Table Tweaks: Adjust column selection and individual column widths.
  • Kanban Mapping: Define grouping columns (Picklists only), swimlanes, and card content.
• Real-time Previews: Dispatches update_list_filter events to the system, allowing other components on the page to reflect configuration changes immediately without saving.

---

Props

Prop	Type	Default	Description
props	object	-	Standard App Builder props including appId, node, handleClick, and componentId.

---

Technical Details

State Management

The component uses a local filter state initialized from the selectedFilter provided by the useFilterState hook. It also listens to the eventSystem for edit_list_filter and switch_list_filter events to stay in sync with the user's focus.

Integration with QueryBuilder

The component leverages the QueryBuilder in controlled mode:

<QueryBuilder
  value={{
    query_mode: filter.query_mode,
    sql_query: filter.query,
    ui_configuration: filter.ui_configuration
  }}
  onChange={(newValue) => {
    // Updates filter state and dispatches update_list_filter event
  }}
  defaultCollapsed={true}
  showRunButton={false}
/>

Events

Event Type	Payload	Description
update_list_filter	filter record	Fired on any change to provide live previews.
open_clone_record_modal	{ record, schema }	Fired when clicking the Clone button.

---

Usage

Typically rendered in a sidebar or configuration panel within the App Builder or a Management interface to allow users to customize their data views.