Extending Layouts
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":
-
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
-
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.
| Property | Type | Description |
|---|---|---|
| Alert | string[] | Names of Alert Definitions which apply in this Layout |
| CustomSort | string[] | Names of Custom Sorts which apply in this Layout |
| FlashingCell | string[] | Names of Flashing Cell Definitions which apply in this Layout |
| FormatColumn | string[] | Names of Format Columns which apply in this Layout |
| LayoutName | string | Name of the Layout being extended (Mandatory) |
| PlusMinus | string[] | Names of Plus Minus Nudges which apply in this Layout |
| Shortcut | string[] | Names of Shortcuts which apply in this Layout |
| StyledColumn | string[] | 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
- This demo illustrates how to use
LayoutExtensionsin Layout State to limit objects to 2 Layouts -First LayoutandSecond Layout- with similar configuration - There are 5 Format Columns provided:
Licenseis bold -First LayoutLanguageis blue where value is 'TypeScript' -First LayoutGithub Starshas a bespoke Style and a Display Format -Second Layout- Whole row is orange where
Languagevalue is 'HTML' -Second Layout DateColumns are Italicised and have a Display Format - not extended, so it applies in every Layout
- Additionally we provide 5 Styled Columns:
Namehas a Badge Style -First LayoutOpen PRshas a Gradient Column -First LayoutClosed Issueshas a Percent Bar -Second LayoutHistoryhas a different Sparkline Column inFirst LayoutandSecond Layout
- We set
enableLayoutExtensionsUIto true in Layout Options so that users can change which Layouts an object belongs to
- 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
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',
},
],
},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' },
},
],
},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'],
},
],
},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: falseBooleanNote
- 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 remainsetLayoutsForObject- 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 intogetLayoutExtensions- returns all the objects extended into a LayoutsetLayoutExtensions- replaces all the objects extended into a Layout
addObjectToLayout
object: LayoutExtensionObject, module: LayoutExtensionModule, layoutName?: stringvoidremoveObjectFromLayout
object: LayoutExtensionObject, module: LayoutExtensionModule, layoutName?: stringvoidsetLayoutsForObject
object: LayoutExtensionObject, module: LayoutExtensionModule, layoutNames: string[]voidgetLayoutsForObject
object: LayoutExtensionObject, module: LayoutExtensionModulestring[]getLayoutExtensions
layoutName: stringLayoutExtensionInfosetLayoutExtensions
layoutName: string, extensionInfo: LayoutExtensionInfovoidHint
Layout API also contains renameLayout which renames a Layout and keeps its Layout Extensions
- This demo has 3 Layouts -
Trading,ResearchandAudit- 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 -
setLayoutsForObjectwith the Current Layout - Add to Current Layout -
addObjectToLayout - Make Available Everywhere -
setLayoutsForObjectwith an empty array
- Restrict to Current Layout -
- After each change we call
getLayoutsForObjectand display the result as a System Status message
- Click Restrict to Current Layout, then switch Layouts and note that the
LicenseColumn 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
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
| Property | Type | Description |
|---|---|---|
| Extensions | ExtendedLayoutObject[] | Object to be included in the Layout |
| Layout | Layout | Layout being extended |
The createOrUpdateExtendedLayout function in Layout API enables creating or updating Extended Layouts.
createOrUpdateExtendedLayout
extendedLayout: ExtendedLayoutvoidRetrieving 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: stringExtendedLayout | undefinedSharing 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
- 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())
- 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
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: stringExtendedLayout | falseCaution
- 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
- This example has an Extended Layout ('Original Layout') which we clone
- Click first the button to clone (and then set) the Extended Layout and note that all extended objects apply in the clone
- Click the second button (which becomes enabled) to change the style for the
LanguageColumn - Switch Layouts and note that you see the new style in the original Layout also
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
- This example shows how to use Layout Metadata. We add a
Metadataproperty to 4 layouts:First LayoutandThird Layout- haveMetadataproperty of 'Large' - and they show the Dashboard, open the Tool Panel and use dark themeSecond LayoutandFourth Layout- haveMetadataproperty of 'Small' - and they hide the Dashboard, close the Tool Panel and use light theme
- 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