Using AdapTable
important
This page is referring to how to set up an instance of AdapTable using core JavaScript. If using a Framework Wrapper the process is very similar conceptually but with some subtle differences.
See React Wrapper or Angular Wrapper for precise instructions.
caution
If you are using TypeScript to access AdapTable then you must use version 3.8.3 or higher
Creating an instance of AdapTable is straightforward and involves just 5 steps:
- Create
<div />
elements in your HTML for Adaptable and the underlying vendor grid. - Popular a vendor Data Grid instance with a column schema, row data and any properties set.
- Write any Predefined Config that you want your AdapTable instance to contain at start-up
- Create an Adaptable Options object, passing it the
vendorGrid
andpredefinedConfig
properties. - Instantiate AdapTable - passing in the AdaptableOptions object and retrieving an Adaptable Api object for programmatic, run-time access to the tool.
This will then provide you with a fully working AdapTable instance together with an Adaptable API object which provides programmatic, run-time access.
Lets look at each of these in trun:
note
We will use ag-Grid in this example - by far the most popular and feature-rich DataGrid on the market.
Creating Div Elements
You need to create 2 <div />
elements in your HTML:
- adaptable: will contain the AdapTable instance and is typically positioned first
- grid: will contain the underlying vendor DataGrid; try to name this 'grid' if possible
tip
If using a Shadow DOM or some other mechanism where you cannot create the Div elements directly then use Container Options to pass in the 'adaptable' and 'grid' divs.
This accepts either the name of the Div or the HTMLElement itself.
Define Vendor DataGrid
It is your responsibility to set up the underlying vendor Data Grid object.
warning
Do not instantiate this vendor grid object. AdapTable will do that later together in its constructor together with any wiring up that might be required.
You should define any columns, set any properties, wire up grid events and perhaps provide it with initial data.
This will then be provided to AdapTable via the vendorGrid
property of Adaptable Options.
Column Types
When defining the column schema in the Columns
property of GridOptions it is advisable to add a ColumnType property for each column which matches an AdapTable Column Type.
note
This is not strictly required; however it helps AdapTable know definitively the Data Type of the column which will influence which filters and column options are available.
tip
This is advisable to use in all scenarios; however it's particularly important when the data is loaded after columns have already been set up, as AdapTable might have incorrectly inferred column data types.
caution
If a ColumnType property is not provided, AdapTable will look at the first row of the DataSet to evaluate the Data Type - this can occasionally cause issues on empty or 'mixed' columns.
The AdapTable ColumnTypes are:
- abColDefNumber: for numeric columns
- abColDefNumberArray: for numeric array columns (used in Sparkline Columns)
- abColDefString: for string (text) columns
- abColDefBoolean: for boolean (yes/no) columns
- abColDefDate: for data and time columns
- abColDefObject: for any other column
tip
The type property can accept an array allowing you to provide your own types as well as those which AdapTable expects - as shown in the last column in example above
important
In Versions of AdapTable prior to 7.3 it was necessary also to add a ColumnTypes section in GridOptions - see Troubleshooting FAQ for an example.
Provide Predefined Config
Add any Predefined Config to ship AdapTable to meet your requirements for first use.
In this example we do the following:
- Set 3 Dasbhboard Tabs - with 'Grid', 'Edit' and 'Search' related Toolbars respectively
- Created a Layout with Row Grouping for the Make and Aggregation for Price columns
- Provided a Display Format for the 'Price' column
- Set a default System Status message of type 'Success'
Create AdapTable Options object
Create an AdaptableOptions object which defines how AdapTable should work and contains all it needs
Set any mandatory properties (e.g. adaptableId, primaryKey etc.) and add values for any non-mandatory properties where the default values are not appropriate.
Pass in the 'vendorGrid' object created in Step 2 (together with any Modules you need), and the 'predefinedConfig' (created above).
Also add any Plugins you want to include (in this example the Charts Plugin).
Instantiate AdapTable
AdapTable has a single, asynchronous static contstructor
This receives the Adaptable Options object as its only argument and returns (via a Promise) an Adaptable API object - which gives run time access to all AdapTable functionality.
Access AdapTable at run-time
The AdapTable API has hundreds of methods to allow full programmatic access to AdapTable methods, events and state.
tip
One common practice is to subscribe to the Adaptable Ready event in order to perform any actions required at startup.
Putting It All Together
This example shows all the above steps.