Articles in this section

Getting Started Tutorial

Avatar
Adaptable Tools
  • Updated
Follow

It is very simple to set up the Adaptable Blotter.

Note

The Adaptable Blotter will run in any modern browser - Chrome, Firefox, Edge, Safari, Opera etc.

It does not run in Internet Explorer.

This tutorial will show you, step by step, how to set up a very simple working version of the Adaptable Blotter from scratch. 

Tip

This is a very basic installation for demonstration purposes - for a more detailed overview and explanation of how to set up the Adaptable Blotter, together with full descriptions of the objects required, and integrate it with the underlying grid - see Integration.

Tip

You can see the final version of this demo here.

  1. Create a new Application

    Create a new, empty, web application in a code editor of your choice.  

    Warning

    The Adaptable Blotter is installed via npm and is usually referenced from a node_modules folder, so a Node.js aware application is a definite advantage.

    Tip

    If you are creating a brand new Node.js application from scratch then Express is an excellent resource to get started quickly with a shell application.

  2. Create a stub HTML page

    Now lets create a basic HTML page.  Give it any name that you wish.

    Create 2 <div>s: one for the Adaptable Blotter and the other for the underlying vendor grid.  

    It will also contain a link in a script tag to index.js where we will put most of the code we need

    <!DOCTYPE html>    
    <head>        
        <title>Adaptable Blotter Demo</title>
    </head>
    <body>
        <div id='adaptableBlotter'></div>
        <div id="grid" style="height: 600px;width:700px;" class="ag-theme-balham">

        <script src="src/index.js"></div>
    </body>
</html>

    Warning

    If you don't give the <div>s the same Ids as used above, then you will need to provide the alternative ones (as adaptableBlotterContainer and vendorContainer properties) when creating your AdaptableBlotterOptions object later.

  3. Install the Vendor Grid

    The Adaptable Blotter integrates with an underlying vendor grid so lets now install that.

    Note

    In this example we are using the ag-Grid - the most popular and powerful of all HTML5 DataGrid controls - but the Adaptable Blotter works with other DataGrid controls also.

    To install ag-Grid, in the command line / terminal add:

    npm install ag-grid-community
npm install ag-grid-enterprise

    Note

    The Adaptable Blotter only works with the ag-Grid Enterprise version due to the way that its features primarily complement ag-Grid Enterprise features.

    Warning

    If you are using the ag-Grid Enterprise Version then you must have a valid licence - see more details here.

  4. Create a JavaScript file

    Create a page called index.js which we will use to create the vendor grid and the Adaptable Blotter

  5. Add some styles

    Lets now add the styles we need for both ag-Grid (the vendor grid we are using) and the Adaptable Blotter.

    We will want to switch between the dark and light themes so lets add styles for both. For more information on this topic see Themes.

    // import blotter css and themes
import "@adaptabletools/adaptableblotter/index.css";
import "@adaptabletools/adaptableblotter/themes/dark.css";

