https://github.com/solidexpert-ltd/ngx-query-builder
https://github.com/solidexpert-ltd/ngx-query-builder
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/solidexpert-ltd/ngx-query-builder
- Owner: solidexpert-ltd
- Created: 2025-03-11T18:40:58.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-03-11T18:54:07.000Z (9 months ago)
- Last Synced: 2025-03-11T19:38:21.895Z (9 months ago)
- Language: TypeScript
- Size: 0 Bytes
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-angular - ngx-query-builder - Angular query builder with standalone components, sensible defaults, templating hooks, and full form support for domain-specific editors. (Third Party Components / Forms)
README
# Angular-QueryBuilder
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.
# Getting Started
## Install
- Angular 15 use 15.0.x
- Angular 19 use 19.0.x
`npm install @solidexpert/ngx-query-builder`
# Examples
## Basic Usage
##### `app.module.ts`
```javascript
import { QueryBuilderModule } from "@solidexpert/ngx-query-builder";
import { AppComponent } from "./app.component"
@NgModule(imports: [
...,
QueryBuilderModule,
])
export class AppModule { }
```
##### `app.component.html`
```html
...
...
```
##### `app.component.ts`
```javascript
import { QueryBuilderConfig } from '@solidexpert/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`
```html
```
##### `app.component.ts`
```javascript
query = {
condition: 'and',
rules: [
{field: 'birthday', operator: '=', value: new Date()}
]
};
config: QueryBuilderConfig = {
fields: {
birthday: {name: 'Birthday', type: 'date', operators: ['=', '<=', '>']
defaultValue: (() => return new Date())
},
}
}
```
## Custom Styling (with Bootstrap 4)
##### `app.component.html`
```html
```
##### `app.component.ts`
```javascript
classNames: QueryBuilderClassNames = {
removeIcon: 'fa fa-minus',
addIcon: 'fa fa-plus',
arrowIcon: 'fa fa-chevron-right px-2',
button: 'btn',
buttonGroup: 'btn-group',
rightAlign: 'order-12 ml-auto',
switchRow: 'd-flex px-2',
switchGroup: 'd-flex align-items-center',
switchRadio: 'custom-control-input',
switchLabel: 'custom-control-label',
switchControl: 'custom-control custom-radio custom-control-inline',
row: 'row p-2 m-1',
rule: 'border',
ruleSet: 'border',
invalidRuleSet: 'alert alert-danger',
emptyWarning: 'text-danger mx-auto',
operatorControl: 'form-control',
operatorControlSize: 'col-auto pr-0',
fieldControl: 'form-control',
fieldControlSize: 'col-auto pr-0',
entityControl: 'form-control',
entityControlSize: 'col-auto pr-0',
inputControl: 'form-control',
inputControlSize: 'col-auto'
}
```
## Customizing with Angular Material
Example of how you can completely customize the query component with another library like Angular Material. For the full example, please look at the [source code](https://github.com/zebzhao/Angular-QueryBuilder/blob/master/demo/src/app/app.component.ts) provided in the demo.
#### `app.component.html`
```html
+ Rule
+ Ruleset
- Ruleset
remove
And
Or
{{field.name}}
{{value}}
{{ opt.name }}
...
```
## Property Bindings Quick Reference
See [documentation](https://zebzhao.github.io/Angular-QueryBuilder/) for more details on interfaces and properties.
#### `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`. ([See Demo](https://zebzhao.github.io/Angular-QueryBuilder/demo/)) |
|`classNames`|`object`|Optional|| CSS class names for different child elements in `query-builder` component. |
|`config`|`QueryBuilderConfig`|Required|| Configuration object for the main component. |
|`data`|`Ruleset`|Optional|| (Use `ngModel` or `value` instead.) |
|`emptyMessage`|`string`|Optional|| Message to display for an empty Ruleset if empty rulesets are not allowed. |
|`ngModel`| `Ruleset` |Optional|| 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|| Object that stores the state of the component. |
## Structural Directives
Use these directives to replace different parts of query builder with custom components. See [example](#customizing-with-angular-material), or [demo](https://zebzhao.github.io/Angular-QueryBuilder/demo/) to see how it's done.
#### `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|
#### `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|
|`type`|`string`|Input binding specifying the field type mapped to this input template, specified using syntax in above example|
#### `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|
#### `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|
#### `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|
#### `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|
#### `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`|
#### `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|
|`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|
#### `queryRemoveButton`
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|
## Dependencies
- Angular 8+
That's it.
# Workflow
See the [angular-library-seed](https://github.com/trekhleb/angular-library-seed) project for details on how to build and run tests.