Skip to content

Commit 39cff56

Browse files
raysuelzerraysuelzer
committed
first commit
1 parent 290960c commit 39cff56

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

45 files changed

+13581
-2250
lines changed

‎README.md‎

Lines changed: 297 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,12 @@
11
# NgxAngularQueryBuilder
22

3+
The goal of this project is to enable Angular 12+ support for the original [angular2-query-builder](https://github.com/designermanjeets/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.
4+
5+
This project uses code from https://github.com/designermanjeets/Angular-QueryBuilder
6+
which in turn is a fork from https://github.com/zebzhao/Angular-QueryBuilder both developed under the MIT License.
7+
8+
Please see the original project here:
9+
310
This project was generated with [Angular CLI](https://github.com/angular/angular-cli) version 12.2.13.
411

512
## Development server
@@ -25,3 +32,293 @@ Run `ng e2e` to execute the end-to-end tests via a platform of your choice. To u
2532
## Further help
2633

2734
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.
35+
36+
37+
# Examples
38+
39+
## Basic Usage
40+
41+
##### `app.module.ts`
42+
```javascript
43+
import { NgxAngularQueryBuilderModule } from "ngx-angular-query-builder";
44+
import { AppComponent } from "./app.component"
45+
46+
@NgModule(imports: [
47+
...,
48+
NgxAngularQueryBuilderModule,
49+
])
50+
export class AppModule { }
51+
```
52+
53+
##### `app.component.html`
54+
```html
55+
...
56+
<query-builder [(ngModel)]='query' [config]='config'></query-builder>
57+
...
58+
```
59+
##### `app.component.ts`
60+
```javascript
61+
import { QueryBuilderConfig } from 'ngx-angular-query-builder';
62+
63+
export class AppComponent {
64+
query = {
65+
condition: 'and',
66+
rules: [
67+
{field: 'age', operator: '<=', value: 'Bob'},
68+
{field: 'gender', operator: '>=', value: 'm'}
69+
]
70+
};
71+
72+
config: QueryBuilderConfig = {
73+
fields: {
74+
age: {name: 'Age', type: 'number'},
75+
gender: {
76+
name: 'Gender',
77+
type: 'category',
78+
options: [
79+
{name: 'Male', value: 'm'},
80+
{name: 'Female', value: 'f'}
81+
]
82+
}
83+
}
84+
}
85+
}
86+
```
87+
88+
## Custom Input Components
89+
90+
##### `app.component.html`
91+
```html
92+
<query-builder [(ngModel)]='query' [config]='config'>
93+
<ng-container *queryInput="let rule; type: 'date'">
94+
<custom-datepicker [(ngModel)]="rule.value"></custom-datepicker>
95+
</ng-container>
96+
</query-builder>
97+
```
98+
99+
##### `app.component.ts`
100+
```javascript
101+
query = {
102+
condition: 'and',
103+
rules: [
104+
{field: 'birthday', operator: '=', value: new Date()}
105+
]
106+
};
107+
108+
config: QueryBuilderConfig = {
109+
fields: {
110+
birthday: {name: 'Birthday', type: 'date', operators: ['=', '<=', '>']
111+
defaultValue: (() => return new Date())
112+
},
113+
}
114+
}
115+
```
116+
117+
## Custom Styling (with Bootstrap 4)
118+
119+
[Bootstrap demo](https://zebzhao.github.io/Angular-QueryBuilder/demo/).
120+
121+
##### `app.component.html`
122+
```html
123+
<query-builder [(ngModel)]='query' [config]='config' [classNames]='classNames'></query-builder>
124+
```
125+
##### `app.component.ts`
126+
```javascript
127+
classNames: QueryBuilderClassNames = {
128+
removeIcon: 'fa fa-minus',
129+
addIcon: 'fa fa-plus',
130+
arrowIcon: 'fa fa-chevron-right px-2',
131+
button: 'btn',
132+
buttonGroup: 'btn-group',
133+
rightAlign: 'order-12 ml-auto',
134+
switchRow: 'd-flex px-2',
135+
switchGroup: 'd-flex align-items-center',
136+
switchRadio: 'custom-control-input',
137+
switchLabel: 'custom-control-label',
138+
switchControl: 'custom-control custom-radio custom-control-inline',
139+
row: 'row p-2 m-1',
140+
rule: 'border',
141+
ruleSet: 'border',
142+
invalidRuleSet: 'alert alert-danger',
143+
emptyWarning: 'text-danger mx-auto',
144+
operatorControl: 'form-control',
145+
operatorControlSize: 'col-auto pr-0',
146+
fieldControl: 'form-control',
147+
fieldControlSize: 'col-auto pr-0',
148+
entityControl: 'form-control',
149+
entityControlSize: 'col-auto pr-0',
150+
inputControl: 'form-control',
151+
inputControlSize: 'col-auto'
152+
}
153+
```
154+
155+
## Customizing with Angular Material
156+
157+
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.
158+
159+
#### `app.component.html`
160+
161+
```html
162+
<query-builder [(ngModel)]='query' [config]='config'>
163+
<ng-container *queryButtonGroup="let ruleset; let addRule=addRule; let addRuleSet=addRuleSet; let removeRuleSet=removeRuleSet">
164+
<button type="button" mat-button (click)="addRule()">+ Rule</button>
165+
<button type="button" mat-button (click)="addRuleSet()">+ Ruleset</button>
166+
<button type="button" mat-button (click)="removeRuleSet()">- Ruleset</button>
167+
</ng-container>
168+
<ng-container *queryRemoveButton="let rule; let removeRule=removeRule">
169+
<button type="button" mat-icon-button color="accent" (click)="removeRule(rule)">
170+
<mat-icon>remove</mat-icon>
171+
</button>
172+
</ng-container>
173+
<ng-container *querySwitchGroup="let ruleset">
174+
<mat-radio-group *ngIf="ruleset" [(ngModel)]="ruleset.condition">
175+
<mat-radio-button value="and">And</mat-radio-button>
176+
<mat-radio-button value="or">Or</mat-radio-button>
177+
</mat-radio-group>
178+
</ng-container>
179+
<ng-container *queryField="let rule; let fields=fields; let onChange=onChange">
180+
<mat-form-field>
181+
<mat-select [(ngModel)]="rule.field" (ngModelChange)="onChange($event, rule)">
182+
<mat-option *ngFor="let field of fields" [value]="field.value">{{field.name}}</mat-option>
183+
</mat-select>
184+
</mat-form-field>
185+
</ng-container>
186+
<ng-container *queryOperator="let rule; let operators=operators">
187+
<mat-form-field>
188+
<mat-select [(ngModel)]="rule.operator">
189+
<mat-option *ngFor="let value of operators" [value]="value">{{value}}</mat-option>
190+
</mat-select>
191+
</mat-form-field>
192+
</ng-container>
193+
<!-- Override input component for 'boolean' type -->
194+
<ng-container *queryInput="let rule; type: 'boolean'">
195+
<mat-checkbox [(ngModel)]="rule.value"></mat-checkbox>
196+
</ng-container>
197+
<!-- Override input component for 'category' type -->
198+
<ng-container *queryInput="let rule; let field=field; let options=options; type: 'category'">
199+
<mat-form-field>
200+
<mat-select [(ngModel)]="rule.value" [placeholder]="field.name">
201+
<mat-option *ngFor="let opt of options" [value]="opt.value">
202+
{{ opt.name }}
203+
</mat-option>
204+
</mat-select>
205+
</mat-form-field>
206+
</ng-container>
207+
...
208+
</query-builder>
209+
```
210+
211+
## Property Bindings Quick Reference
212+
213+
See [documentation](https://zebzhao.github.io/Angular-QueryBuilder/) for more details on interfaces and properties.
214+
215+
#### `query-builder`
216+
|Name|Type|Required|Default|Description|
217+
|:--- |:--- |:--- |:--- |:--- |
218+
|`allowRuleset`|`boolean`|Optional|`true`| Displays the `+ Ruleset` button if `true`. |
219+
|`allowCollapse`|`boolean`|Optional|`false`| Enables collapsible rule sets if `true`. ([See Demo](https://zebzhao.github.io/Angular-QueryBuilder/demo/)) |
220+
|`classNames`|`object`|Optional|| CSS class names for different child elements in `query-builder` component. |
221+
|`config`|`QueryBuilderConfig`|Required|| Configuration object for the main component. |
222+
|`data`|`Ruleset`|Optional|| (Use `ngModel` or `value` instead.) |
223+
|`emptyMessage`|`string`|Optional|| Message to display for an empty Ruleset if empty rulesets are not allowed. |
224+
|`ngModel`| `Ruleset` |Optional|| Object that stores the state of the component. Supports 2-way binding. |
225+
|`operatorMap`|`{ [key: string]: string[] }`|Optional|| Used to map field types to list of operators. |
226+
|`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. |
227+
|`config.calculateFieldChangeValue`|`(currentField: Field, nextField: Field, currentValue: any) => any`|Optional|| Used to calculate the new value when a rule's field changes. |
228+
|`value`| `Ruleset` |Optional|| Object that stores the state of the component. |
229+
230+
## Structural Directives
231+
232+
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.
233+
234+
#### `queryInput`
235+
236+
Used to replace the input component. Specify the type/queryInputType to match specific field types to input template.
237+
238+
|Context Name|Type|Description|
239+
|:--- |:--- |:--- |
240+
|`$implicit`|`Rule`|Current rule object which contains the field, value, and operator|
241+
|`field`|`Field`|Current field object which contains the field's value and name|
242+
|`options`|`Option[]`|List of options for the field, returned by `getOptions`|
243+
|`onChange`|`() => void`|Callback to handle changes to the input component|
244+
245+
#### `queryOperator`
246+
247+
Used to replace the query operator selection component.
248+
249+
|Context Name|Type|Description|
250+
|:--- |:--- |:--- |
251+
|`$implicit`|`Rule`|Current rule object which contains the field, value, and operator|
252+
|`operators`|`string[]`|List of operators for the field, returned by `getOperators`|
253+
|`onChange`|`() => void`|Callback to handle changes to the operator component|
254+
|`type`|`string`|Input binding specifying the field type mapped to this input template, specified using syntax in above example|
255+
256+
#### `queryField`
257+
258+
Used this directive to replace the query field selection component.
259+
260+
|Context Name|Type|Description|
261+
|:--- |:--- |:--- |
262+
|`$implicit`|`Rule`|Current rule object which contains the field, value, and operator|
263+
|`getFields`|`(entityName: string) => void`|Get the list of fields corresponding to an entity|
264+
|`fields`|`Field[]`|List of fields for the component, specified by `config`|
265+
|`onChange`|`(fieldValue: string, rule: Rule) => void`|Callback to handle changes to the field component|
266+
267+
#### `queryEntity`
268+
269+
Used to replace entity selection component.
270+
271+
|Context Name|Type|Description|
272+
|:--- |:--- |:--- |
273+
|`$implicit`|`Rule`|Current rule object which contains the field, value, and operator|
274+
|`entities`|`Entity[]`|List of entities for the component, specified by `config`|
275+
|`onChange`|`(entityValue: string, rule: Rule) => void`|Callback to handle changes to the entity component|
276+
277+
#### `querySwitchGroup`
278+
279+
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.
280+
281+
|Context Name|Type|Description|
282+
|:--- |:--- |:--- |
283+
|`$implicit`|`RuleSet`|Current rule set object which contain a list of child rules|
284+
|`onChange`|`() => void`|Callback to handle changes to the switch group component|
285+
286+
#### `queryArrowIcon`
287+
288+
Directive to replace the expand arrow used in collapse/accordion mode of the query builder.
289+
290+
|Context Name|Type|Description|
291+
|:--- |:--- |:--- |
292+
|`$implicit`|`RuleSet`|Current rule set object which contain a list of child rules|
293+
294+
#### `queryEmptyWarning`
295+
296+
Can be used to customize the default empty warning message, alternatively can specify the `emptyMessage` property binding.
297+
298+
|Context Name|Type|Description|
299+
|:--- |:--- |:--- |
300+
|`$implicit`|`RuleSet`|Current rule set object which contain a list of child rules|
301+
|`message`|`string`|Value passed to `emptyMessage`|
302+
303+
#### `queryButtonGroup`
304+
305+
For replacing the default button group for Add, Add Ruleset, Remove Ruleset buttons.
306+
307+
|Context Name|Type|Description|
308+
|:--- |:--- |:--- |
309+
|`$implicit`|`RuleSet`|Current rule set object which contain a list of child rules|
310+
|`addRule`|`() => void`|Function to handle adding a new rule|
311+
|`addRuleSet`|`() => void`|Function to handle adding a new rule set|
312+
|`removeRuleSet`|`() => void`|Function to handle removing the current rule set|
313+
314+
#### `queryRemoveButton`
315+
316+
Directive to replace the default remove single rule button component.
317+
318+
|Context Name|Type|Description|
319+
|:--- |:--- |:--- |
320+
|`$implicit`|`Rule`|Current rule object which contains the field, value, and operator|
321+
|`removeRule`|`(rule: Rule) => void`|Function to handle removing a rule|
322+
323+
## Dependencies
324+
- Angular 8+

0 commit comments

Comments
 (0)