ebs.generateGrid
Displays a custom view inside a specific HTML element in the Document Object Model. For the interactive version of the grid, which allows you to edit the view records by double clicking them, see ebs.generateInteractiveGrid.
Syntax
function ebs.generateGrid(gridHtmlId: string, viewData: IViewData, height?: string | number, actionHandlers?: EbsActionHandler[], callback?: Function, gridOptions?: IEbsGridOptions, overrideViewColumnList?: any[], pageContext?: any, useProvidedFetch?: boolean;): void;
| Parameter | Type | Description |
|---|---|---|
gridHtmlId
|
string | ID of the HTML element where the view will be injected. |
viewData
|
IViewData | Data view used as a data source for the grid. IMPORTANT! If the data view is based on a custom fetch, the fetch expression must include the primary key of the main entity in the result set. |
height (optional) |
string | number | HTML markup value for the height of the HTML element where the view will be injected (see the gridHtmlId parameter).This allows you, for instance, to set a fixed height or a dynamic height based on a function for your view. By default, the height will be set to 100%. |
actionHandlers (optional) |
EbsActionHandler[] |
Custom action handlers you wish to display in the top right corner of the grid. |
callback (optional) |
Function | Callback function to run when the view is displayed. |
gridOptions (optional) |
IEbsGridOptions | Display customizations for the grid. |
overrideViewColumnList (optional) |
any[] | Replace the view columns returned by the view data with a custom set of view columns. |
Interfaces
IViewData
Specifications of a data view. Depending on the provided parameters, this may reference an existing view (e.g., viewName) or act as a literal definition of a view to be instantiated directly (e.g., by using a custom fetch expression).
interface IViewData {
mainHtmlId?: string;
fetch?: IFetch;
viewName?: string;
formName?: string;
hasCustomFetch?: boolean;
columns?: any[];
optionSetsAsRadio?: any;
editFormName?: string;
showViewButton?: boolean;
selectedView?: IEbsMetadataView;
editForm?: IEbsMetadataForm;
baseEntityMetadata?: IEbsMetadataEntity;
isSimpleGrid?: boolean;
transientCollectionRequest?: ITransientEntityDataAsCollectionRequest;
parameters?: any;
}
| Property | Type | Description |
|---|---|---|
| mainHtmlId (optional) |
string | ID of the HTML element where the view will be injected. Used when opening a data view from a menu item. |
| fetch (optional) |
IFetch | Fetch object expression used to retrieve the desired data. |
| viewName (optional) |
string | Name of a preconfigured data view used to retrieve the desired data. |
| formName (optional) |
string | Name of the data form used to open view records. |
| hasCustomFetch (optional) |
boolean | Indicates if the view uses a custom fetch object expression to return results. |
| columns (optional) |
any[] | Entity view columns to be displayed by the data view. |
| optionSetsAsRadio (optional) |
any | Represent option set attributes as radio buttons. |
| editFormName (optional) |
string | Name of the data form used to open view records for editing. |
| showViewButton (optional) |
bolean | Display a dedicated View button for each view record. |
| selectedView (optional) |
IEbsMetadataView | Allows you to manually configure the data form used as data source. |
| editForm (optional) |
IEbsMetadataForm | Allows you to manually configure the data form used to open view records for editing. |
| baseEntityMetadata (optional) |
IEbsMetadataEntity | Allows you to manually configure the base entity of the data view. |
| isSimpleGrid (optional) |
boolean | Indicates the data view is a simple grid report. |
| transientCollectionRequest (optional) |
ITransientEntityDataAsCollectionRequest | Allows you to use a transient data entity with a collection output that is part of the base entity's extended model as data source. |
| parameters (optional) |
any | Parameter bag that can supply additional values that may override options defined in higher-level function arguments, enabling reuse across different entry points. |
EbsActionHandler
Object representing a custom action handler to be displayed in the top right corner of a grid.
class EbsActionHandler {
iconClass: string;
text: string;
localizedText: string;
handler: Function;
items: EbsActionHandler[];
id: string;
showLoading?: boolean;
autoClose?: boolean;
constructor(options: IEbsActionHandlerOptions);
}
| Property | Type | Description |
|---|---|---|
| iconClass | string | CSS class of the action handler's icon. |
| text | string | Text displayed on the action handler icon or the name of a localization resource. |
| localizedText | string | Action handler text label localized in the platform's current language. |
| handler | Function | Function that executes the action handler's action. |
| items | EbsActionHandler[] | Children action handlers that the user can select from the current action handler. |
| id | string | Unique identifier of the action handler. |
| showLoading (optional) |
boolean | Deprecated. |
| autoClose (optional) |
boolean | Deprecated. |
Use the IEbsActionHandlerOptions interface as a constructor signature for EbsActionHander objects. E.g.:
const dummySaveHandler = new EbsActionHandler({
iconClass: "icon-save",
text: "Save",
handler: () => {
console.log("Document saved!");
}
});
IEbsActionHandlerOptions
Constructor signature for the EbsActionHandler class.
interface IEbsActionHandlerOptions {
iconClass: string;
text: any;
handler: Function;
items?: EbsActionHandler[];
}
| Property | Type | Description |
|---|---|---|
| iconClass | string | CSS class of the action handler's icon. |
| text | string | Text displayed on the action handler icon or the name of a localization resource. |
| handler | Function | Function that executes the action handler's action. |
| items | EbsActionHandler[] | Children actions handlers that the user can select from the current action handler. |
IEbsGridOptions
Grid customizations.
interface IEbsGridOptions {
showInsertButton?: boolean;
selectionMode?: "single" | "multiple";
allowEdit?: boolean;
showColumnHeaders?: boolean;
showFilterRow?: boolean;
editMode?: "cell" | "row" | "batch" | "form" | "popup";
scrollHorizontal?: boolean;
pageSize?: number;
renderToolbar?: Function;
refreshMode?: "full" | "reshape" | "repaint";
noDelete?: boolean;
noInsert?: boolean;
noRefresh?: boolean;
noExport?: boolean;
}
| Property | Type | Description |
|---|---|---|
| showInsertButton (optional) |
boolean | Displays a button to insert new records to the grid. |
| selectionMode (optional) |
string |
|
| allowEdit (optional) |
boolean | Allows users to edit the records displayed in the grid. |
| showColumnHeaders (optional) |
boolean | Displays column headers at the top of the grid. |
| showFilterRow (optional) |
boolean | Displays filtering fields at the top of the grid. |
| editMode (optional) |
string | If the grid allows users to edit the displayed records, determines how the records will be edited:
|
| scrollHorizontal (optional) |
boolean | Allows to grid to scroll horizontally. Useful for grids with many columns. |
| pageSize (optional) |
number | Maximum number of records displayed on a grid page. |
| renderToolbar (optional) |
Function | Callback function used to personalize the toolbar’s rendering. This callback is invoked during toolbar initialization, allowing you to override or extend the default toolbar content. |
| refreshMode (optional) |
string |
|
| noInsert (optional) |
boolean | Prevents the inserting of new grid records. |
| noRefresh (optional) |
boolean | Prevents grid refreshing. |
| noExport (optional) |
boolean | Prevents exporting of grid data. |
Examples
In this example, we edit the page template of a form driven flow to include a button called viewCustomers. When clicking the button:
- We display a custom list in the gridContainer HTML element.
- The list includes the firstName and lastName attributes of the customers entity. (The fetch also retrieves the entity's primary key customersid which is not displayed in the list.)
- We set the list height to 400px.
- When the list is displayed, we use the callback function to log the Grid generated successfully message in the browser's console.
$('#viewCustomers').on('click', function (event) {
ebs.generateGrid('gridContainer', {fetch: {
entity: {
name: "customers",
alias: "a",
attributelist: [{
name: "customersid",
alias: "aPK"
},{
name: "firstName",
alias: "aFirstName",
},{
name: "lastName",
alias: "aLastName"$('#viewCustomers').on('click', function (event) {
ebs.generateGrid('gridContainer', {
fetch: {
entity: {
name: "customers",
alias: "a",
attributelist: [
{
name: "customersid",
alias: "aPK"
},
{
name: "firstName",
alias: "aFirstName"
},
{
name: "lastName",
alias: "aLastName"
}
]
}
}
}, '400px', null, function () {
console.log("Grid generated successfully.");
});
});
}
]
}
}},'400px',null,function(){console.log("Grid generated successfully.");});
});
In this example:
- We define a custom view called myCustomView based on the Supergrid view. If the view is not available, the custom view will fall back to the backupFetch fetch.
- We define an array of action handlers called actionHandlers containing a refresh button called refreshBtn and a button to delete the current selection called deleteBtn.
- The delete button uses the ebs.callActionByNameAsync function to call the deleteSelectedRows endpoint which allows you to delete records based on their IDs.
- We generate a grid inside the divHtmlId element using the above custom view and action handers.
- The height of the grid is set to auto.
- Rendering the grid triggers the afterGenerateCallback function.
- Users can select grid records a single row at a time.
// Create a backup fetch in case the desired entity view is missing.
var backupFetch = {};
backupFetch.entity = {};
backupFetch.entity.name = entityName;
backupFetch.entity.alias = 'a';
backupFetch.entity.join = [{
"type": "left",
"entity": {
"alias": "i",
"name": "BWStatus",
"attributelist": [{
"name": "label",
"alias": "StatusName"
}]
},
"fromto": [{
"from": "businessStatusId",
"to": "BWstatusid"
}]
}];
backupFetch.where = {
type: "and",
expressionlist: [{
type: "and",
conditionlist: [{
type: "equals",
first: "a.masterAttributeId",
second: "val(" + masterId + ")"
}]
}]
};
// Define the fetch object based on the Supergrid view.
// If the Supergrid view is missing, it will fall back to the backupFetch.
var myCustomView = {};
myCustomView.viewName = 'Supergrid';
myCustomView.fetch = backupFetch;
// Define the action handlers.
var actionHandlers = [];
// Define the refresh action handler.
var refreshBtn = new EbsActionHandler({
iconClass: 'dx-icon-refresh',
text: 'Refresh',
handler: function() {
return ebs.reload()
}});
actionHandlers.push(refreshBtn);
// Define the delete selection action handler.
var deleteBtn = new EbsActionHandler({
iconClass: 'dx-icon-close',
text: 'Delete Selection',
handler: function() {
var grid = getJQbyId(gridHtmlId).dxDataGrid('instance');
var selectedIds = grid.getSelectedRowKeys();
var noOfSelectedRows = selectedIds.length;
if (noOfSelectedRows == 0){
ebs.showMessage('No row selected.')
} else {
ebs.callActionByNameAsync('deleteSelectedRows', {rowsToBeDeleted:selectedIds})
.then(function(e){
ebs.showMessage('Records deleted.', {type:'success'})
})
.catch(function(e){
ebs.showMessage('Error!', {type:'error'})
});
}
}});
actionHandlers.push(deleteBtn);
// Generate the grid
ebs.generateGrid(divHtmlId, myCustomView, 'auto', actionHandlers, afterGenerateCallback, {
selectionMode: 'single'
});