Complex Filter Configuration: Tips and Techniques
Author:
Yulia Andreyanova
Changed on:
9 Apr 2025
Key Points
- This guide offers step-by-step instructions for setting up and customizing the Complex Filter component to achieve precise and efficient data filtering.
- Learn how to set up data sources, use GraphQL queries, and display results easily with card components like Standard Card and Product Card.
- Discover how to customize fields by changing their types, adjusting the field order, and removing unnecessary ones to make the filter simple and effective for your needs.
Prerequisites
Steps
Add the Component Skeleton to the Manifest
Begin by defining the structure for the `fc.field.filterComplex` component in the . Include properties for filters, queries, and configurations:
1{
2 "component": "fc.field.filterComplex",
3 "label": "Product filter",
4 "extensions": {
5 "filtersSource": "",
6 "query": "",
7 "variables": {},
8 "overrides": {},
9 "searchItemConfig": {},
10 "chipItemConfig": {},
11 "onChangeValues": {},
12 "mode": "single",
13 "exclude": []
14 }
15}Configure Data Source
Define the `query` and `variables` to retrieve the desired data. This enables the component to fetch entities dynamically.
1"extensions": {
2 "query": parse(gql`query products($products_ref: [String!], $products_name: [String!], $productCatalogue: String!) {
3 variant: variantProducts (ref: $products_ref, name: $products_name, catalogue: {ref: $productCatalogue}) {
4 edges {
5 node { ref name attributes { name value } }
6 }
7 }
8 standard: standardProducts (ref: $products_ref, name: $products_name, catalogue: {ref: $productCatalogue}) {
9 edges {
10 node { ref name attributes { name value } }
11 }
12 }
13 }`),
14 "variables": {
15 "products_first": 100,
16 "productCatalogue": "{{productCatalogue}}"
17 },
18}Customize Fields
To refine the displayed data, unwanted fields can be excluded by adding their names to the `exclude` property. The `overrides` property can be used to customize field types, labels, and .
1"extensions": {
2 "overrides": {
3 "name": {
4 "sortPrefix": 1
5 },
6 },
7 "exclude": [
8 "createdon",
9 "updatedon",
10 "type",
11 "status",
12 "gtin",
13 "summary",
14 "productcatalogue"
15 ]
16}Configure Selection Behavior
Control how users interact with the filter using the `mode` and `selectionLimit` properties.
1{
2 "extensions": {
3 "mode": "multiple",
4 "selectionLimit": 5
5 }
6}The `mode` property how many items a user can select. When set to `single`, only one item can be chosen, and the selected value is returned as a string. When set to `multiple` (the default), users can select multiple items, and the output is returned as an array. The `selectionLimit` property, which only applies when `mode` is `multiple`, restricts the number of selectable items to a specified maximum (e.g., 5 means users can choose up to five items).
Set Modal Size and Layout Columns
Use `modalDimension` and `displayColumns` to configure the filter modal layout.
`modalDimension`: This controls the modal size. It accepts "small" (the default) or "medium." This is useful when you expect longer labels or want more visual breathing room.`displayColumns`: This setting defines the number of columns for the field layout. Set it to`2`or`3`to group more fields horizontally, making better use of screen space.
1"extensions": {
2 "modalDimension": "medium",
3 "displayColumns": 2
4}
Display Search Results
Choose between the fc.card.product or fc.card.attribute components to visualize search results. Configure how results are presented using the `searchItemConfig` property.
1"extensions": {
2 "searchItemConfig": {
3 "component": "fc.card.product",
4 "props": {
5 "title": "{{node.name}}",
6 "cardImage": {
7 "imageUrl": "{{node.attributes.byName.imageUrl}}"
8 },
9 "attributes": [
10 {
11 "value": "{{node.ref}}"
12 }
13 ]
14 }
15 },
16}Configure Selected Items Display
Use the `chipItemConfig` property to define how selected items are displayed in the filter’s modal window. This configuration can include additional query and variable properties to specify a query for preselected items. For instance, the filter panel might supply a list of references already selected without opening the complex filter. If these properties are not defined, the main query will be used by default.
1"extensions": {
2 "chipItemConfig": {
3 "label": "{{node.name}}",
4 "query": parse(gql`query products($products_ref: [String!], $products_name: [String!]) {
5 variant: variantProducts (ref: $products_ref, name: $products_name) {
6 edges { node { ref name }}
7 }
8 standard: standardProducts (ref: $products_ref, name: $products_name) {
9 edges { node { ref name } }
10 }
11 }`),
12 "variables": {
13 "products_first": 100,
14 },
15 },
16}Handle Selected Values
After items are selected and the modal window is closed, the chosen values must appear in the main input field. Use the `onChangeValues` property to achieve this.
The `onChangeValues` property determines how selected values are displayed in the input field and specifies their mapping to query variables. This configuration ensures a seamless transition between the filter’s modal window and the main input, keeping the interface user-friendly and functional.
1"extensions": {
2 "onChangeValues": {
3 "value": "node.ref",
4 "variableName": 'products_ref',
5 "visibleItemsThreshold",: 3
6 },
7}Full Configuration Example
Below is a comprehensive example of the fully configured `fc.field.filterComplex` component:
1"productRef": {
2 "component": "fc.field.filterComplex",
3 "label": "Product filter",
4 "extensions": {
5 "query": parse(gql`query products($products_ref: [String!], $products_name: [String!], $productCatalogue: String!) {
6 variant: variantProducts (ref: $products_ref, name: $products_name, catalogue: {ref: $productCatalogue}) {
7 edges {
8 node {
9 ref
10 name
11 attributes {
12 name
13 value
14 }
15 }
16 }
17 }
18 standard: standardProducts (ref: $products_ref, name: $products_name, catalogue: {ref: $productCatalogue}) {
19 edges {
20 node {
21 ref
22 name
23 attributes {
24 name
25 value
26 }
27 }
28 }
29 }
30 }`),
31 "variables": {
32 "products_first": 100,
33 "productCatalogue": "{{productCatalogue}}"
34 },
35 "searchItemConfig": {
36 "component": "fc.card.product",
37 "props": {
38 "title": "{{node.name}}",
39 "cardImage": {
40 "imageUrl": "{{node.attributes.byName.imageUrl}}"
41 },
42 "attributes": [
43 {
44 "value": "{{node.ref}}"
45 }
46 ]
47 }
48 },
49 "chipItemConfig": {
50 "label": "{{node.name}}",
51 "query": parse(gql`query products($products_ref: [String!], $products_name: [String!]) {
52 variant: variantProducts (ref: $products_ref, name: $products_name) {
53 edges {
54 node {
55 ref
56 name
57 }
58 }
59 }
60 standard: standardProducts (ref: $products_ref, name: $products_name) {
61 edges {
62 node {
63 ref
64 name
65 }
66 }
67 }
68 }`),
69 "variables": {
70 "products_first": 100,
71 },
72 },
73 "onChangeValues": {
74 "value": "node.ref",
75 "variableName": 'products_ref'
76 },
77 "exclude": [
78 "createdon",
79 "updatedon",
80 "type",
81 "status",
82 "gtin",
83 "summary",
84 "productcatalogue"
85 ],
86 "overrides": {
87 "name": {
88 "sortPrefix": 1
89 }
90 }
91 }
92}
