AdapTable Rx Upgrade Guide

AdapTable Rx (Version 9) was released on 14 July 2021.

important

It is named Rx (short for Reactive Extensions) as one of the main new features are Observable and Aggregation Expressions which use the Reactive Extensions (Rx) paradigm.

AdapTable Rx is a major release containing many improvements both to core functionality and to how AdapTable is accessed by developers.

caution

AdapTable Rx includes some breaking changes which are listed below

Summary

The changes in AdapTable Rx can be summarised as follows (full details are provided below):

  • Modules (previously called Functions) have been consolidated e.g. Flashing Cell, Updated Row and Cell Validation have been merged into Alerts, and Gradient Column and Percent Bar into Format Column

  • A few Modules have received major enhancements, notably Alerts, Format Column, Conditional Style, Export and FreeText Column

  • Some functionality that was previously provided in Predefined Config has been ported over to Adaptable Options e.g. Entitlements, Menus, Action Columns

    note

    Predefined Config now contains only objects which can change during Application run-time

    Adaptable Options contains behaviour and functionality that will never change post-creation

  • Many new Events have been added to improve the ability to react to changes in Adaptable and AG Grid

    tip

    These include the new Adaptable State Changed Event which replaces - and improves on - Audit Log

  • The User Functions section has been removed, as all the functionality it contained is now available in Adaptable Options

  • The Adaptable Parser has had significant improvements, including:

  • Team Sharing has been enhanced:

    • Offers Active Sharing where Shared Entities remain linked between users
    • When a Shared Entity referencse other objects, these too will be (automatically) shared
  • Instantiating the Angular Wrapper has been simplified and improved

  • Signficant enhancements to key UI objects to ensure a better usability experience, including:

    • Improvements to the Wizard and new common, re-usable UI objects (e.g.
    • Cell Editors - Numeric Editor / Date Picker provided automatically when editing relevant cells
    • Read-Only Cells so that editability can be set at individual cell level
    • Use of Infinite Table - a 3rd party React Grid - for rendering tabular data inside AdapTable
  • 2 Enhancements to the Finance Plugin:

  • Auto Generated Primary Keys are now available - but only to be used if absolutely necessary

Modules

Core functionality in AdapTable remains divided into discrete sets called Modules (previously called 'Functions').

As before, these can have Entitlements set, in order to manage user accessibility.

Modules Consolidation

As part of the move from 'Functions' to 'Modules', some Modules have significantly new functionality - these are listed below.

Other Modules have been merged. These include:

Old ModuleMerged Into
Cell ValidationAlerts
Flashing CellsAlerts
Updated RowsAlerts
Gradient ColumnFormat Column
Percent BarsFormat Column

Alert

Alerts have received a number of major enhancements in AdapTable Rx including:

  • Alerts can be triggered by Observable and Aggregation Expressions
  • Flashing Cells and Updated Rows have been merged into Alerts as Flashing Alerts
  • Cell Validation has been moved into Alerts as Prevent Edit Alerts
  • Improved Alert Wizard makes it easier to create and manage Alert Definitions
  • An Adaptable Form can be displayed in an Alert Notification
  • Alert Notification can contain Adaptable Buttons that perform actions when clicked
  • Actions can be provided by Adaptable (e.g. undo, highlight cell, jump to cell) or by user

Conditional Style

Conditional Style has these enhancements:

  • A new Rule property to determine whether the Style should be displayed. It consists of either:
  • Improved Wizard so creating Conditional Styles is much easier

Dashboard

The Dashboard has received some modifications:

Tool Panels

The Tool Panel has received some minor changes:

caution

These changes to Tool Panels are contained in version 9.0.5 published a few days after the main release

Export

Export has received some minor improvements:

  • Visual Data report has been renamed Current Data; it exports whatever data is in the Grid (ie. filtered)

  • The new Visual Data report will export all data in the grid with full styling and grouping

    note

    This report can only be exported to Excel

  • Export Destinations now appear in a separate dropdown, allowing you to select a 'default' destination

  • Devs are able to stipulate in Export Options whether to export the formatted value or the raw data value - either for whole grid or by Column data type (with special provision for dates)

  • A timestamp can be appended to the exported file for easy identification purposes

Format Column

Format Column has many new features including:

Free Text Column

Free Text Columns now have a DataType property.

Possible values are 'String' (the default), 'Number', 'Boolean' or 'Date'

tip

AdapTable provides a cell editor that is suitable for the data type (e.g. it's Date Picker for 'Date' columns)

Shortcut

The Shortcut module now only operates on numeric columns.

note

The previous date-input functionality is available via the datepickerButtons property in the Date Picker

Parser Enhancements

One of the most exciting new features in AdapTable Rx is to Queries and Expressions.

As the name implices, in AdapTable Rx the parser is now able to run reactive-type Expressions, which provide users with a very powerful range of querying functionality.

note

Reactive Expressions can be written at design-time or run-time, either by hand or using the Expression Editor

There are 2 types of Reactive Expressions: Observable and Aggregation.

Observable Expressions

Observable Expressions react to changes (or lack of changes) in data, either per row or for whole grid.

This allows you to create expressions (and show alerts) for questions like:

  • has this cell changed 3 times?
  • is this the highest value its been today?
  • has this not changed in the last 3 hours?

Aggregation Expressions

Aggregation Expressions provide a way to sum numeric columns and then perform queries against them.

For instance you can run a query (with an Alert) to say tell me if the total for the PnL column exceeds 50M in rows where Status is Active.

Parser Functions

The Adaptable Parser continually offers additional functions - in response to new functionality and user requests.

Some of the new functions in AdapTable Rx include:

  • QUERY - enables you to provide a Named Query as an argument in an Expression
  • WHERE - used in Observable and Aggregtion Expressions to limit the Data Set used
  • String manipulation functions - LEN, UPPER, LOWER, CONCAT

Team Sharing

  • Team Sharing has some useful new features notably:

    • Active Sharing - Shared Entities can be linked so that changes made by one are shared among all
    • Referenced Sharing - If a Shared Entity references other objects, all references are also shared

Adaptable Options

A key focus is AdapTable Rx is to move settings that will only be configured at design-time into Adaptable Options, leaving Predefined Config containing just objects that can change at run-time.

To this end a number of new sections have been added, a few removed, and some have important new properties.

New Options

The new and renamed Adaptable Options sections are:

SectionNotes
Alert OptionsManages Alerts Notification settings and Flashing Alerts default properties
Dashboard OptionsReplaces properties from Dashboard section in Predefined Config
Entitlements OptionsReplaces Entitlements section in Predefined Config with identical functionality
Menu OptionsReplaces Menu-related section in Predefined Config with improved functionality
System Status OptionsOption for managing System Status Module
Search OptionsNow contains all properties from the previously separate Query and Filter Options
Tool Panel OptionsReplaces properties from Tool Panel section in Predefined Config

Merged / Removed Options

These sections in Adaptable Options are now no longer required or have been merged into a common section:

SectionNotes
Audit OptionsAudit Log is replaced by the superior Adaptable State Changed Event
Filter OptionsMerged into Search Options - all functionality remains the same
Query OptionsMerged into Search Options - all functionality remains the same
Framework ComponentsReplaced by Custom Toolbars in Dashboard Options

Updated Options

Some Adaptable Options sections have important new properties that have been moved from Predefined Config. These include:

Options SectionPropertyPrevious Predefined Config Section
ExportcustomDestinationsExport
ExportcustomReportsExport
GeneralcellSummaryOperationsCellSummary
GeneralcolumnSortComparersCustom Sort
GeneralcurrentCalendarCalendar
User InterfaceeditLookUpItemsUser Interface
User InterfacepermittedValuesUser Interface
User InterfaceactionColumnsAction Column
note

Action Columns now wrap an Adaptable Button and have been much simplified

Predefined Config

As stated above some sections in Predefined Config have been removed for 2 reasons:

  • Some sections which never change at run-time have been merged into Adaptable Options
  • Some sections have been consolidated to reduce complexity and improve the user experience

Removed Config Sections

The full list of sections removed from Predefined Config is:

SectionWhy removed
Action ColumnNow set in User Interface Options
Bulk UpdateBulkUpdateValue property now managed in Internal State
CalendarNow set in General Options
Cell SummaryNow set in General Options
EntitlementsNow set in Entitlements Options
Flashing CellMerged into Alerts Module
Gradient ColumnMerged into Format Column Module
Percent BarMerged into Format Column Module
Smart EditSmartEditValue property now managed in Internal State
System StatusNow set in System Status Options
Updated RowMerged into Alerts Module
User InterfacePrimarily ported to User Interface Options

Updated Config Properties

Some properties in Predefined Config sections have been moved:

SectionMoved To
Filter / SystemFiltersSearch Options

Automated Updates

AdapTable automatically updates those sections of Predefined Config likely to have been created or edited at run-time to be compatible with the new objects in AdapTable Rx. These include:

Old ConfigHow Updated by AdapTable
Conditional StyleMerges 'Predicate' & 'Expression' properties into Conditional Style Rule property
Calculated ColumnChanges 'ColumnExpression' to Calculated Column ScalarExpression property
ExportChanges 'Expression' into new Report BooleanExpression property
Percent BarUpdates them into Format Column GradientStyle objects
Gradient ColumnUpdates them into Format Column PercentBar objects
AlertUpdates old Alerts to use new Alert objects
Flashing CellCreates new Flashing Alerts objects
Updated RowCreates new Flashing Alerts objects

Events

Events have been improved significantly in AdapTable Rx both in terms of syntax and use cases supported.

Event Syntax

The previous FDC3-type messaging has been removed, along with the 'xxxArgs' class for each Event.

In its place there is a single xxxInfo class fired for each Event containing all relevant data.

note

The method of subscribing to an event (via the Event Api) remains unchanged

Event Consolidation

Many Events have been added (or renamed) while others, which are now longer relevent, have been removed:

New Events

The new and renamed Events are:

EventWhen Fired
Adaptable State ChangedAny state changes in Adaptable: Replaces Audit Log
Cell ChangedAny cell in AdapTable is updated (either by user or ticking data)
Dashboard ChangedAny change is made to Dashboard toolbars, visibility, or mode
Flashing Alert Fireda Flashing Alert is triggered
Grid Data ChangedThe rows collection is changed in the Grid's Data Source
Layout ChangedA Layout changes (previously 'LayoutUpdated')
System Status Message DisplayedA System Status message is shown
Team Shared Entity ChangedAn Active Shared Entity in Team Sharing has changed

Removed Events

The removed Events are:

EventWhy Removed
Action Column ClickedAction Column now uses Adaptable Buttons which has an `onClick' function
Layout UpdatedReplaced by new Layout Changed Event
Dashboard Button ClickedDashboard now uses Adaptable Buttons which has an `onClick' function
Toolbar Button ClickedToolbars now contain Adaptable Buttons which has an `onClick' function
Toolbar Visibility ChangedMerged into Dashboard Changed Event
Validation FailedMerged into Alert Fired Event

State Changed Event

Perhaps the most significant new Event is the Adaptable State Changed Event.

This fires whenever any State changes in Adaptable, and provides full details of the change, specifies the action which triggered the change and contains 'before and after' state objects.

note

This event replaces - and vastly improves on - Audit Log which has been removed

This allows users to specify which changes to listen to, and to get full details of everything that has happened in the grid, whether user actions, cell edits, ticking data changes etc.

tip

It is trivial to subscribe to this event and stream relevant changes to a destination of your choice giving you full, comprehesive Audit capability

User Functions

One welcome consequence of the consolidation and refactorign of Modules (see above) is that the 'UserFunctions' section of Adaptable Options is no longer required.

note

This is a beneficial outcome as User Functions required splitting code messily betweeen Predefined Config and Adaptable Options

All the functionality previously in User Functions is now available elsewhere in AdapTable as follows:

Old User FunctionNotes
Action Column RenderAction Column uses standard Adaptable Buttons
Action Column Should RenderAction Column uses standard Adaptable Buttons
Alert ButtonAlert uses standard Adaptable Buttons
Cell Summary OperationCell Summaries are now provided in General Options
Custom Export DestinationExport Module now uses an Adaptable Form for Custom Destinations
Custom ReportExport Options has a customReports property that handles this
Custom Sort ComparerManaged by the columnSortComparers property in General Options
Entitlement LookUpEntitlements are now set in Entitlements Options
Get Column ValuesDistinct column values can now be provided in User Interface Options
User Menu Item ClickedMenu Options contains all functions used to manage user menu items
User Menu Item LabelMenu Options contains all functions used to manage user menu items
User Menu Item Show PredicateMenu Options contains all functions used to manage user menu items

Angular Wrapper

AdapTable Rx simplifies the instantiation of AdapTable when using the Angular Wrapper.

Instead of 2 components being required, just the standard ag-grid-angular component should be provided.

important

This should be supplied with the adaptableOptions property which extends the grid with AdapTable features

warning

AdapTable Rx requires the use of Angular 10 or higher.

UI Improvements

The User Interface in Adaptable has been simplified in AdapTable Rx together with more common components.

Adaptable Form

There is a new Adaptable Form which is dynamically generated when required.

It can contain fields (of various types - e.g. dropdown, numeric editor, checkbox etc.), default values, buttons, descriptions and full validation.

The Adaptable Form is currently used in these Modules (with more to follow in the coming months):

  • Custom Destination in Export displays a form allowing additional information to be provided
  • Alert can contain a Form with Buttons to allow edits to be overriden or undone

Adaptable Buttons

The many previous ad-hoc button implementations in Adaptable have been consolidated to use a new, more powerful Adaptable Button object.

It is used in these Modules and Options:

Buttons contain 5 functions to be provided by users and invoked by AdapTable when required:

  • onClick - what happens when the Button is clicked
  • hidden - whether or not to display the Button
  • disabled - whether or not the Button is enabled
  • buttonStyle - what style to give the Button (can alternatively be a hard-coded value)
  • label - caption to display in the Button (can alternatively be a hard-coded value)

Wizard

The standard Wizard used in many Module Popups has had a makeover with a number of enhancements:

  • now runs vertically (rather than horizontally), making better use of screen estate
  • allows you to navigate between steps using the mouse
  • provides context-sensitive instructions
  • explains in each step what is required to enable the wizard to move to the next step or finish
  • contains an intuitive summary screen with buttons to edit each section of the object
note

So far we have updated Alert, Conditional Style, Query, Export, Format Column, FreeText Column and Custom Sort Modules to use the new Wizard with others to follow in coming months

important

This is Work In Progress so any feedback on how the Wizard can be futher improved is appreciated

Cell Editors

AdapTable now provides 2 cell editors which will be automatically used when the cell is in edit mode:

note

If a cell editor is provided in Grid Options then, naturally, that will be used and not the AdapTable one

  • Numeric Editor - only allows numbers and has arrows to move up and down
  • Date Picker - a Date Picker providing a very full list of features which is heavily stylable

Read-Only Cells

Editability can now be defined at the individual cell level via user-provided functions.

tip

This new functionality combines nicely with the 2 new editableCellStyle and readOnlyCellStyle properties in User Interface Options

Finance Plugin Columns

The Finance Plugin has 2 new Column types in AdapTable Rx which can be provided at Design Time if required:

Weighted Average Columns

Weighted Average Columns will perform a Weighted Average aggregation - both when the Row is grouped or in Pivot Mode

note

It requires that the user provides a 2nd column which will also be used to perform the aggregation calculation

FDC3 Instrument Columns

Instrument Columns show a 'Broadcast Instrument' Menu Item which, when clicked, will broadcast an FDC3 Instrument message.