Class: Datagrid

Datagrid(container, config)

Creates and manage a datagrid

Examples of usage:

Manually load data:

 const container = document.getElementById("grid_container");
 const Datagrid = window.portal.Datagrid;
 const grid = new Datagrid(container, {
     id         : "survey-grid",
     classNames : "grid survey",
     columns    : [
         {
             type : "checkbox"
         },
         {
             id  : "name",
             type : "link",
             translateKey : "grid.survey.name",
             dataKey : "name",
             action : (item, cellValue) => {
                 console.log("clicked on: ", item, cellValue);
             }
         }
     ]
 });
 grid.addData([
      {
         id : 1, name : "Survey 1", description : "My first survey" 
      },
      {
         id : 2, name : "Survey 2", description : "My second survey"
      }
 ]);
 grid.display();

Customize the rendering:

 const container = document.getElementById("grid_container");
 const Datagrid = window.portal.Datagrid;
 const grid = new Datagrid(container, {
     id         : "survey-grid",
     classNames : "grid survey",
     columns    : [
         {
             type : "checkbox"
         },
         {
             id  : "name",
             type : "label",
             translateKey : "grid.survey.name",
             dataKey : "name",
             format : (item) => { // Format the text to display
                 return item.name.toLocaleUpperCase();
             }
         },
         {
             id : "description",
             type : "label",
             dataKey : "description",
             renderElement : (element, item) => {
                 if (item.id === 1) { // Add an extra span after the current text
                     const tag = document.createElement("span");
                     tag.innerText = "Default";
                     tag.classList.add("tag");
                     element.classList.add("default");
                     element.parentNode.appendChild(tag);
                 }
             }
         }
     ]
 });
 grid.addData([
      {
         id : 1, name : "Survey 1", description : "My first survey" 
      },
      {
         id : 2, name : "Survey 2", description : "My second survey"
      }
 ]);
 grid.display();

Load data through AJAX requests:

 const container = document.getElementById("grid_container");
 const Datagrid = window.portal.Datagrid;
 const grid = new Datagrid(container, {
     id         : "survey-grid",
     classNames : "grid survey",
     ajaxUrl    : "api/surveys",
     columns    : [
         {
             type : "checkbox"
         },
         {
             id  : "name",
             type : "label",
             translateKey : "grid.survey.name",
             dataKey : "name"
         }
     ]
 });

 grid
     .display() // Display the grid
     .pull();   // Pull the data from the `ajaxUrl` key

Lazy load the data through AJAX requests:

 const container = document.getElementById("grid_container");
 const Datagrid = window.portal.Datagrid;
 const grid = new Datagrid(container, {
     id         : "survey-grid",
     classNames : "grid survey",
     ajaxUrl    : "api/surveys",
     columns    : [
         {
             type : "checkbox"
         },
         {
             id  : "name",
             type : "label",
             translateKey : "grid.survey.name",
             dataKey : "name"
         }
     ]
 });

 const urlParams = {
     offset : 0,
     limit : 200
 };
 grid
     .display()                  // Display the grid
     .pull({                     // Pull the first page of data
         append : false,         // Clear existing data if any
         urlParams : urlParams   // Add some URL parameters on the `ajaxUrl`
     }); 

 grid.addEventListener("scrollOnLastRow", () => {
     urlParams.offset++;
     grid.pull({
         append : true,           // Append the data (don't clear it)
         urlParams : urlParams    // Update the URL parameters on the `ajaxUrl`
     });
 });
Dependencies:
  • ./js/portal.EventEmitter.js
  • ./js/portal.ajax.js
  • ./js/portal.i18n.js
  • ./js/portal.navigation.js
    • ./js/portal.channel.js
  • ./js/portal.utils.js
  • ./css/portal.variables.css
  • ./css/portal.datagrid.css

Constructor

new Datagrid(container, config)

Creates a new instance of the data grid

Parameters:
Name Type Description
container HTMLElement

Container where to append the data grid
config Object

Config of the data grid

Properties
Name Type Attributes Default Description
id String

Identifier of the table
classNames String | function

Class names of the table (or function that returns the class names as string)
idKey String

Indicate how to find the id of the data item
ajaxUrl String <optional>

URL to call if need fresh data for the table
fixedHeaders Boolean <optional>

Indicates that the header is fixed
formatFetchData function <optional>

