https://github.com/raysuelzer/ngx-angular-query-builder
A version of angular2-query-builder to work with Angular 12+ (Need maintainers)
https://github.com/raysuelzer/ngx-angular-query-builder
Last synced: 2 months ago
JSON representation
A version of angular2-query-builder to work with Angular 12+ (Need maintainers)
- Host: GitHub
- URL: https://github.com/raysuelzer/ngx-angular-query-builder
- Owner: raysuelzer
- License: other
- Created: 2021-11-23T23:07:06.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2024-08-21T17:35:40.000Z (about 1 year ago)
- Last Synced: 2024-12-28T13:31:45.701Z (10 months ago)
- Language: TypeScript
- Homepage:
- Size: 704 KB
- Stars: 32
- Watchers: 3
- Forks: 39
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-angular - ngx-angular-query-builder - A new version of [angular2-query-builder](https://github.com/zebzhao/Angular-QueryBuilder) that supports modern Angular. Used to create queries and filters. (Table of contents / Third Party Components)
- trackawesomelist - ngx-angular-query-builder (⭐30) - A new version of [angular2-query-builder (⭐293)](https://github.com/zebzhao/Angular-QueryBuilder) that supports modern Angular. Used to create queries and filters. (Recently Updated / [Sep 03, 2024](/content/2024/09/03/README.md))
- fucking-awesome-angular - ngx-angular-query-builder - A new version of <b><code> 305⭐</code></b> <b><code> 228🍴</code></b> [angular2-query-builder](https://github.com/zebzhao/Angular-QueryBuilder)) that supports modern Angular. Used to create queries and filters. (Table of contents / Third Party Components)
README
# NgxAngularQueryBuilder
The goal of this project is to enable Angular 12+ support for the original [angular2-query-builder](https://github.com/zebzhao/Angular-QueryBuilder). It is _not_ production ready. This project may not be maintained. Should the original project become active again, this library may be abandoned.
## I suggest forking this project if it is critical to your project because I may not update this regularly. If you want to contribute to maintaining this project open an issue.
The changelog for the package is here: https://github.com/raysuelzer/ngx-angular-query-builder/blob/main/projects/ngx-angular-query-builder/CHANGELOG.md
This project uses code from https://github.com/designermanjeets/Angular-QueryBuilder a fork of https://github.com/zebzhao/Angular-QueryBuilder both developed under the MIT License.
## Change Log
https://github.com/raysuelzer/ngx-angular-query-builder/blob/main/projects/ngx-angular-query-builder/CHANGELOG.md
## Branches
- Main should be the latest / highest version.
- feature/* is where changes are staged before being merged
- versions/* are the different versions for the angular packages ie. version 16 is versions/16.x.
# Versions
Use the following versions depending upon your angular version
- Angular 12 & 13 - Versions ^0.0.5
- Angular 13 - Versions 13.x.x
- Angular 14 - Versions 14.x.x
- Angular 15 - Versions 15.x.x
- Angular 16 - Versions 16.x.x
- Angular 17 - Versions 17.x.x
- Angular 18 - Versions 18.x.x
# Examples
npm install ngx-angular-query-builder
## Basic Usage
##### `app.module.ts`
```javascript
import { NgxAngularQueryBuilderModule } from "ngx-angular-query-builder";
import { AppComponent } from "./app.component"
@NgModule(imports: [
...,
NgxAngularQueryBuilderModule,
])
export class AppModule { }
```
##### `app.component.html`
```html
...
...
```
##### `app.component.ts`
```javascript
import { QueryBuilderConfig } from 'ngx-angular-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)
[Bootstrap demo](https://zebzhao.github.io/Angular-QueryBuilder/demo/).
##### `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 12+
This project was generated with [Angular CLI](https://github.com/angular/angular-cli) version 12.2.13.
## Development server
Run `ng serve` for a dev server. Navigate to `http://localhost:4200/`. The app will automatically reload if you change any of the source files.
## Code scaffolding
Run `ng generate component component-name` to generate a new component. You can also use `ng generate directive|pipe|service|class|guard|interface|enum|module`.
## Build
Run `ng build` to build the project. The build artifacts will be stored in the `dist/` directory.
## Running unit tests
Run `ng test` to execute the unit tests via [Karma](https://karma-runner.github.io).
## Running end-to-end tests
Run `ng e2e` to execute the end-to-end tests via a platform of your choice. To use this command, you need to first add a package that implements end-to-end testing capabilities.
## Further help
To get more help on the Angular CLI use `ng help` or go check out the [Angular CLI Overview and Command Reference](https://angular.io/cli) page.