Extending Layouts

View as Markdown

Summary

  • Layouts contain useful sets of column-related information
  • This means that they do not include Format Columns, Styled Columns or Alerts etc
  • AdapTable provides a mechanism for users who find this restriction too constraining
  • Objects (e.g. Format Columns) can be extended into particular Layouts, so they only apply there
  • Developers can also add bespoke Metadata to a Layout

At their core, Layouts are simply sets of column-related properties.

They contain details of Column visibility, order, sorting, grouping, aggregations, filters and related properties.

Caution

By default, Layouts do not contain other Adaptable Objects like styling, formatting, Alerts or Flashing Cells

This results in 2 types of "restrictions":

  1. all Adaptable Objects in Adaptable State are automatically available in all Layouts, even though a user might prefer, for example, for some styles or Alerts to be applicable to one Layout but not another

  2. developers cannot add custom objects, or properties, to their Layouts

AdapTable therefore allows for Layouts to be extended in 2 ways to meet these twin limitations:

  • Layout Extensions - so that some AdapTable objects apply only in selected Layouts

  • Metadata - to enable developers to provide additional bespoke information in the Layout

Layout Extensions

AdapTable allows Layouts to be extended to have knowledge of specific Adaptable Objects.

In other words developers - or runtime users - can specify that a particular Format Column, Styled Column or Alert is available in "LayoutA" but not "LayoutB".

This is managed via the LayoutExtensions property of Layout State.

It is a collection of LayoutExtension objects - each one names a Layout and lists, per Module, the names of the objects extended into that Layout.

The Modules that can be extended are:

Objects that apply only in one layout.

An Alert, Custom Sort, Flashing Cell, Format Column, Plus Minus nudge, Shortcut or Styled Column applies in every layout until its Name is listed here. Once listed, it applies only in the layouts that name it. LayoutName is the layout's Name. Each array is object names, not column ids.

PropertyTypeDescription
Alertstring[]Names of Alert Definitions which apply in this Layout
CustomSortstring[]Names of Custom Sorts which apply in this Layout
FlashingCellstring[]Names of Flashing Cell Definitions which apply in this Layout
FormatColumnstring[]Names of Format Columns which apply in this Layout
LayoutNamestringName of the Layout being extended (Mandatory)
PlusMinusstring[]Names of Plus Minus Nudges which apply in this Layout
Shortcutstring[]Names of Shortcuts which apply in this Layout
StyledColumnstring[]Names of Styled Columns which apply in this Layout
// `Bold License` applies in `Trading` and `Research`;  `Highlight TypeScript` and `Big Price Move` only in `Trading`
// Every other Format Column and Alert applies everywhere
Layout: {
  CurrentLayout: 'Trading',
  Layouts: [...],
  LayoutExtensions: [
    {
      LayoutName: 'Trading',
      FormatColumn: ['Bold License', 'Highlight TypeScript'],
      Alert: ['Big Price Move'],
    },
    {
      LayoutName: 'Research',
      FormatColumn: ['Bold License'],
    },
  ],
},

Note

  • The rules for Extending Layouts are simple and consistently applied:
    • An object which is not listed in any Layout Extension is global - it applies in every Layout (this is the default)
    • Once an object is listed in one or more Layout Extensions, it applies only in those Layouts
Deep Dive

Understanding how Layout Extensions are kept in sync

Extended Layouts
Fork
  • This demo illustrates how to use LayoutExtensions in Layout State to limit objects to 2 Layouts - First Layout and Second Layout - with similar configuration
  • There are 5 Format Columns provided:
    • License is bold - First Layout
    • Language is blue where value is 'TypeScript' - First Layout
    • Github Stars has a bespoke Style and a Display Format - Second Layout
    • Whole row is orange where Language value is 'HTML' - Second Layout
    • Date Columns are Italicised and have a Display Format - not extended, so it applies in every Layout
  • Additionally we provide 5 Styled Columns:
    • Name has a Badge Style - First Layout
    • Open PRs has a Gradient Column - First Layout
    • Closed Issues has a Percent Bar - Second Layout
    • History has a different Sparkline Column in First Layout and Second Layout
  • We set enableLayoutExtensionsUI to true in Layout Options so that users can change which Layouts an object belongs to
