Dealogic Styleguide

Data Grid

Data Grids are useful for displaying tabular data and provide more functionality than a simple table. Users can edit data, export data, sort, filter, select rows, use optimised data loading mechanisms and much, much more. See ag-Grid Enterprise for full list of supported grid features.

UI Toolkit provides extension to enterprise version of ag-Grid, that covers styling and interactions. It also allows certain UI Toolkit components to be used within grid cells for enhanced functionality.

Developer Setup

UI Toolkit Grid extension is published as a separate npm package, with the same version as UI Toolkit Components and Styles. It supports a specific patch version of ag-Grid Enterprise (v23.2 as of UI Toolkit v4.23.0), which is automatically defined as a dependency, so you don’t have to include ag-Grid yourself.

Step 1 & 2: Connect to feed & register @dealogic

You need to be connected to Dealogic feed and have @dealogic registered in your project – see Step 1 and 2 on Installation page.

Step 3: Set dependacies

Add "@dealogic/dealogic-grid" as a dependency (yarn add @dealogic/dealogic-grid or npm install @dealogic/dealogic-grid).

Step 4: Add grid container to your page

In your HTML - add an element that will contain the grid, e.g.

<div id="my-grid" style=”height: 100%; width:100%;”></div>

Step 5: Import @dealogic-grid package and initialise grid on your grid container

In your script – import @dealogic-grid package

import DlGrid from "@dealogic/dealogic-grid"

Make sure you load the included css from the package. Depending on your setup, this can be done in different ways. In case you CSS gets processed by your bundler, this could be done like so:

import "@dealogic/dealogic-grid/dist/dlgrid.css"

and initialise the grid, on the element defined in your HTML

let eGridDiv = document.querySelector('#my-grid')
const grid = DlGrid.init(eGridDiv, gridOptions)

The init() method will automatically extend ag-Grid’s “gridOptions” object with UI Toolkit default options. It will also add required classes in your HTML - theme classes to the grid element and dl-grid class to its parent container.

See more on gridOptions on ag-Grid’s documentation pages. Note that the first step on ag-Grid Enterprise installation page is already taken care of by your earlier steps. Continue with setting the licence key (Dealogic has 10 developer licences for Enterprise version of ag-Grid).

Column Definitions & Grid Options

Checkbox Column

Add the following parameters into columnDefs object, part of gridOptions ag-Grid object:

headerClass: 'checkbox-column',
headerCheckboxSelection: 'true',
checkboxSelection: 'true',
cellClass: 'checkbox-column'
width: '32'
suppressSorting: 'true'

Numeric Column

Add the following parameters into columnDefs object, part of gridOptions ag-Grid object:

cellClass: 'number-type'
type: 'numericColumn'

Long Text Column

Add the following parameter into columnDefs object, part of gridOptions ag-Grid object:

cellClass: 'long-text'

Non-editable Column

Add the following parameter into columnDefs object, part of gridOptions ag-Grid object:

cellClass: 'non-editable'

Column with a “Hamburger Menu”

suppressMenu: 'false',
menuTabs: ['generalMenuTab']

Loading Indicator Cell

If it is a loading stated column, you should add a cellRenderer function

cellRenderer: 'loadingCellRenderer'

The loadingCellRenderer will return back a span element, which has a 'loading' stylem e.g.:

function loadingCellRenderer(params) {
  var textContent = "<span class='loading'></span>";
  return textContent;
}

Cell Column with Autocomplete

See Autocomplete component page for details, e.g. of callback function returning search results

const callbackFn = (query) => {
  // ...
  return results
}

const columnDefinition = DlGrid.colDef.autoComplete({
  headerName: "DealTerms",
  field: "dealterms",
  editable: true,
}, callbackFn)

Cell Column with Popover Note that extends cell data

Each cell in a column which uses the popover definition is expected to have a label and body property. The label is shown inside the cell, the body content is shown inside the popover.

const popoverDef = DlGrid.colDef.popover({
  headerName: "Poppin'",
  field: "popping",
  editable: false,
  suppressMenu: true,
})

const columnDefs = [
  …
  popoverDef,
  …
]

const row = {
  …
  popping: {
    label: 'cell label',
    body: 'content shown in popover',
  },
  …
}

Large Text Cell Column with Popover Note that shows full cell data

Usefule in cases when cell content overflows the cell

const largeTextDef = DlGrid.colDef.largeText({
  headerName: "Full Name",
  field: "fullname",
  editable: true,
  suppressMenu: true,
})

