AdvancedQueryFilter

AdvancedQueryFilter is a comprehensive React component designed to create powerful filtering interfaces with the ability to save, edit, and manage queries. It combines form controls with query management features, making it ideal for advanced search scenarios in data-intensive applications.

Features

• Dynamic Form Generation - Builds form interfaces based on provided field definitions
• Query Operations - Supports various query operations like "greater than", "begins with", etc.
• Query Management - Save, load, edit, and delete queries
• Customizable Buttons - Add custom action buttons to extend functionality
• Controlled State - Fully controlled component with callback functions for state management

Installation

npm install advanced-query-filter
# or
yarn add advanced-query-filter

Component API

Props

Prop	Type	Required	Default	Description
getActionData	function	Yes	-	Callback function when actions occur (search, save, delete). Receives object with action type and value.
initialSavedQueries	object	Yes	-	Object containing initial saved queries to populate the component.
formName	string	Yes	-	Title of the form displayed to users.
formDefinition	array	Yes	-	Array of field definitions that specify the structure of the form.
buttonDefinition	array	No	[]	Array of custom button definitions to add to the query panel.
customButtonFunction	function	No	() => {}	Callback function for custom buttons. Receives the event and button label.
onAppend	function	No	-	Callback when append action is triggered for a field.
onSearch	function	No	-	Callback when search action is triggered for a field.
onView	function	No	-	Callback when view action is triggered for a field.

Field Definition Schema

Each field in the formDefinition array should be an object with the following properties:

Property	Type	Required	Description
name	string	Yes	Unique identifier for the field.
label	string	Yes	Display label for the field.
type	string	No	Input type (e.g., "text", "number").
hasAdvancedFeatures	boolean	No	Whether the field supports advanced query operations.
showCondition	boolean	No	Whether to show condition selection for this field.
searchable	boolean	No	Whether this field supports search operations.
viewable	boolean	No	Whether this field supports view operations.
appendable	boolean	No	Whether this field supports append operations.
render	function	No	Custom render function for complex fields like dropdowns or checkboxes.

Query Data Format

The query data format for saved queries and form data follows this structure:

{
  fieldName: {
    value: any, // The actual value of the field
    query: string // The query operator like "gt", "begins_with", etc.
  }
}

Basic Usage

import React from 'react';
import AdvancedQueryFilter from './AdvancedQueryFilter';

function MyFilterComponent() {
  // Initial saved queries
  const initialSavedQueries = {
    "query1": {
      id: { value: 101, query: "gt" },
      userName: { value: "Alice", query: null },
      domain: { value: "example.com", query: "begins_with" },
      cityDropdown: { value: { name: "Delhi" }, query: null },
      checkbox1: { value: true, query: null },
    },
    "query2": {
      id: { value: 102, query: null },
      userName: { value: "Bob", query: null },
      domain: { value: "domain.com", query: null },
      cityDropdown: { value: { name: "Lucknow" }, query: null },
      checkbox1: { value: false, query: null },
    }
  };

  // Action callback
  const getActionData = (data) => {
    console.log("Action data:", data);
    // Handle different actions (search, save, delete)
    switch (data.action) {
      case "search":
        // Process search with data.value
        break;
      case "save":
        // Update saved queries in your storage
        break;
      case "delete":
        // Remove saved query from your storage
        break;
      default:
        break;
    }
  };

  // Form field definitions
  const formDefinition = [
    {
      name: "userName",
      label: "User Name",
      type: "text",
      hasAdvancedFeatures: true,
    },
    {
      name: "domain",
      label: "Domain Name",
      type: "text",
      showCondition: false,
      hasAdvancedFeatures: true
    },
    {
      name: "id",
      label: "ID",
      type: "number",
      showCondition: true,
      searchable: true,
      viewable: true,
      appendable: true,
    }
  ];

  // Event handlers
  const onSearch = (label) => {
    console.log("onSearch method called", label);
  };
  
  const onView = (label) => {
    console.log("onView method called", label);
  };
  
  const onAppend = (label) => {
    console.log("onAppend method called", label);
  };

  // Custom button definitions
  const buttonDefinition = [
    {
      label: "custom1",
    },
    {
      label: "custom2",
    }
  ];

  // Custom button handler
  const customButtonFunction = (e, label) => {
    console.log("Custom button clicked:", label);
  };

  return (
    <AdvancedQueryFilter
      formName="User Management Form"
      getActionData={getActionData}
      initialSavedQueries={initialSavedQueries}
      buttonDefinition={buttonDefinition}
      customButtonFunction={customButtonFunction}
      formDefinition={formDefinition}
      onView={onView}
      onSearch={onSearch}
      onAppend={onAppend}
    />
  );
}