Try It Out
  • Switch between the 2 Layouts to see the different Format Columns and Styled Columns applied
  • Open the Format Column section of the Settings Panel and use the buttons in the Layouts row to change which Layouts an object belongs to
  • Tick "Show Format Columns not available in current Layout" to see objects extended into other Layouts
  • Edit a Format Column and use the Layouts step in the wizard
Loading demo…

Configuring Extended Layouts

Developers can set up Extended Layouts in Initial State.

Developer Guide

Setting up Extended Layouts

These are the steps required to extend Layouts:

Layout: {
  CurrentLayout: 'First Layout',
  Layouts: [
    {
      TableColumns: ['name', 'language', 'description'],
      Name: 'First Layout',
    },
    {
      TableColumns: ['license', 'has_wiki', 'has_pages'],
      Name: 'Second Layout',
    },
  ],
},
1
Create the Layout(s)

Define any required Layout(s) in Layout Initial State.

Create the Layouts as usual - nothing special is required.

FormatColumn: {
  FormatColumns: [
    {
      Name: 'Bold Name',
      Scope: { ColumnIds: ['name'] },
      Style: { FontWeight: 'Bold' },
    },
    {
      Name: 'Italic Text',
      Scope: { ColumnIds: ['text'] },
      Style: { FontStyle: 'Italic' },
    },
  ],
},
2
Give each Object a unique Name

Create the other objects as usual, making sure each has a Name which is unique within its Module.

Layout: {
  CurrentLayout: 'First Layout',
  Layouts: [...],
  LayoutExtensions: [
    {
      LayoutName: 'First Layout',
      FormatColumn: ['Bold Name', 'Italic Text'],
    },
    {
      LayoutName: 'Second Layout',
      FormatColumn: ['Italic Text'],
    },
  ],
},
3
Add a Layout Extension for each Layout

Add a LayoutExtensions collection to Layout State with a Layout Extension for each Layout.

List - per Module - the names of the objects which should apply in it.

Objects not listed anywhere remain available in every Layout.

Extending Layouts in the UI

Run-time Users can also manage which Layouts an object belongs to.

Caution

This is off by default - set enableLayoutExtensionsUI in Layout Options to true to enable it

enableLayoutExtensionsUI

Default: false
Boolean
Show controls for extending objects into Layouts

Note

  • Even if this property is set to false, extended objects show a read-only Layouts row in Settings Panel
  • The Settings Panel displays a checkbox to show objects which are not available in the Current Layout

Extending Layouts via API

Layout API contains 6 functions to read and change which objects are extended into which Layouts:

  • addObjectToLayout - extends an object into a Layout (by default the Current Layout)
  • removeObjectFromLayout - removes an object from a Layout; it becomes global if no Layouts remain
  • setLayoutsForObject - extends an object into exactly the given Layouts (an empty list makes it global)
  • getLayoutsForObject - returns the names of the Layouts an object is extended into
  • getLayoutExtensions - returns all the objects extended into a Layout
  • setLayoutExtensions - replaces all the objects extended into a Layout

addObjectToLayout

object: LayoutExtensionObject, module: LayoutExtensionModule, layoutName?: string
void
Extends an object into a Layout

removeObjectFromLayout

object: LayoutExtensionObject, module: LayoutExtensionModule, layoutName?: string
void
Removes an object from a Layout

setLayoutsForObject

object: LayoutExtensionObject, module: LayoutExtensionModule, layoutNames: string[]
void
Extends an object into exactly the given Layouts

getLayoutsForObject

object: LayoutExtensionObject, module: LayoutExtensionModule
string[]
Returns the Layouts an object is extended into

getLayoutExtensions

layoutName: string
LayoutExtensionInfo
Returns all the objects extended into a Layout

setLayoutExtensions

layoutName: string, extensionInfo: LayoutExtensionInfo
void
Replaces all the objects extended into a Layout

Hint

Layout API also contains renameLayout which renames a Layout and keeps its Layout Extensions

Managing Layout Extensions with the API
Fork
  • This demo has 3 Layouts - Trading, Research and Audit - and a single Format Column (Bold License) which initially applies in all of them
  • A Custom Toolbar provides 3 buttons which call Layout API:
    • Restrict to Current Layout - setLayoutsForObject with the Current Layout
    • Add to Current Layout - addObjectToLayout
    • Make Available Everywhere - setLayoutsForObject with an empty array
  • After each change we call getLayoutsForObject and display the result as a System Status message
