@kerwin612/ngx-query-builder

ngx-query-builder

A modernized Angular 4+ query builder based on jQuery QueryBuilder. Support for heavy customization with Angular components and provides a flexible way to handle custom data types.

Forked from (https://github.com/zebzhao/Angular-QueryBuilder) as the original project has stopped updating and does not support the latest Angular versions, so I will continue to maintain it and support the latest versions of Angular.

Getting Started

Install

• Angular latest, use 0.6.3+

npm install @kerwin612/ngx-query-builder

---

• Angular 9, use 0.6.0
• Angular 8, use 0.5.1
• Angular 6-7, use 0.4.2
• Angular 4-5, use 0.3.2

npm install angular2-query-builder

See https://github.com/zebzhao/Angular-QueryBuilder for more details on the usage of the old version.

Examples

Basic Usage

app.module.ts

import { QueryBuilderModule } from "ngx-query-builder";
import { AppComponent } from "./app.component"

@NgModule(imports: [
  ...,
  QueryBuilderModule,
  IonicModule.forRoot(AppComponent) // (Optional) for IonicFramework 2+
])
export class AppModule { }

app.component.html

...
<ngx-query-builder [(ngModel)]='query' [config]='config'></ngx-query-builder>
...

app.component.ts

import { QueryBuilderConfig } from 'ngx-query-builder';

export class AppComponent {
  query = {
    condition: 'and',
    rules: [
      {field: 'age', operator: '<=', value: 'Bob'},
      {field: 'gender', operator: '>=', value: 'm'}
    ]
  };
  
  config: QueryBuilderConfig = {
    fields: {
      age: {name: 'Age', type: 'number'},
      gender: {
        name: 'Gender',
        type: 'category',
        options: [
          {name: 'Male', value: 'm'},
          {name: 'Female', value: 'f'}
        ]
      }
    }
  }
}

Custom Input Components

app.component.html

<ngx-query-builder [(ngModel)]='query' [config]='config'>
  <ng-container *queryInput="let rule; type: 'date'">
    <custom-datepicker [(ngModel)]="rule.value"></custom-datepicker>
  </ng-container>
</ngx-query-builder>

app.component.ts

query = {
  condition: 'and',
  rules: [
    {field: 'birthday', operator: '=', value: new Date()}
  ]
};

config: QueryBuilderConfig = {
  fields: {
    birthday: {name: 'Birthday', type: 'date', operators: ['=', '<=', '>']
      defaultValue: (() => return new Date())
    },
  }
}

Property Bindings Quick Reference

ngx-query-builder

Name	Type	Required	Default	Description
allowRuleset	boolean	Optional	true	Displays the + Ruleset button if true.
allowCollapse	boolean	Optional	false	Enables collapsible rule sets if true.
classNames	QueryBuilderClassNames	Optional		CSS class names for different child elements in query-builder component.
config	QueryBuilderConfig	Required		Configuration object for the main component.
data	Ruleset	Optional	{ condition: 'and', rules: [] }	(Use ngModel or value instead.)
emptyMessage	string	Optional		Message to display for an empty Ruleset if empty rulesets are not allowed.
ngModel	Ruleset	Optional	{ condition: 'and', rules: [] }	Object that stores the state of the component. Supports 2-way binding.
operatorMap	{ [key: string]: string[] }	Optional		Used to map field types to list of operators.
persistValueOnFieldChange	boolean	Optional	false	If true, when a field changes to another of the same type, and the type is one of: string, number, time, date, or boolean, persist the previous value. This option is ignored if config.calculateFieldChangeValue is provided.
config.calculateFieldChangeValue	(currentField: Field, nextField: Field, currentValue: any) => any	Optional		Used to calculate the new value when a rule's field changes.
value	Ruleset	Optional	{ condition: 'and', rules: [] }	Object that stores the state of the component.

Structural Directives

Use these directives to replace different parts of query builder with custom components.

queryArrowIcon

Directive to replace the expand arrow used in collapse/accordion mode of the query builder.

Context Name	Type	Description
$implicit	RuleSet	Current rule set object which contain a list of child rules
getDisabledState	() => boolean	Retrieves or determines the disabled state of the component

querySwitchGroup

Useful for replacing the switch controls, for example the AND/OR conditions. More custom conditions can be specified by using this directive to override the default component.

Context Name	Type	Description
$implicit	RuleSet	Current rule set object which contain a list of child rules
onChange	() => void	Callback to handle changes to the switch group component
getDisabledState	() => boolean	Retrieves or determines the disabled state of the component

queryButtonGroup

For replacing the default button group for Add, Add Ruleset, Remove Ruleset buttons.

Context Name	Type	Description
$implicit	RuleSet	Current rule set object which contain a list of child rules
parentValue	RuleSet	For parent node's data if exists
addRule	() => void	Function to handle adding a new rule
addRuleSet	() => void	Function to handle adding a new rule set
removeRuleSet	() => void	Function to handle removing the current rule set
getDisabledState	() => boolean	Retrieves or determines the disabled state of the component

queryRulesetAddRuleButton

For replacing the default button for Add Rule.

Context Name	Type	Description
$implicit	RuleSet	Current rule set object which contain a list of child rules
addRule	() => void	Function to handle adding a new rule
getDisabledState	() => boolean	Retrieves or determines the disabled state of the component

queryRulesetAddRulesetButton

For replacing the default button for Add Ruleset.

Context Name	Type	Description
$implicit	RuleSet	Current rule set object which contain a list of child rules
addRuleSet	() => void	Function to handle adding a new rule set
getDisabledState	() => boolean	Retrieves or determines the disabled state of the component

queryRulesetRemoveButton

For replacing the default button for Remove Ruleset.

Context Name	Type	Description
$implicit	RuleSet	Current rule set object which contain a list of child rules
removeRuleSet	() => void	Function to handle removing the current rule set
getDisabledState	() => boolean	Retrieves or determines the disabled state of the component

queryEntity

Used to replace entity selection component.

Context Name	Type	Description
$implicit	Rule	Current rule object which contains the field, value, and operator
entities	Entity[]	List of entities for the component, specified by config
onChange	(entityValue: string, rule: Rule) => void	Callback to handle changes to the entity component
getDisabledState	() => boolean	Retrieves or determines the disabled state of the component

queryField

Used this directive to replace the query field selection component.

Context Name	Type	Description
$implicit	Rule	Current rule object which contains the field, value, and operator
getFields	(entityName: string) => void	Get the list of fields corresponding to an entity
fields	Field[]	List of fields for the component, specified by config
onChange	(fieldValue: string, rule: Rule) => void	Callback to handle changes to the field component
getDisabledState	() => boolean	Retrieves or determines the disabled state of the component

queryOperator

Used to replace the query operator selection component.

Context Name	Type	Description
$implicit	Rule	Current rule object which contains the field, value, and operator
operators	string[]	List of operators for the field, returned by getOperators
onChange	() => void	Callback to handle changes to the operator component
getDisabledState	() => boolean	Retrieves or determines the disabled state of the component

queryInput

Used to replace the input component. Specify the type/queryInputType to match specific field types to input template.

Context Name	Type	Description
$implicit	Rule	Current rule object which contains the field, value, and operator
field	Field	Current field object which contains the field's value and name
options	Option[]	List of options for the field, returned by getOptions
onChange	() => void	Callback to handle changes to the input component
getDisabledState	() => boolean	Retrieves or determines the disabled state of the component

queryRuleRemoveButton

Directive to replace the default remove single rule button component.

Context Name	Type	Description
$implicit	Rule	Current rule object which contains the field, value, and operator
removeRule	(rule: Rule) => void	Function to handle removing a rule
getDisabledState	() => boolean	Retrieves or determines the disabled state of the component

queryEmptyWarning

Can be used to customize the default empty warning message, alternatively can specify the emptyMessage property binding.

Context Name	Type	Description
$implicit	RuleSet	Current rule set object which contain a list of child rules
message	string	Value passed to emptyMessage
getDisabledState	() => boolean	Retrieves or determines the disabled state of the component

Dependencies

• Angular 8+

Development

dev

• pnpm watch
• pnpm start

build

• pnpm build

For use in other local projects

cd dist/ngx-query-builder
npm link

cd /path/to/other/project
npm link ngx-query-builder

That's it.