Advanced Filtering (In Progress)

Advanced Filter Dialog Specification

1. Revision History

Version	User	Date	Notes
0.1	Danail Marinov	Oct 5, 2018	Initial draft
0.2	Danail Marinov	Aug 1, 2019	Update
0.3	Danail Marinov	Aug 6, 2019	Display Density and Hands Off
0.4	Danail Marinov	Aug 21, 2019	Dragging the AF dialog
0.5	Danail Marinov	Sept 02, 2019	Min/Max Height
0.6	Danail Marinov	Oct 15, 2019	AF Button in the Toolbar - states

2. Overview

Advanced Filter Dialog provides means for creating and editing complex filtering logic. Through the Advanced Filtering (AF) can be created complex filters and group of filters holding operands. The set of operands depend on the type of the values in the column that filter is applied on. Advanced Filtering allows cross-column filtering across the grid.

3. User Stories

End User Stories

As an end user, I want to be able to create groups of filters (expression) that are applied on selected grid columns. I want to be able to add interactively group of filters having predefined logical operation (AND, OR).
As an end user, I want to be able to edit a filter condition: specifying column field, filtering operand and value for each filter. All this should be achieved interactively.
As an end user, I want to be able to choose the type of operand based on the grid column type.
As an end user, I want to be provided with a convenient end-user interface for creating and editing complex filtering expressions that contain multiple filters, spreading across and combining different data columns.
As an end user, I want to be able to interactively select the logical operation (AND, OR) that will define the connection between filters and filter expressions.
As an end user, I want to be able to add or remove filters interactively.
As an end user, I want to be able to add or remove group of filters interactively.
As an end user, I want to be able to group filters interactively.
As an end user, I want to be able to ungroup filters that have been grouped before.
As an end user, I want to be able to reorder filters and group of filters through drag and drop.
As an end user, I want to have always exposed the name of the column on which the filter is applied on, the name of the filter operand applied and the typed filter value.
As an end user, I want to have always exposed the logical operation (AND, OR) applied for group of filters.
As an end user, I want to be able to perform selection on condition and group of conditions.
As an end user, I want to be have exposed color code indication about the logical operation (AND, OR) applied for group of filters.
As an end user, I want to be be able to insert filter or group of filters after selected filter or group of filters.
As an end user, I want to be able to select multiple filter conditions.
As an end user, I want to have exposed contextual menu having meaningful actions when more than one filtering conditions are selected.
As an end user, I want to be able to trigger Advanced Filtering Dialog from the grid toolbar.
As an end user, I want to be able to clear all created filters within the Advanced Filtering.
As an end user, I want to be able to apply all created filters within the Advanced Filtering.
As an end user, I want to be able to close the Advanced Filtering Dialog discarding the created filters through Cancel button.
As an end user, I want to be able to quickly remove a filter condition using a clear icon in the filter chip.
As an end user, I want to be able to drag and move AF dialog window along the application area.
As an end user, I want to be able to interact with the grid while AF dialog window opened.

Developer Stories

As a developer, I want to be able to open/close the Advanced Filter Dialog programmatically.
As a developer, I want to be able to define the initial state of the Advanced Filter Dialog expressions tree.
As a developer, I want to be able to clear the applied filtering expression programmatically.
As a developer, I want to be able to specify the operands applicable for a grid column corresponding to the type of data of that column.
As a developer I want to be able to programmatically set filtering conditions that override the default ones.
As a developer I want to have preset option for the type of filters that I can apply on data (numeric, string, boolean).
As a developer I want to create custom filtering conditions.
As a developer I want to be able to set display density for the Advanced Filtering.
As a developer I want to be able to host the advanced filtering dialog outside of the grid.

4. Functionality

User Interface

Design Hands-Off: https://cloud.indigo.design/share/jcvp2e8px0q4

Advanced Filtering can be triggered from the action icon placed in the grid Toolbar.

After triggering, the AF dialog pops up over the grid. The AF AF dialog window is draggable along the whole application area, not resizable and may exceed grid width. If, I, as an end user, click outside of the AF dialog, it will not be closed.

Initially, the AF dialog is empty and lets users create group of filter conditions connected with "And" or "Or".

Starting "And" or "Or" group of conditions will show on left a vertical line that indicates the "And" or "Or" condition between the filters through a color code. In order to have valid filter condition, I, as an end user, have to define on which column to apply the filter and what is the operand, as well as to type value. Typing value completes creating valid filter conditions, so that I, as an end user, will be able to confirm filter creation through the Confirmation action icon after the third input (the Value input). After completing the filter, the action buttons below the filtering condition would go from Disabled to Inactive mode.

After completing a filter condition, I, as an end user, have to confirm it which makes the filter condition go from Edit in View mode. While Edit mode of the filter is represented as a set of three inputs (for Column, Operand, Value), View mode is shown through a complex chip component that is holding the properties about the filter that has been defined - selected column, operand, value. After having at least one completed filter condition, the action buttons in the bottom the AF dialog (Clear, Cancel, Apply) goes from Disabled to Inactive.