Method to format the data after it has been fetch
loadingMessage String <optional>

Message while loading the data
noItemsFoundMessage String <optional>

Message when no items are found
bindUrlQuery Boolean <optional>
 false

Indicates if query is binding with the url
filter function <optional>

Method to filter the data
treeview Object <optional>

Tree-view option

Properties
Name Type Attributes Description
childrenDataKey String <optional>

Data key to retrieve the nested children items
columns Array.<Object>

Defines the columns of the data drid

Properties
Name Type Attributes Default Description
id String

Defines the id of the column
type String

Defines the type of the column ("checkbox", "label", "link", "select")
classNames string <optional>

Additional CSS classes (separate with spaces) to apply on both header and cells
translateKey String <optional>

Key to translate the column title
notSortable Boolean <optional>
 false

Indicates if the column is sortable
dataKey String <optional>

Indicates if the data object key to fill the column
dataValueSubKey String <optional>

For multiple values, indicates the sub-key to find the value associated with the data object
dataTextSubKey String <optional>

For multiple values, indicates the sub-key to find the text associated with the data object
maxVisibleSubItems Number <optional>

Max visible sub-items before overflow
overflowSubItemMessageKey String <optional>

Message to display when overflow
attributes Object | function <optional>

Additional attributes (use the object key/value) to set on each cell (or a function that returns an objects)
options Array.<Object> <optional>

Options for the "select" box

Properties
Name Type Attributes Description
value Array.<Object> <optional>

Value of the "select" option
translateKey Array.<Object> <optional>

Key to translate the text of the "select" option
action function <optional>

Action to perform on click
url function <optional>

URL of the link
format function <optional>

Indicates if the format of the data to display (use "date" to format as Date)
useDataAsTranslationKey Boolean <optional>

Use the text as a translation key
renderElement function <optional>

Customize the rendering of the cells

Extends

Methods

addData(data) → {portal.Datagrid}

Add arbitrary data.

Parameters:
Name Type Description
data Array.<Object>

Arbitrary data
Returns:

Return the datagrid

Type
portal.Datagrid

addEventListener(name, fn)

Register a new event.

Parameters:
Name Type Description
name String

Name of the event.
fn function

Function to trigger on event.
Inherited From:
Mixes In:

append(dataItem) → {portal.Datagrid}

Append a new data item in the grid and in the data

Parameters:
Name Type Description
dataItem Object

Data item to append in the grid
Fires:
Returns:

Returns the datagrid

Type
portal.Datagrid

contains(dataItem, text) → {Boolean}

Returns true when the text is contained into the data item

Parameters:
Name Type Description
dataItem Object

Data item where to search
text String

Text to search
Returns:

True if the text is contains

Type
Boolean

createCellContentElement(cellValue, dataItem, column) → {HTMLElement}

Create an element to add in the cell

Parameters:
Name Type Description
cellValue Object

Item use to create the content

Properties
Name Type Attributes Description
text String

Text of the item
value String | Number <optional>

Value associated with the item
translationKey Strign <optional>

Translation key
dataItem Object

Data item associated with the column value
column Object

Column associated with the data item
Returns:

Element to append in the cell

Type
HTMLElement

createRowContentElement(dataItem) → {HTMLElment}

Create a table row element for the specified data item

Parameters:
Name Type Description
dataItem Object

Data item for which to creates the row
Returns:

Table row element to append in the table

Type
HTMLElment

createRows(data, indentopt, statusopt) → {Object|portal.Datagrid.CreateRowsStatus}

Create all table rows using the specified data. This method could be recursive if the datagrid also act as a treeview

Parameters:
Name Type Attributes Default Description
data Array

Data for which to creates the rows
indent Number <optional>
 0

Number of recursive calls to manage the indent
status CreateRowsStatus <optional>

Status of the rows creation
Returns:

display() → {portal.Datagrid}

Build and display the data grid

Returns:

Return the datagrid

Type
portal.Datagrid

emit(name, …args) → {portal.EventArg}

Event to emit.

Parameters:
Name Type Attributes Description
name String

Event to emit.
args * <repeatable>

Arguments of the event.
Inherited From:
Mixes In:
Returns:

Return the event argument.

Type
portal.EventArg

getCellValues(dataItem, column) → {Object|Array.<Object>}

Get the cell values of the data item.

Parameters:
Name Type Description
dataItem Object

