diff --git a/README.md b/README.md index fcd3662..4c880f8 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,313 @@ # Angular Condition Builder -THIS IS A FOLK OF https://github.com/zebzhao/Angular-QueryBuilder WITH THE LATEST ANGULAR + +

+ + Test CI + + + npm + + + monthly downloads + +

+ +> [!NOTE] +> This is a folk of zebzhao's [repo](https://github.com/zebzhao/Angular-QueryBuilder) to maintence with the latest Angular + +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. + +## Installation + +``` +$ npm install @angular-ex/ngx-condition-builder --save +``` + +## Basic Usage + +##### `app.module.ts` +```javascript +import { QueryBuilderModule } from "angular2-query-builder"; +import { AppComponent } from "./app.component" + +@NgModule(imports: [ + ..., + QueryBuilderModule, + IonicModule.forRoot(AppComponent) // (Optional) for IonicFramework 2+ +]) +export class AppModule { } +``` + +##### `app.component.html` +```html +... + +... +``` +##### `app.component.ts` +```javascript +import { QueryBuilderConfig } from 'angular2-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 + + + + + + + + + + + + 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+