I, as an end user, may add nested group of conditions instead of single filter conditions. Then, I, as an end user, have to select whether to add "And" or "Or" group. This action creates nested group with indent and color line on its left that indicates the connection between the filters in it (connected with "And" or "Or" condition). In addition, the length of that line marks the included filter conditions. End Group action ends the current group of conditions. Group of conditions has to have at least two single filter conditions.

If the last created condition is nested in a group of conditions, then additional button "End Group" is displayed. It indicates ending of the current group of filters and moving one level down.

Example:

If, I, as an end user, select a filter chip, it goes from view to selected state. If the filter chip is NOT the last one in the filter tree, then Edit and Insert/Add Filter action icons are displayed. If the filter chip is the last one in the filter tree, then only Edit action icon is displayed.

Selecting Edit turns the filter into Edit Mode and the current filter data is displayed within the inputs.

Mouseover on filter chip displays Edit and Insert/Add Filter action icons, if the filter chip is NOT the last one in the filter tree. If the filter chip is the last one in the filter tree, then only Edit action icon is displayed.

If selected, Insert/Add Filter action inserts a row below the filter containing actions to insert single filter, "And" group or "Or" group. These actions can be hidden by the close Action icon.

If, I, as an end user, select more than one filters, then contextual menu appears with options to create "And" or "Or" group of filters with the selected filters or to delete all of them. If, I, as an end user, create a new group from the selected filters, then it is placed on the level of the first selected filter. If, I as an end user, close the contextual menu (through the Close button or ESC), then all selected filters go from selected to idle state.

Single filters can be grouped with other filters or groups of filters from different levels.

When grouping filters, the newly created group appears on the level of the upper filter that has been previously selected.

I, as an end user, can perform selection of a whole group of filters by selecting the color line of that filter group. Then contextual menu appears with available actions to change the "And"/"Or" condition, Ungroup the filters in the group or to Delete the whole group of conditions. The contextual menu is top aligned with the first of the selected filters. When a group of filters is selected, all nested filters get selected, too. If, I as an end user, close the contextual menu (through the Close button or ESC), then the selected group of filters goes from selected to idle state.

As an end user, I can perform selection of more than one group of filters. Then, all nested within the group filters are getting selected.

Buttons overlapping - despite it is an edge case, if happens that Add Group/Buttons actions overlap with the contextual menu when having selection of more than one condition, priority is given to the contextual menu.

Advanced Filtering Button in the Toolbar - States The button placed in the Grid Toolbar, used for triggering the Advanced Filtering has three states:

Idle - when the Advanced Filtering Dialog is not triggered and there are no applied filters
Active - when the Advanced Filtering Dialog is triggered
Applied Filters - when there applied filters within the Advanced Filtering Dialog

In terms of styling, the Idle and Active states are visually identical:

Dragging the AF dialog - AF dialog can be dragged within the whole application area, it is not restricted only within the grid area. Dragging is performed through on-click on the whole header area of the AF dialog.
Display Density

Comfortable: The AF dialog MIN height is 324px, based on the height of a dialog with 3 filters and a set of buttons. The AF dialog MAX height is 564px and if its content has to go beyond, a vertical scroll appears.

Cosy: The AF dialog MIN height is 260px, based on the height of a dialog with 3 filters and a set of buttons. The AF dialog MAX height is 440px and if its content has to go beyond, a vertical scroll appears.

Compact: The AF dialog MIN height is 222px, based on the height of a dialog with 3 filters and a set of buttons. The AF dialog MAX height is 384px and if its content has to go beyond, a vertical scroll appears.

Globalization/Localization

Navigation

API

Inputs

Name	Description	Type
allowAdvancedFiltering	Gets/sets a value indicating whether the advanced filtering is enabled	boolean
advancedFilteringExpressionsTree	Gets/sets the state of the advanced filtering	IFilteringExpressionsTree

Methods

Name	Description	Return type	Parameters
openAdvancedFilteringDialog	Opens the advanced filtering dialog
closeAdvancedFilteringDialog	Closes the advanced filtering dialog		applyChanges: boolean

Outputs

Name	Description	Cancelable	Arguments

7. Test Scenarios

Automation

Initial view

Should show/hide 'Adv. Filtering' button in toolbar based on allowAdvancedFiltering input.
Should open Advanced Filtering dialog when the 'Adv. Filtering' button is clicked.
Should open Advanced Filtering dialog when the openAdvancedFilteringDialog method is called.
Should close Advanced Filtering dialog when the closeAdvancedFilteringDialog method is called by respecting the provided applyChanges parameter.
Should display a message, 'and' and 'or' buttons and no groups in AF dialog when grid is not filtered.
'And' and 'Or' groups should have correct operator lines.

Interaction