export default MyFilterComponent;

Advanced Usage

Custom Form Fields

For complex input types like dropdowns or checkboxes, you can use the render property to define custom renderers:

// Form definition with custom renderers
const formDefinition = [
  // Standard fields
  {
    name: "userName",
    label: "User Name",
    type: "text",
    hasAdvancedFeatures: true
  },
  // Custom dropdown field
  {
    name: "cityDropdown",
    render: () => (
      <div className="card flex justify-content-center">
        <Dropdown
          value={formData["cityDropdown"]?.value || null}
          name="cityDropdown"
          onChange={(e) => handleFormChange(e.target.name, e.value)}
          options={cities}
          optionLabel="name"
          placeholder="Select a City"
          className="w-full md:w-14rem"
        />
      </div>
    ),
  },
  // Custom checkbox field
  {
    name: "checkbox",
    render: () => (
      <div className="card flex justify-content-center">
        <label>checkbox</label>
        <Checkbox
          name="checkbox1"
          onChange={(e) => handleFormChange(e.target.name, e.target.checked)}
          checked={formData["checkbox1"]?.value || false}
        />
      </div>
    ),
  },
];

Handling Query Operations

The component supports field-specific query operations through the query property in the form data. Common operations include:

• gt - Greater than
• lt - Less than
• eq - Equal to
• begins_with - Begins with
• contains - Contains
• ends_with - Ends with

You can extend these operations according to your application needs.

Component Structure

The AdvancedQueryFilter component consists of three main sub-components:

1. AdvancedForm - Renders the form fields based on the provided definition
2. QueryPanel - Provides buttons for managing queries and executing actions
3. SavedQueryDialog - Dialog for saving and confirming deletion of queries

State Management

The component manages several internal states:

• formData - Current values and query operations for each field
• savedQueries - Collection of saved queries
• selectedQuery - Currently selected query
• isFormDisabled - Whether form fields are read-only
• dialogVisible - Dialog visibility state
• Button visibility states (showSave, showEdit, showDelete)

Event Flow

1. User fills out the form and sets query conditions
2. User can perform actions:
   • Search - Execute search with current form values
   • Save Query - Save current form state as a named query
   • Load Query - Load a previously saved query
   • Edit Query - Edit a loaded query
   • Delete Query - Remove a saved query
   • Custom Actions - Execute user-defined actions

Dependencies

This component requires:

• React 16.8+ (for Hooks support)
• Any UI component library for the form controls (like PrimeReact in the example)

Styling

The component doesn't include specific styling rules, allowing you to integrate it with your application's design system. You should provide appropriate CSS for:

• Form layout and spacing
• Button styling
• Dialog appearance

Best Practices

1. Consistent Query Structure - Maintain consistent query operation naming across your application
2. Validation - Add validation for query conditions based on field types
3. Persistence - Implement persistence for saved queries in a database or local storage
4. Accessibility - Ensure form elements have appropriate ARIA attributes
5. Error Handling - Add error handling for failed query operations

Troubleshooting

Common Issues

• Empty query list - Ensure initialSavedQueries is properly formatted
• Form fields not updating - Check that field names in formDefinition match keys in form data
• Custom buttons not working - Verify customButtonFunction is properly implemented

Contributing

Guidelines for contributing to the development of this component.

License

Specify your license information here.