From aaafb66d0346e06b0f808414822a27cda9211a37 Mon Sep 17 00:00:00 2001 From: igdmdimitrov Date: Fri, 27 Sep 2024 14:22:02 +0300 Subject: [PATCH 1/5] docs(query-builder): update topic with nested queries and templating --- en/components/query-builder.md | 94 +++++++++++++++++++++++++--------- en/components/toc.yml | 1 + 2 files changed, 71 insertions(+), 24 deletions(-) diff --git a/en/components/query-builder.md b/en/components/query-builder.md index cc2d506688..29192b7837 100644 --- a/en/components/query-builder.md +++ b/en/components/query-builder.md @@ -64,7 +64,7 @@ import { IGX_QUERY_BUILDER_DIRECTIVES, FilteringExpressionsTree, FieldType } fro selector: 'app-home', template: ` @@ -76,7 +76,7 @@ import { IGX_QUERY_BUILDER_DIRECTIVES, FilteringExpressionsTree, FieldType } fro }) export class HomeComponent { public expressionTree: FilteringExpressionsTree; - public fields: FieldType []; + public entities: Array; public onExpressionTreeChange() { ... @@ -88,41 +88,53 @@ Now that you have the Ignite UI for Angular Query Builder module or directives i ## Using the Angular Query Builder -If no expression tree is initially set, you start with creating a group of conditions linked with [`AND`]({environment:angularApiUrl}/enums/filteringlogic.html#and) or [`OR`]({environment:angularApiUrl}/enums/filteringlogic.html#or). After that, conditions or sub-groups can be added. +If no expression tree is initially set, you start with creating a group of conditions linked with [`AND`]({environment:angularApiUrl}/enums/filteringlogic.html#and) or [`OR`]({environment:angularApiUrl}/enums/filteringlogic.html#or). Then you choose entity and which fields the query should return. After that, conditions or sub-groups can be added. -In order to add a condition, a field, an operand based on the field dataType and a value if the operand is not unary. Once the condition is committed, a chip with the condition information appears. By hovering or clicking the chip, you have the options to modify it or add another condition or group right after it. +In order to add a condition you select a field, an operand based on the field data type and a value if the operand is not unary. The operands `In` and `Not In` will allow you to create inner query with conditions from different entity instead of providing a value. Once the condition is committed, a chip with the condition information appears. By clicking the chip, you have the options to modify it or add another condition or group right after it. If you select more than one condition chip, a context menu appears with options to create a group or delete the queries. If you choose to create a group with the selected conditions, the newly created group will appear where the topmost selected condition was placed. In order to select a group, you can also click on its vertical line, which is colored based on the linking condition ([`AND`]({environment:angularApiUrl}/enums/filteringlogic.html#and) or [`OR`]({environment:angularApiUrl}/enums/filteringlogic.html#or)). If a single group is selected, you get a context menu with options to change its logic, ungroup or delete it. -You can start using the component by setting the [`fields`]({environment:angularApiUrl}/classes/igxquerybuildercomponent.html#fields) property to an array describing the field name and its data type. It will automatically assign the corresponding operands based on the data type. +Since every condition is related to a specific field from a particular entity changing the entity will lead to resetting all present conditions and groups. When selecting a new entity a confirmation dialog will be shown unless the [`showEntityChangeDialog`]({environment:angularApiUrl}/classes/igxquerybuildercomponent.html#showEntityChangeDialog) input property is set to false. + +You can start using the component by setting the [`entities`]({environment:angularApiUrl}/classes/igxquerybuildercomponent.html#entities) property to an array describing the entity name and an array of its fields, where each field is defined by its name and data type. Once a field is selected it will automatically assign the corresponding operands based on the data type. The Query Builder has the [`expressionTree`]({environment:angularApiUrl}/classes/igxquerybuildercomponent.html#expressionTree) input property. You could use it to set an initial state of the control and access the user-specified filtering logic. ```typescript ngAfterViewInit(): void { - const tree = new FilteringExpressionsTree(FilteringLogic.And); + const innerTree = new FilteringExpressionsTree(FilteringLogic.And, undefined, 'Companies', ['ID']); + innerTree.filteringOperands.push({ + fieldName: 'Employees', + condition: IgxNumberFilteringOperand.instance().condition('greaterThan'), + conditionName: 'greaterThan', + searchVal: 100 + }); + innerTree.filteringOperands.push({ + fieldName: 'Contact', + condition: IgxBooleanFilteringOperand.instance().condition('true'), + conditionName: 'true' + }); + + const tree = new FilteringExpressionsTree(FilteringLogic.And, undefined, 'Orders', ['*']); tree.filteringOperands.push({ - fieldName: 'ID', - condition: IgxStringFilteringOperand.instance().condition('contains'), - searchVal: 'a', - ignoreCase: true + fieldName: 'CompanyID', + condition: IgxStringFilteringOperand.instance().condition('in'), + conditionName: 'in', + searchTree: innerTree }); - const subTree = new FilteringExpressionsTree(FilteringLogic.Or); - subTree.filteringOperands.push({ - fieldName: 'ContactTitle', - condition: IgxStringFilteringOperand.instance().condition('doesNotContain'), - searchVal: 'b', - ignoreCase: true + tree.filteringOperands.push({ + fieldName: 'OrderDate', + condition: IgxDateFilteringOperand.instance().condition('before'), + conditionName: 'before', + searchVal: new Date('2024-01-01T00:00:00.000Z') }); - subTree.filteringOperands.push({ - fieldName: 'CompanyName', - condition: IgxStringFilteringOperand.instance().condition('startsWith'), - searchVal: 'c', - ignoreCase: true + tree.filteringOperands.push({ + fieldName: 'ShippedDate', + condition: IgxDateFilteringOperand.instance().condition('null'), + conditionName: 'null' }); - tree.filteringOperands.push(subTree); - + this.queryBuilder.expressionTree = tree; } ``` @@ -131,12 +143,44 @@ The `expressionTree` is a two-way bindable property which means a corresponding ```html ``` +## Templating + +The Ignite UI for Angular Query Builder Component allows defining templates for header and search value using the following predefined reference names: + +### Header + +Passing content inside of the `igx-query-builder-header` allows templating the query builder header. The [`IgxQueryBuilderHeaderComponent`]({environment:angularApiUrl}/classes/igxquerybuilderheadercomponent.html) component provides a way to hide the legend by setting the [`showLegend`]({environment:angularApiUrl}/classes/igxquerybuilderheadercomponent.html#showLegend) input property is set to false. + + The code snippet below illustrates how to do this: + +```html + + + Build your query + + +``` + +### Search value + +The search value of a condition can be templated using the [`igxQueryBuilderSearchValue`]({environment:angularApiUrl}/classes/igxquerybuildersearchvaluetemplatedirective.html) directive, applied to a `` inside of the `igx-query-builder`'s body: + +```html + + + + + +``` + + + ## Styling To get started with styling the Query Builder, we need to import the `index` file, where all the theme functions and component mixins live: @@ -446,6 +490,8 @@ You can also streamline your Angular app development using [WYSIWYG App Builder
* [IgxQueryBuilderComponent API]({environment:angularApiUrl}/classes/igxquerybuildercomponent.html) +* [IgxQueryBuilderHeaderComponent]({environment:angularApiUrl}/classes/igxquerybuilderheadercomponent.html) +* [IgxQueryBuilderSearchValueTemplateDirective]({environment:angularApiUrl}/classes/igxquerybuildersearchvaluetemplatedirective.html) * [IgxQueryBuilderComponent Styles]({environment:sassApiUrl}/index.html#function-query-builder-theme) ## Additional Resources diff --git a/en/components/toc.yml b/en/components/toc.yml index f83ea1f9be..d3812bcd15 100644 --- a/en/components/toc.yml +++ b/en/components/toc.yml @@ -970,6 +970,7 @@ - name: Query Builder href: query-builder.md new: false + updated: true - name: Radio & Radio Group href: radio-button.md new: false From 8dcb5e2559b713a3865c2ffb117b70e354fc359c Mon Sep 17 00:00:00 2001 From: igdmdimitrov Date: Fri, 27 Sep 2024 15:37:28 +0300 Subject: [PATCH 2/5] chore(*): address PR comments --- en/components/query-builder.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/en/components/query-builder.md b/en/components/query-builder.md index 29192b7837..6e16c7abb6 100644 --- a/en/components/query-builder.md +++ b/en/components/query-builder.md @@ -88,15 +88,15 @@ Now that you have the Ignite UI for Angular Query Builder module or directives i ## Using the Angular Query Builder -If no expression tree is initially set, you start with creating a group of conditions linked with [`AND`]({environment:angularApiUrl}/enums/filteringlogic.html#and) or [`OR`]({environment:angularApiUrl}/enums/filteringlogic.html#or). Then you choose entity and which fields the query should return. After that, conditions or sub-groups can be added. +If no expression tree is initially set, you start with creating a group of conditions linked with [`AND`]({environment:angularApiUrl}/enums/filteringlogic.html#and) or [`OR`]({environment:angularApiUrl}/enums/filteringlogic.html#or). Then you choose an entity and which of its fields the query should return. After that, conditions or sub-groups can be added. -In order to add a condition you select a field, an operand based on the field data type and a value if the operand is not unary. The operands `In` and `Not In` will allow you to create inner query with conditions from different entity instead of providing a value. Once the condition is committed, a chip with the condition information appears. By clicking the chip, you have the options to modify it or add another condition or group right after it. +In order to add a condition you select a field, an operand based on the field data type and a value if the operand is not unary. The operands `In` and `Not In` will allow you to create an inner query with conditions for a different entity instead of simply providing a value. Once the condition is committed, a chip with the condition information appears. By clicking the chip, you have the options to modify it or add another condition or group right after it. -If you select more than one condition chip, a context menu appears with options to create a group or delete the queries. If you choose to create a group with the selected conditions, the newly created group will appear where the topmost selected condition was placed. +If you select more than one condition chip, a context menu appears with options to group or delete the current selection. If you choose to create a group with the selected conditions, the newly created group will appear where the topmost selected condition was placed. In order to select a group, you can also click on its vertical line, which is colored based on the linking condition ([`AND`]({environment:angularApiUrl}/enums/filteringlogic.html#and) or [`OR`]({environment:angularApiUrl}/enums/filteringlogic.html#or)). If a single group is selected, you get a context menu with options to change its logic, ungroup or delete it. -Since every condition is related to a specific field from a particular entity changing the entity will lead to resetting all present conditions and groups. When selecting a new entity a confirmation dialog will be shown unless the [`showEntityChangeDialog`]({environment:angularApiUrl}/classes/igxquerybuildercomponent.html#showEntityChangeDialog) input property is set to false. +Since every condition is related to a specific field from a particular entity changing the entity will lead to resetting all preset conditions and groups. When selecting a new entity a confirmation dialog will be shown, unless the [`showEntityChangeDialog`]({environment:angularApiUrl}/classes/igxquerybuildercomponent.html#showEntityChangeDialog) input property is set to false. You can start using the component by setting the [`entities`]({environment:angularApiUrl}/classes/igxquerybuildercomponent.html#entities) property to an array describing the entity name and an array of its fields, where each field is defined by its name and data type. Once a field is selected it will automatically assign the corresponding operands based on the data type. The Query Builder has the [`expressionTree`]({environment:angularApiUrl}/classes/igxquerybuildercomponent.html#expressionTree) input property. You could use it to set an initial state of the control and access the user-specified filtering logic. @@ -151,11 +151,11 @@ The `expressionTree` is a two-way bindable property which means a corresponding ## Templating -The Ignite UI for Angular Query Builder Component allows defining templates for header and search value using the following predefined reference names: +The Ignite UI for Angular Query Builder Component allows defining templates for the component's header and the search value using the following predefined reference names: ### Header -Passing content inside of the `igx-query-builder-header` allows templating the query builder header. The [`IgxQueryBuilderHeaderComponent`]({environment:angularApiUrl}/classes/igxquerybuilderheadercomponent.html) component provides a way to hide the legend by setting the [`showLegend`]({environment:angularApiUrl}/classes/igxquerybuilderheadercomponent.html#showLegend) input property is set to false. +Passing content inside of the `igx-query-builder-header` allows templating the query builder header. The [`IgxQueryBuilderHeaderComponent`]({environment:angularApiUrl}/classes/igxquerybuilderheadercomponent.html) provides a way to hide the legend by setting the [`showLegend`]({environment:angularApiUrl}/classes/igxquerybuilderheadercomponent.html#showLegend) input property to false. The code snippet below illustrates how to do this: @@ -169,7 +169,7 @@ Passing content inside of the `igx-query-builder-header` allows templating the q ### Search value -The search value of a condition can be templated using the [`igxQueryBuilderSearchValue`]({environment:angularApiUrl}/classes/igxquerybuildersearchvaluetemplatedirective.html) directive, applied to a `` inside of the `igx-query-builder`'s body: +The search value of a condition can be templated using the [`igxQueryBuilderSearchValue`]({environment:angularApiUrl}/classes/igxquerybuildersearchvaluetemplatedirective.html) directive, applied to an `` inside of the `igx-query-builder`'s body: ```html From bb06e8843a77ee82d93daa1a010a70dc7838f3d5 Mon Sep 17 00:00:00 2001 From: igdmdimitrov <49060557+igdmdimitrov@users.noreply.github.com> Date: Tue, 1 Oct 2024 10:35:06 +0300 Subject: [PATCH 3/5] Update en/components/query-builder.md Co-authored-by: Mike Cherkasov --- en/components/query-builder.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/components/query-builder.md b/en/components/query-builder.md index 6e16c7abb6..4f6729227d 100644 --- a/en/components/query-builder.md +++ b/en/components/query-builder.md @@ -88,7 +88,7 @@ Now that you have the Ignite UI for Angular Query Builder module or directives i ## Using the Angular Query Builder -If no expression tree is initially set, you start with creating a group of conditions linked with [`AND`]({environment:angularApiUrl}/enums/filteringlogic.html#and) or [`OR`]({environment:angularApiUrl}/enums/filteringlogic.html#or). Then you choose an entity and which of its fields the query should return. After that, conditions or sub-groups can be added. +If no expression tree is initially set, you start by creating a group of conditions linked with [`AND`]({environment:angularApiUrl}/enums/filteringlogic.html#and) or [`OR`]({environment:angularApiUrl}/enums/filteringlogic.html#or). Then you choose an entity and which of its fields the query should return. After that, conditions or sub-groups can be added. In order to add a condition you select a field, an operand based on the field data type and a value if the operand is not unary. The operands `In` and `Not In` will allow you to create an inner query with conditions for a different entity instead of simply providing a value. Once the condition is committed, a chip with the condition information appears. By clicking the chip, you have the options to modify it or add another condition or group right after it. From 1c4617c4ba4c70c9dd6c61895f52b3fac2b0b738 Mon Sep 17 00:00:00 2001 From: igdmdimitrov Date: Thu, 3 Oct 2024 14:57:30 +0300 Subject: [PATCH 4/5] docs(query-builder): update template snippet and add sample --- en/components/query-builder.md | 44 ++++++++++++++++++++++++++++------ 1 file changed, 37 insertions(+), 7 deletions(-) diff --git a/en/components/query-builder.md b/en/components/query-builder.md index 4f6729227d..41429b4109 100644 --- a/en/components/query-builder.md +++ b/en/components/query-builder.md @@ -161,9 +161,8 @@ Passing content inside of the `igx-query-builder-header` allows templating the q ```html - - Build your query - + + ``` @@ -172,14 +171,45 @@ Passing content inside of the `igx-query-builder-header` allows templating the q The search value of a condition can be templated using the [`igxQueryBuilderSearchValue`]({environment:angularApiUrl}/classes/igxquerybuildersearchvaluetemplatedirective.html) directive, applied to an `` inside of the `igx-query-builder`'s body: ```html - - - + + + @if ( + selectedField?.field === 'Region' && + (selectedCondition === 'equals' || selectedCondition === 'doesNotEqual') + ){ + + + {{ reg.text }} + + + } + @else if ( + selectedField?.field === 'OrderStatus' && + (selectedCondition === 'equals' || selectedCondition === 'doesNotEqual') + ){ + + + {{stat.text}} + + + } + @else { + + } ``` - + + ## Styling From 0d608ab5b148c4c74b54cb45c3d7251dcb9c970c Mon Sep 17 00:00:00 2001 From: igdmdimitrov Date: Fri, 4 Oct 2024 15:33:35 +0300 Subject: [PATCH 5/5] docs(query-builder): add supporting text for example --- en/components/query-builder.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/en/components/query-builder.md b/en/components/query-builder.md index 41429b4109..c8de544ee9 100644 --- a/en/components/query-builder.md +++ b/en/components/query-builder.md @@ -206,6 +206,8 @@ The search value of a condition can be templated using the [`igxQueryBuilderSear ``` +We’ve created this Angular Query Builder example to show you the templating functionalities for the header and the search value of the Angular Query Builder component. +