Grid Interaction Directives

Grid Interaction Directives Specification

Revision History

1. Overview

Version	User	Date	Notes
0.1	Stamen Stoychev	May 13, 2020	Initial draft

Objectives

To allow the user to subscribe to DOM events on cells and rows (e.g. pointerover, click, focus, etc.) but receive component-related context for the element triggering the event instead of just DOM-related one.

2. User Stories

As an end-user:

Story 1:

As a developer:

Story 1: I want to be able show custom grid row UI on row hover and assign that UI context through the template
Story 2: I want to be able show custom grid cell UI on cell hover and assign that UI context through the template

Acceptance criteria

3. Functionality

3.1. End-User Experience

3.2. Developer Experience

There are two separate attribute directives that are available to the user - IgxCellInteractionDirective that provides events for cell interactions and IgxRowInteractionDirective that provides events for row interactions.

Both require the same type of input:

export interface IInteractionConfig = {
    start: Array<string>,
    end: Array<string>
}

Both start and end expect an array of events that correspond to what the user considers the beginning and the end of an interaction with the element type of his choice (cells or rows). For example, if the user requires the pointerenter event for the beginning of an interaction on rows and pointerleave as the end, he should use the following code to initialize the directive:

<igx-grid [igxRowInteraction]="{ start: ['pointerenter'], end: ['pointerleave'] }">
</igx-grid>

The directive does not check for event availability or if it makes sense as an event fired for the DOM element of choice. It delegates a handler to all specified events on the grid's body and attempts to recognize the original target as a grid cell or row. If it can't then the corresponding interaction event is not emitted.

NOTE: Events that do not propagate or that have their propagation stopped by other logic will result in integration events not emitting.

start and end have an additional purpose - to separate the outputs logically so that it is easier to handle them declaratively in the template. To finalize the example above, the user has two events to subscribe to:

<igx-grid
    [igxRowInteraction]="{ start: ['pointerenter'], end: ['pointerleave'] }"
    (onRowInteractionStart)="menu.show($event)"
    (onRowInteractionEnd)="menu.hide($event)">
</igx-grid>

Corresponding events are available for IgxCellInteractionDirective - onCellInteractionStart and onCellInteractionEnd.

The event argument context is different for the events provided by the two directives:

IgxCellInteractionDirective's arguments implement the CellType interface
IgxRowInteractionDirective's arguments implement the RowType interface

3.3. Globalization/Localization

Describe any special localization requirements such as the number of localizable strings, regional formats

3.4. User Interface

N/A

3.5. Navigation

N/A

3.6. API

Inputs

Name	Type	Default value	Valid values	Description
igxRowInteraction	IInteractionConfig	null	{ start: ['event1', 'event2'], end: ['event3', 'event4']}	Controls which events to subscribe to for emitting the interaction outputs for rows
igxCellInteraction	IInteractionConfig	null	{ start: ['event1', 'event2'], end: ['event3', 'event4']}	Controls which events to subscribe to for emitting the interaction outputs for cells

Outputs

Name	Description	Type
onCellInteractionStart	Emitted when a specified `start` DOM event is fired for a cell	`CellType`
onCellInteractionEnd	Emitted when a specified `end` DOM event is fired for a cell	`CellType`
onRowInteractionStart	Emitted when a specified `start` DOM event is fired for a row	`RowType`
onRowInteractionEnd	Emitted when a specified `end` DOM event is fired for a row	`RowType`