Version 9 Upgrade Guide

Version 9 of AdapTable will be released on 28 June 2021.

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

warning

This Upgrade Guide is "Work In Progress" and will be continually updated as we get closer to the release

Summary

The changes in Version 9 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 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

    important

    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
    • Where Shared Entities reference other objects, these too will be 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
  • 2 Enhancements to the Finance Plugin:

Modules

Core functionality in AdapTable remains divided into discrete sets called Modules (previously '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 merged. These include:

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

Module Changes

Some Modules in version 9 of AdapTable support significantly enhanced functionality. These include:

Alerts

Alerts have received a number of major enhancements in Version 9 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 shown in an Alert with 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 Conditional Style Wizard so creating Condtional Styles is much easier

Format Column

Format Column has many new features including:

Free Text Column

Free Text Columns now have a DataType property:

  • Possible values are 'String', 'Number', 'Boolean' or 'Date'
  • The default value is 'String'
  • AdapTable provides a cell editor that is suitable for the data type (e.g. a date picker for 'Date' columns).

Plus Minus

Parser Enhancements

One of the most exciting new features in Adaptable V.9 is to Queries and Expressions.

The AdapTable parser is now able to run 2 reactive-type Expressions that provide users with a very powerful range of querying functionality.

note

Both of these Expression Types can be written at design-time or run-time, either by hand or using the Expression Editor

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.

Two of the new functions in Version 9 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

Team Sharing

  • Team Sharing has some useful new features notably:

    • Active Sharing - Shared Enitites 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 Version 9 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 in previously separate Query and Filter Options

Merged / Removed Options

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

SectionNotes
Audit OptionsAudit Log has been 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

Updated Options

Some Adaptable Options sections have important new properties that have been moved from elsewhere in AdapTable. These include:

Options SectionPropertyNotes
ExportcustomDestinationsPreviously in Export section of Predefined Config
ExportcustomReportsPreviously in Export section of Predefined Config
GeneralcellSummaryOperationsPreviously CellSummary section of Predefined Config
GeneralcolumnSortComparersPreviously in Custom Sort section of Predefined Config
GeneralcurrentCalendarPreviously Calendar section of Predefined Config
User InterfaceeditLookUpItemsMoved from User Interface State
User InterfacepermittedValuesMoved from User Interface State
User InterfaceactionColumnsPreviously Action Column section of Predefined Config
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
Bulk UpdateCurrent Bulk Update value 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 EditCurrent Smart Edit value now managed in Internal State
System StatusNow set in System Status Options
Updated RowMerged into Alerts Module
User InterfacePrimarily ported to User Interface Options
note

Predefined Config that references old modules will be automatically merged by AdapTable into the new Module when the application next loads so developers don't need to port any Config.

Events

Events have been improved significantly in v.9 both in terms of syntax and use cases

Event Syntax

The FDC3-type messaging has been removed as has the 'xxxArgs' class for each Event.

Instead there is a single 'xxxInfo' class fired for each Event containing all that is useful.

note

The method of subscribing to an event (via the Event Api) is 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 edited (either by user or ticking data)
Dashboard ChangedAny change is made to Dashboard toolbars, visibility, or mode
Flashing Alert Fireda Flashing Alert is triggered
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 UpdatedMerged into new Layout Changed Event
Dashboard Button ClickedDasbhoard now uses Adaptable Buttons which has an `onClick' function
Toolbar Button ClickedTooolbars 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 consequence of the consolidation of Modules and Adaptable Options (see above) is that Usser Functions are no longer required

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

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 needed to manage user menu items
User Menu Item LabelMenu Options contains all functions needed to manage user menu items
User Menu Item Show PredicateMenu Options contains all functions needed to manage user menu items

Angular Wrapper

Version 9 simplifies the instantiation of AdapTable when using the Angular Wrapper.

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

This should be supplied with the adaptableOptions property which will extend the grid with the AdapTable features.

warning

Version 9 requires the use of Angular 10 or higher.

UI Improvements

The User Interface in Adaptable has been simplified in Version 9 together with more common components.

Adaptable Form

We have created a new Adaptable Form which is dynamically generated when required.

This is now used in these places in AdapTable (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

Buttons are used in many places in AdapTable so these have all been consolidated to use a new Adaptable Button object.

This replaces many of the previous ad-hoc button implementations and is used in these Modules and Options:

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

  • onClick - what happens when the Button is clicked
  • shouldRender - whether or not to display the Button
  • buttonStyle - what style to give the Button

Wizard

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

  • now runs verticially rather than horizontally better using screen estate
  • allows you to navigate between steps using the mouse
  • shows you why the wizard cannot move to next step or finish
  • contains a summary screen with buttons to edit each section of the object
note

So far we have updated Alert, Conditional Style 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 this 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 heavily stylable Date Picker providing a very full list of features

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 Version 9 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.