Data item on which to retrieve the column value
column Object

Column where to get the value
Returns:

Values {value? , text}

Type
Object | Array.<Object>

getDataLength() → {Number}

Return the total number of data items. This method take in account the treeview like data.

Returns:

Length of data

Type
Number

getPlainText(dataItem, column) → {String}

Get the plain text of the data item for sort or search.

Parameters:
Name Type Description
dataItem Object

Data item on which to retrieve the text
column Object

Column where to get the text
Returns:

Plain text

Type
String

getSelections() → {Array.<Object>}

Returns the list of selected items

Returns:

List of selected items.

Type
Array.<Object>

hideLoader()

Hide loader

hidePlaceholder()

Hide placeholder

listen() → {portal.Datagrid}

Listen the events on the table

Fires:
Returns:

Return the datagrid

Type
portal.Datagrid

pull(optionsopt) → {Promise}

Pull the data to display and render it.

This method require the ajaxUrl in the config.

Parameters:
Name Type Attributes Description
options Object <optional>

Options of the pull

Properties
Name Type Attributes Default Description
append Boolean <optional>
 false

Append new data (don't clear the existing datagrid).
urlParams Object <optional>

URL parameters to add in the after the URL to query the data.
Returns:

Promise when the data is rendered

Type
Promise

query(queryopt) → {portal.Datagrid}

Apply sort, search, filter on the data grid

Parameters:
Name Type Attributes Description
query Object <optional>

Query to apply on the list

Properties
Name Type Attributes Description
sort String <optional>

Name of the column to sort
sortDesc Number <optional>

0 for ascending, 1 for descending
search String <optional>

Search item
Returns:

Return the datagrid

Type
portal.Datagrid

remove(dataItem) → {portal.Datagrid}

Remove a data item from the data grid and from the data

Parameters:
Name Type Description
dataItem Object

Data item to remove
Fires:
Returns:

Returns the datagrid

Type
portal.Datagrid

removeEventListener(name, fn)

Remove an event listener.

Parameters:
Name Type Description
name String

Name of the event to remove.
fn function

Function to remove from the listener.
Inherited From:
Mixes In:

Search the keyword to filter the datagrid

Parameters:
Name Type Description
keyword String

Keyword to search
Returns:

Return the datagrid

Type
portal.Datagrid

showLoader(messageopt)

Show loader with optional message

Parameters:
Name Type Attributes Description
message String <optional>

Message to display

showPlaceholder(messageopt)

Show the placeholder with optional message

Parameters:
Name Type Attributes Description
message String <optional>

Message to display

sortData() → {portal.Datagrid}

Sort the data

Returns:

Return the datagrid

Type
portal.Datagrid

unselect(dataItem) → {Boolean}

Unselect a specific data item, and return true if the state has changed

Parameters:
Name Type Description
dataItem Object

Data item to unselect
Returns:

True if the state has changed

Type
Boolean

update() → {portal.Datagrid}

Update the data grid using the data and the query

Fires:
Returns:

Return the datagrid

Type
portal.Datagrid

updateHeaderCheckbox() → {portal.Datagrid}

Update the state of the header checkbox according to the selections

Returns:

Return the datagrid

Type
portal.Datagrid

Type Definitions

CreateRowsStatus

Type:
  • Object
Properties:
Name Type Description
selectionsChanged Boolean

Indicates if the selections has changed

Events

addRow

Each time a row is added in the table.

Parameters:
Name Type Description
dataItem Object

Data grid item which represent the row.

append

When a data item is append in the table using the append() method.

Parameters:
Name Type Description
dataItem Object

Data grid item that has been append.

remove

When a data item is removed in the table using the remove() method.

Parameters:
Name Type Description
dataItem Object

Data grid item that has been removed.

scrollOnLastRow

When the user scroll on the table container and reach the last display row.

Example of usage:

    let offset = 0;
    grid.addEventListener("scrollOnLastRow", () => {
        offset++;
        grid.pull({
            append: true, 
            urlParams : {
                offset : offset,
                limit  : 250
            }
        });
    });
Parameters:
Name Type Description
datagrid portal.Datagrid

The current datagrid.

selectionChange

When the selection changed.

Parameters:
Name Type Description
selections Array.<Object>

List of selections

update

When the datagrid was updated.

Parameters:
Name Type Description
datagrid portal.Datagrid

The current datagrid.