Try It Out
  • Click Restrict to Current Layout, then switch Layouts and note that the License Column is no longer styled
  • In another Layout, click Add to Current Layout and note that the Format Column now applies in both Layouts
  • Click Make Available Everywhere to restore the default
Loading demo…

Creating Extended Layouts

An ExtendedLayout is a composite object which contains a Layout together with the objects extended into it:

Defines an Extended Layout - provides a Layout and all objects that refer to it

PropertyTypeDescription
ExtensionsExtendedLayoutObject[]Object to be included in the Layout
LayoutLayoutLayout being extended

The createOrUpdateExtendedLayout function in Layout API enables creating or updating Extended Layouts.

createOrUpdateExtendedLayout

extendedLayout: ExtendedLayout
void
Receives an Extended Layout and saves it, and all extended Objects, to State

Retrieving Extended Layouts

AdapTable also provides the getExtendedLayoutByName helper function in Layout API which can fetch an Extended Layout from AdapTable State.

Hint

This is particularly useful if wanting to share or clone an Extended Layout (see below)

getExtendedLayoutByName

layoutName: string
ExtendedLayout | undefined
Returns the full Extended Layout object with the given name

Sharing Extended Layouts

By their nature, Extended Layouts are not stored as a single, composite object in Adaptable State.

Instead, the Layout is stored with other Layouts, the extended objects (e.g. Format Columns or Custom Sorts) are stored in the appropriate State section, and the association between them is stored in LayoutExtensions.

However by using the 2 functions above - getExtendedLayoutByName and createOrUpdateExtendedLayout - it is possible to fetch an Extended Layout, make any changes to it as needed, and save it elsewhere.

Hint

  • A better way to do this is via Referenced Team Sharing
  • This shares a Layout together with all the objects extended into it
Sharing Extended Layouts
Fork
  • This example has an initial Layout ('First Layout') extended with 4 Format Columns
  • A Custom Dashboard Button imports - and sets - a new Extended Layout ('Imported Layout') with 2 Styled Columns
  • When a Layout is Selected we send a System Status message with its contents (and log the full object to the console())
Try It Out
  • Click the button to import and set the new Extended Layout and note that you see the Layout and the 2 Styled Columns (but not the 4 Format Columns)
  • Open the System Status popup to see the contents of the Extended Layout
  • Open the Console and switch between Layouts to see the full Extended Layout object
Loading demo…

Cloning Extended Layouts

Extended Layouts, like regular Layouts, can be cloned.

AdapTable clones the underlying Layout and extends all of the original Layout's objects (e.g. Format Columns or Styled Columns) into the clone.

This is done using the cloneExtendedLayout function in Layout API.

cloneExtendedLayout

layout: ExtendedLayout, newName: string
ExtendedLayout | false
Clones an Extended Layout

Caution

  • The extended objects themselves are not copied - both original and cloned Layouts reference the same objects
  • This means that changing that object (e.g. a Format Column) will be reflected in both Layouts
Cloning Extended Layouts
Fork
  • This example has an Extended Layout ('Original Layout') which we clone
Try It Out
  1. Click first the button to clone (and then set) the Extended Layout and note that all extended objects apply in the clone
  2. Click the second button (which becomes enabled) to change the style for the Language Column
  3. Switch Layouts and note that you see the new style in the original Layout also
Loading demo…

Metadata

Sometimes developers want to extend Layouts by including their own custom bespoke properties and objects.

Note

A common use case is to include the Author or the Team or other organisation-specific details

This is done by using the Metadata property (of type any) which is in the Adaptable Object type, from which the Layout object derives.

Caution

Unlike most properties in the Layout, Metadata can only be added at design-time or programmatically

Layouts With Metadata
Fork
  • This example shows how to use Layout Metadata. We add a Metadata property to 4 layouts:
    • First Layout and Third Layout - have Metadata property of 'Large' - and they show the Dashboard, open the Tool Panel and use dark theme
    • Second Layout and Fourth Layout - have Metadata property of 'Small' - and they hide the Dashboard, close the Tool Panel and use light theme
Try It Out
  • Switch between the Layouts (you might need to use the status bar when the Dashboard is hidden!) to see how we listen to Metadata and change the grid accordingly
Loading demo…