Should add a new 'And' group when clicking the respective 'add and' button.
Should add a new 'Or' group when clicking the respective 'add or' button.
Newly added group should have disabled adding buttons and disabled 'end group' button.
Newly added group should have a single empty condition, a disabled 'commit' button and an enabled 'cancel' button.
Newly added group should be discarded when clicking the 'cancel' button of its initial condition.
Newly added condition should be empty and should have disabled adding buttons.
Newly added condition should have a disabled 'commit' button and an enabled 'cancel' button.
Should scroll the adding buttons into view when the add icon of a chip is clicked.
Should scroll the newly added expression into view when the respective add button is clicked.
Should scroll to the expression when entering its edit mode.
Should keep the context menu in view when scrolling the expressions container.
Each condition field should be enabled only if the field on its left is populated. (except for unary operators)
First condition field/dropdown should contain only filterable columns.
Second condition field/dropdown should contain operators based on the column's datatype.
Third condition field should open calendar when the column is of 'date' type.
Third condition field should contain editable text when the column is of non 'date' type.
Condition should have enabled 'commit' button only when all fields are populated.
Should commit currently edited condition when the 'commit' button is clicked.
Should correctly filter by string, number, date and boolean columns through UI.
Should not commit and close currently edited condition when the 'close' button is clicked.
Should close the condition that is currently in edit mode when the 'close' button is clicked.
Should display the 'adding' buttons and the 'cancel' button when trying to add a new condition/group to existing group.
Should hide the 'adding' buttons and the 'cancel' button when the 'cancel' button is clicked.
Should add a new condition or a group to existing group by using add buttons.
Should remove a condition from an existing group by using delete icon of respective chip.
Should end a group when clicking its 'end group' button.
Should select/unselect a condition when its respective chip is clicked.
Clicking/Hovering a single condition should display its 'edit' button and the '+' button for adding more conditions/groups to the group.
Selecting multiple conditions should display the (create group)/(delete filters) context menu.
Unselecting conditions until one selected remains should hide the (create group)/(delete filters) context menu.
When a condition is selected, clicking its 'edit' button should put it in edit mode.
Double-clicking a condition should put it in edit mode.
Should create an 'and'/'or' group from multiple selected conditions when respective context menu button is clicked.
Should delete all selected conditions when the 'delete filters' option from context menu is clicked.
Should select/deselect all child conditions and groups when clicking a group's operator line.
Should show/hide group's context menu when clicking its operator line.
Should discard added group when clicking its operator line without having a single expression.
Should change the group's operator when using its context menu buttons.
Ungroup button of the root group's context menu should be disabled.
Should ungroup the group's children and append them to next parent group when click 'ungroup' from context menu.
Should remove a group from the expr tree when click 'delete' from context menu.
Group with a single condition cannot be ended. ('end' button is disabled)
Should filter the grid correctly when adding conditions and groups through AF dialog.
Should clear all conditions and groups when the 'clear filter' button is clicked.
Should apply all conditions and groups and close the AF dialog when the 'apply' button is clicked.
Should keep edited conditions and groups inside AF dialog when applying and opening it again.
Should not keep changes over edited conditions and groups inside AF dialog when canceling and opening it again.
Should apply display density of the AF dialog correctly when changing the displayDensity of the grid.
Should not close the AF dialog when clicking outside of it.
Should emit the onFilteringDone event when applying filters.

Keyboard Navigation/Interaction

Should navigate with Tab/Shift+Tab through chips, their respective delete icons and the operator lines.
Should navigate with Tab/Shift+Tab through chips' 'edit', 'cancel' and 'adding' buttons.
Should navigate with Tab/Shift+Tab through the buttons and fields of a condition in edit mode.
Should put a chip in edit mode when pressing 'Enter'.
Should remove a chip in when pressing 'Enter' on its 'remove' icon.
Should add a condition/group pressing 'Enter' on its respective 'add' button.
Should hide the 'adding' buttons and the 'cancel' button when pressing 'Enter' on its 'cancel' button.
Should select/deselect a chip when pressing 'Enter' on it.
Should select/deselect all child conditions and groups when pressing 'Enter' on a group's operator line.
Should open group's context menu when pressing 'Enter' on its operator line.
Should clear all conditions and groups when pressing 'Enter' on the 'clear filter' button.
Should apply all conditions and groups and close the AF dialog when pressing 'Enter' on the 'apply' button.
Should close the AF dialog when pressing 'Enter' on the 'cancel' button.

API <-> UI updates

Applying filter through the API should correctly update the AF dialog.
Applying filter through the AF dialog should correctly update the API.
Clearing filter through the API should clear the AF dialog's filters.
Clearing filter through the AF dialog should clear the API's filters.

Localization

Should correctly localize all Advanced Filtering dialog related strings.

Manual

Should drag the AF dialog anywhere in the application by using 'press and hold' of its header area.
Should be able to fully interact with the grid while the dialog is opened.