const columnDefs = [
  …
  largeTextDef,
  …
]

Cell Column with Column Graph

It displays a columns graph based on the values

const colGraphDef = dlGrid.colDef.columnGraph({
  headerName: "Demand sensitivity",
  editable: false,
  suppressMenu: true,
  valueGetter: (params: any) => {
    const values = [];
    let max = Math.round(Math.random() * 2e6);

    for (let i = 9; i >= 1; i--) {
      values.push({
        data: Math.max(0, (max -= Math.round(Math.random() * 1e5))),
        label: "test label",
        selected: false
      });
    }
    values[4].selected = true;
    return {
      values
    };
  }
});

const columnDefs = [
  …
  colGraphDef,
  …
]

Percentage bar

Display a percentage bar

const percentageDef = dlGrid.colDef.percentageBar({
  headerName: '%',
  field: 'account',
  editable: false,
  suppressMenu: true,
  width: 160,
  valueGetter: (params) => {
    return Math.round(Math.random() * 120)
  }
})

const columnDefs = [
  …
  percentageDef,
  …
]

Examples

<div class="dl-grid">
    <div style="padding: 4px">
        <div style="float: right;">
            <dl-input name="name[]" id="quickFilterInput" placeholder="Type text to filter..."></dl-input>
            <dl-button id="btDestroyGrid">Destroy Grid</dl-button>
            <dl-button id="btBringGridBack">Create Grid</dl-button>
        </div>
        <div style="padding: 4px;">
            <b>Employees Skills and Contact Details</b> <span id="rowCount"></span>
        </div>
        <div style="clear: both;"></div>
    </div>
    <div style="width: 100%; height: 400px;" id="bestHtml5Grid" class="ag-basic"></div>
</div>

<div class="dl-grid-full">
    <div style="width: 100%; height: 460px;" class="ag-basic"></div>
</div>

// import DlGrid from "@dealogic/dealogic-grid"

const defaultCountryList = dealogicData['countries'].slice(0, 10)

const countrySearchCallback = (query) => {
  const q = query.toLowerCase()
  return dealogicData['countries'].filter((country) => {
    return country.label.toLowerCase().includes(q)
  })
}

const autocompleteDef = DlGrid.colDef.autoComplete({
  headerName: 'name (autocomplete)',
  field: 'label',
  editable: true,
  suppressMenu: false,
}, countrySearchCallback, {
  defaultOptions: defaultCountryList,
})

const columnGraphDef = DlGrid.colDef.columnGraph({
  headerName: 'demand sensitivity',
  field: 'label',
  editable: false,
  suppressMenu: false,
  refData: {
    currency: 'GBP',
    locale: 'en-US',
  },
  valueFormatter: function (params) {
    return Math.round(Math.random() * 3500) +'k'
  },
  valueGetter: function (params) {
    const values = []
    let max = Math.round(Math.random() * 2e6)

    for (let i = 9; i >= 1; i--) {
      values.push({
        data: Math.max(0, (max -= Math.round(Math.random() * 1e5))),
        label: 90 - i,
        selected: (i === 4),
      })
    }

    return {
      values,
    }
  },
})

const columnDefs = [
  { field: 'group', headerName: 'continent' },
  autocompleteDef,
  columnGraphDef,
  { field: 'sub', headerName: 'capital' },
  { field: 'sup', headerName: 'code' },
]

const gridOptions = {
  columnDefs,
  rowData: dealogicData['countries'],
}

const grid = DlGrid.init(document.querySelector('.dl-grid-full .ag-basic'), gridOptions)

<div class="dl-grid-percentage">
    <div style="width: 100%; height: 300px;" class="ag-basic"></div>
</div>

// import DlGrid from "@dealogic/dealogic-grid"

const percentageDef = DlGrid.colDef.percentageBar({
  headerName: '% bar',
  field: 'account',
  editable: false,
  suppressMenu: true,
  width: 160,
  valueGetter: (params) => {
    return Math.round(Math.random() * 120)
  }
})

const columnDefs = [
  { field: 'label', headerName: 'name' },
  { field: 'group', headerName: 'continent' },
  percentageDef,
  { field: 'sub', headerName: 'capital' },
  { field: 'sup', headerName: 'code' },
]

const gridOptions = {
  columnDefs,
  rowData: dealogicData['countries'],
}

const grid = DlGrid.init(document.querySelector('.dl-grid-percentage .ag-basic'), gridOptions)