// import aggrid themes
import "ag-grid-community/dist/styles/ag-grid.css";
import "ag-grid-community/dist/styles/ag-theme-balham.css";
import "ag-grid-community/dist/styles/ag-theme-balham-dark.css";

  6. Instantiate the Vendor Grid

    Now we have installed ag-Grid lets create a grid instance itself and provide it with some data.

    Add this section to our page in the <body> section straight after the 2 <div> tags we created earlier.

    Note

    This example is taken directly from one provided by ag-Grid.

      // specify the columns for ag-Grid
  var columnDefs = [
    {headerName: "Make", field: "make"},
    {headerName: "Model", field: "model"},
    {headerName: "Price", field: "price"}
  ];
  // specify the data for ag-Grid
  var rowData = [
    {make: "Toyota", model: "Celica", price: 35000},
    {make: "Ford", model: "Mondeo", price: 32000},
    {make: "Porsche", model: "Boxter", price: 72000}
  ];                
  // let ag-grid know which columns and what data to use
  var gridOptions = {
    columnDefs: columnDefs,
    rowData: rowData,
    enableSorting: true,
    enableFilter: true
  };  
  //  This is only here temporarily - we will remove when we create the Adaptable Blotter        
  // lookup the container we want the Grid to use
  var eGridDiv = document.querySelector('#grid');
  // create the grid passing in the div to use 
  //together with the columns & data we want to use
  new agGrid.Grid(eGridDiv, gridOptions);

    If we run our page in the browser we will now see an ag-Grid populated with the 3 lines of dummy data we provided it.

    Screenshot_2018-10-14_13_05_44.png

    Note

    We have instantiated the ag-grid vendor instance here for demonstration purposes. We will shortly remove that code as the Adaptable Blotter takes care of that for you.

  7. Install the Adaptable Blotter

    Let's now create an instance of the Adaptable Blotter to integrate with the vendor grid that we have already instantiated.

    But first we need to install it which we do via a private npm registry. See Installation for full details.

    Once this is successfully completely, it will add a new 'adaptableblotter' folder to our node_modules folder.

    Note

    The downloaded folder includes all the files you need, including definition files and transpiled JavaScript.

  8. Integrate the Adaptable Blotter

    Now that the Adaptable Blotter is installed, lets integrate it with our ag-Grid.

    This involves 3 steps:

    1. Create a reference to the Adaptable Blotter

       import AdaptableBlotter from '@adaptabletools/adaptableblotter/agGrid'

    2. Create an AdaptableBlotterOptions object

      The Blotter Options object will include all the information the Adaptable Blotter needs to instantiate itself. 

      The only 2 mandatory properties are primaryKey (to allow us to identify each cell) and vendorGrid (a reference to the underlying grid  - in this case the ag-Grid we created above).

      let blotterOptions = {
    primaryKey: "make",
    vendorGrid: gridOptions,
    userName: "demo user",
    blotterId: "Demo agGrid Blotter"
}

      Tip

      Only add values for non-mandatory properties where you are unhappy with the default options.

      For a full list of properties (and default values) see Blotter Options Documentation.

      Note

      This is a very basic implementation. 

      For instance, we have not set up Server Searching, Audit Log  or enabled Config Server.  Nor have we provided the Blotter with any Permissions (though we will add Predefined Config in the final step).

      Information on all these advanced topics can be found elsewhere in this Help.

    3. Instantiate the Adaptable Blotter.

      This is a one line command that creates an Adaptable Blotter of a type that matches the underlying grid. 

      The constructor takes just one parameter - the AdaptableBlotterOptions object created in the previous step.

      let blotter = new AdaptableBlotter(blotterOptions);

      Warning

      You should remove the bit of code that we wrote earlier where we instantiated the ag-grid instance as the Adaptable Blotter will do that for us.

      So delete the few lines that start with the comment: // This is only here temporarily - we will remove when we create the Adaptable Blotter

  9. Test Page in a Browser

    To test, lets run our web page in a browser and we should see the Adaptable Blotter sitting on top of - and integrating with - our ag-Grid instance (in this case by running a Quick Search).

    Screenshot_2018-10-14_15_17_52.png

    Warning

    You might see a warning in your console that the Adaptable Blotter does not know the Data Types of the columns supplied. If you want to avoid this, you can specify the DataTypes for ag-Grid in the columnTypes property of GridOptions. See Trouble Shooting FAQ for more details.

  10. Add Predefined Config (Optional)

    We are now finished. 

    However, if we wish, we can change initial look and feel of the screen by setting User State through Predefined Config.

    (There are very many different options for Predefined Config allowing you to set up each instance of the Adaptable Blotter exactly to meet your visual, business, user and entitlements requirements - see full list at Config Basics.)

    For this example, we shall keep it simple and make 2 config changes

    • Set the initial theme to be "Dark Theme" (instead of the default "Light Theme").

    • Show the 'Smart Edit' toolbar (instead of the default 'Advanced Search' toolbar).

    Tip

    You can see all the Predefined Config options at Predefined Config Documentation.

    We simply need to create the JSON for the Predefined Config and then add it to predefinedConfig property of Blotter Options.

    let demoJson = {      
  "Dashboard": {
    "VisibleToolbars": [
      "SmartEdit",
      "QuickSearch"
    ]
  },
  "Theme": {
    "CurrentTheme": "Dark Theme"
  }
}

// create an AdaptableBlotterOptions object
let blotterOptions = {
  primaryKey: "make",
  vendorGrid: gridOptions,
  userName: "demo user",
  blotterId: "Demo agGrid Blotter",
  predefinedConfig: demoJson
}

    Now if we run the page we see that we are using the dark theme and the Smart Edit toolbar is in place:

    demodark.PNG

    Tip

    You might need first to clear any local state for Demo Grid Blotter in your local cache before you can see this change.  (An alternative is to run the configClear function in Blotter API).

Example 2. Full Code for Getting Started Tutorial

This is the full code that we created during this tutorial:

**** index.html *****
<!DOCTYPE html>
  <head>
    <title>Adaptable Blotter Demo</title>
  </head>
  <body>
    <div id='adaptableBlotter'></div>
    <div id="grid" style="height: 600px; width:700px;" class="ag-theme-balham"></div>
    <script src="src/index.js"></div>
  </body>
</html>


**** index.js *****
// import the Adaptable Blotter
import AdaptableBlotter from '@adaptabletools/adaptableblotter/agGrid'

// import blotter css and themes
import "@adaptabletools/adaptableblotter/index.css";
import "@adaptabletools/adaptableblotter/themes/dark.css";

// import aggrid themes
import "ag-grid-community/dist/styles/ag-grid.css";
import "ag-grid-community/dist/styles/ag-theme-balham.css";
import "ag-grid-community/dist/styles/ag-theme-balham-dark.css";

// specify the columns for ag-Grid
  var columnDefs = [
    {headerName: "Make", field: "make"},
    {headerName: "Model", field: "model"},
    {headerName: "Price", field: "price"}
  ];
  
// specify the data for ag-Grid
  var rowData = [
    {make: "Toyota", model: "Celica", price: 35000},
    {make: "Ford", model: "Mondeo", price: 32000},
    {make: "Porsche", model: "Boxter", price: 72000}
  ];  
              
  // let ag-grid know which columns and what data to use
  var gridOptions = {
    columnDefs: columnDefs,
    rowData: rowData,
    enableSorting: true,
    enableFilter: true
  };  

// Create some predefined config 
// NOTE : this will ONLY work if you have a valid Adaptable Blotter li
let demoJson = {      
  "Dashboard": {
    "VisibleToolbars": [
      "SmartEdit",
      "QuickSearch"
    ]
  },
  "Theme": {
    "CurrentTheme": "Dark Theme"
  }
}

// create an AdaptableBlotterOptions object
let blotterOptions = {
  primaryKey: "make",
  vendorGrid: gridOptions,
  userName: "demo user",
  blotterId: "Demo agGrid Blotter",
  predefinedConfig: demoJson
}

// instantiate the Adaptable Blotter
let blotter = new AdaptableBlotter(blotterOptions);

Related articles

Comments

0 comments

Article is closed for comments.

Powered by Zendesk