This project is read-only.

vpGrid Events

vpGrid has its own set of events.

Registering to vpGrid event handlers is the basic technic to fully customize the grid to match all your business requirements.

If you cannot implement your business requirement, this means vpGrid is missing the right Event. In that case, use the discussions page to ask for this event in the next release.

To register your handler to a vpgrid event, use the following syntax in your Javascript file:

onCellValidatingEventhandler = function (source, eventArgs) {
try {

} catch (e) {
vpGrid.logException(e);
}
}
vpGrid.registerEventHandler(vpGrid.Event.onCellValidating, onCellValidatingEventhandler);

In the above sample code, you register your handler called onCellValidatingEventHandler to the vpGrid event called onCellValidating

vpGrid has a public interface that you can use in your own event handlers. This interface gives you access to a method called vpGrid.logException(). This method enables to trace any exception and its context into the browser console (The browser console is available when typing F12). In next release it will be possible to send all client-side errors and exceptions to the server.

vpGrid events  have been designed in the same way as events in the .Net Framework. Inside the vpGrid library events are always raised through a method that has the same name as the event.

Evant handlers have always the same signature : function (source, eventArgs) where source is the source of the event (generally a DOM element) and where eventArgs holds any properties that are usefull for the event handler to make a business decision.

Event names follow the same pattern as in the .Net Framework.

Events postfixed by ing are raised before the action is done by vpGrid. For these type of events the eventArgs may contain a cancel property. By setting the cancel property to true, the event handler can stop the action. If the event handler wants to stop the action, he should also set the cancelReason property to explain the user why he(she) cannot do the action.

Events postfixed by ed are raised after the action has been done by vpGrid. Event handlers uses these events to do post processing for the corresponding event.

 You can listen to any of these events:

 

 vpGrid.Event.onDataReceived = "onDataReceived";
//This event is raised when the response data has been received from remote server.
//this event enables to change the received data before loading it in the grid.
//for example the server might sent "compressed data" or "unreadable" data to optimize security and bandwidth
//this event enables listener to transform a non readable received data into a meaningfull data.
//Listeners might also add or remove any data to or from the received data.
//Event handler must have the following signature : function(source, eventArgs)
//the eventArgs parameter has the following signature :
// eventArgs = {
// data: [{col1:xxx, col2:yyy, ... colN:zzz}, ...]
// };
// The data property of the eventArgs object is an array of objects. Each object in the array represent a row in the grid.
// The property names of these objects must be the name of an existing column in the grid.


vpGrid.Event.onUpdatedDataReceived = "onUpdatedDataReceived";
//This event is raised when the response data has been received from remote server due to a data update on server-side.
//this event enables to do any post processing on updated data
//for example the caller might upload files or do any ajax request on the real updated data
//The listener must not change any data embeded in the eventArgs object
//Event handler must have the following signature : function(source, eventArgs)
//the eventArgs parameter has the following signature :
// eventArgs = {
// sentData: {col1:xxx, col2:yyy, ... colN:zzz, extraData1:ttt, extraData2:uuu, ..., extraDataN:www}, -> Data sent to the server to make the server-side update
// receivedData: {col1:xxx, col2:yyy, ... colN:zzz}, -> Data sent back by the server after the server-side update operation
// keyName: -> name of the key that identifies the entity on server side
// keyValue: -> value of the key
// };
// The sentData property of the eventArgs object represents the client-side updated row in the grid.




vpGrid.Event.onInsertedDataReceived = "onInsertedDataReceived";
//This event is raised when the response data has been received from remote server due to a data insert on server-side.
//this event enables listeners to do any post processing on inserted data
//for example the caller might upload files or do any ajax request on the real inserted data
//The listener must not change any data embeded in the eventArgs object
//Event handler must have the following signature : function(source, eventArgs)
//the eventArgs parameter has the following signature :
// eventArgs = {
// sentData: {col1:xxx, col2:yyy, ... colN:zzz, extraData1:ttt, extraData2:uuu, ..., extraDataN:www}, -> Data sent to the server to make the server-side insert
// receivedData: {col1:xxx, col2:yyy, ... colN:zzz}, -> Data sent back by the server after the server-side insert operation
// keyName: -> name of the key that identifies the entity on server side
// keyValue: -> value of the key of the new inserted entity
// };
// The sentData property of the eventArgs object represents the client-side inserted row in the grid.
// The listener should not modify the eventArgs.receivedData content.




vpGrid.Event.onInsertingDataOnRemote = "onInsertingDataOnRemote";
//This event is raised when a data row is about to be sent to the remote server for an INSERT operation
// This event enable listeners to cancel this CRUD operation upon specific business rules
// (for example the row has content but is empty in terms of business data)
//Event handler must have the following signature : function(source, eventArgs)
//the eventArgs parameter has the following signature :
// eventArgs = {
// data: data, -> literal object that holds the data that will be sent to the server
// cancel : false|true (false by default)
// cancelReason : ""
// };
// The event handler can inspect the data object, can modify it, can add properties
// To prevent the data to be sent, the event handler must set the cancel property to true.
// Optionnaly the event handler should set a message to tell the user why this data should not be sent to server




vpGrid.Event.onUpdatingDataOnRemote = "onUpdatingDataOnRemote";
//This event is raised when a data row is about to be sent to the remote server for an UPDATE operation
// This event enable listeners to cancel this CRUD operation upon specific business rules
// (for example the row has content but is empty in terms of business data)
//Event handler must have the following signature : function(source, eventArgs)
//the eventArgs parameter has the following signature :
// eventArgs = {
// data: data, -> literal object that holds the data that will be sent to the server
// cancel : false|true (false by default)
// cancelReason : ""
// };
// The event handler can inspect the data object, can modify it, can add properties
// To prevent the data to be sent, the event handler must set the cancel property to true.
// Optionnaly the event handler should set a message to tell the user why this data should not be sent to server



vpGrid.Event.onDeletingDataOnRemote = "onDeletingDataOnRemote";
//This event is raised when a data row is about to be sent to the remote server for a DELETE operation
// This event enable listeners to cancel this CRUD operation upon specific business rules
// (for example the row has content but is empty in terms of business data)
//Event handler must have the following signature : function(source, eventArgs)
//the eventArgs parameter has the following signature :
// eventArgs = {
// data: data, -> literal object that holds the data that will be sent to the server
// cancel : false|true (false by default)
// cancelReason : ""
// };
// The event handler can inspect the data object, can modify it, can add properties
// To prevent the data to be sent, the event handler must set the cancel property to true.
// Optionnaly the event handler should set a message to tell the user why this data should not be sent to server


vpGrid.Event.onDataInsertedUpdatedDeletedOnRemote = "onDataInsertedUpdatedDeletedOnRemote";
//This event is raised when when all CRUD operations have been performed by the grid
// This event enable listeners to do post processing only when all the INSERT/UPDATE/DELETE have been done.
// (for example reloading the grid)
//Event handler must have the following signature : function(source, eventArgs)
//the eventArgs parameter has the following signature :
// eventArgs = {
// -> eventArgs does not need to have any content for this event
// };




vpGrid.Event.onCellRendering = "onCellRendering";
//This event is raised when a cell is rendering and jqGrid is about to render the <td> cell container.
//this event enables to setup the html attributes of the <td> cell container.
//You cannot set the <td> html content with this event.
//Event handler must have the following signature : function(source, eventArgs)
//the eventArgs parameter has the following signature :
// eventArgs = {
// cellName: cellname,
// cellValue: value,
// rowData: data,
// td : {}
// };
// The event handler can set the eventArgs.td literal object with properties corresponding to html attributes.
// for example : eventArgs.td.title = 'xxx', eventArgs.td.class = 'myclass', eventArgs.td.style="xxx'



vpGrid.Event.onSummaryCellRendering = "onSummaryCellRendering";
//This event is raised when a summary cell is rendering.
//this event enables to setup the value of the summary cell and also the html attributes of the <td> cell container.
//Event handler must have the following signature : function(source, eventArgs)
//the eventArgs parameter has the following signature :
// eventArgs = {
// cellName: cellname,
// cellValue: value,
// useCellFormatter : false,
// uiIdentifier : xxxx -> value of the data tag data-vpgrid-ui-id
// td : {},
// remove :{}
// isAsync: true -> this event is async. you cannot revert it back to be synchronous
// asyncInit : function(){} -> call this method at the beginning of your event handler
// asyncEnd : function(){} -> call this method when your event handler has finished its task (be it asynchronous or synchronous)
// };
//
// The event handler can set the eventArgs.td literal object with properties corresponding to html attributes.
// The uiIdentifier property enables listener to know on which summary row he is called:
// if there is only one summary row (this is the default): uiIdentifier=""
// if there are more than one summary row: uiIdentifier = "SumarryRowN" where N = 1,2,3, ...
// If existing attributes or classes must be removed, the event handler should fill the remove property.
// For example, to remove the ui-state-error class on the td : remove.class='ui-state-error'.
// for example : eventArgs.td.title = 'xxx', eventArgs.td.class = 'myclass', eventArgs.td.style="xxx'
// The Event handler should also setup the cellValue property. This value will be rendered in the cell summary.
// If cellValue must be rendered in the same format as other cells in the column, the event handler should explicitely set the useCellFormatter property to true.



vpGrid.Event.onSelectCellRendering = "onSelectCellRendering";
//This event is raised when a cell is in edit mode and needs to be rendered as a select statement <select>...</select>
//Event handler must have the following signature : function(source, eventArgs)
//the eventArgs parameter has the following signature :
// eventArgs = {
// cellName: cellname,
// cellValueBeforeEditing: value,
// rowData: data,
// selectOptions : []
// };
// The event handler should fill the eventArgs.selectOptions with literal objects of type : { key : xxx, value : yyy} (a collection of key/value pairs)
// if there is no listener or if listener(s) does nothing, the selectOptions array will be be automatically filled with all distinct values of the column.



vpGrid.Event.onAutocompleteCellRendering = "onAutocompleteCellRendering";
//This event is raised when a cell is in edit mode and needs to be rendered as an input statement <input>...</input> with autocomplete bound to it.
//Event handler must have the following signature : function(source, eventArgs)
//the eventArgs parameter has the following signature :
// eventArgs = {
// cellName: cellname,
// cellValue: value,
// options : {}, -> options parameter of autocomplete jquery-ui
// data: [],
// rowData: data
// };
// The event handler should fill the eventArgs.data array with strings. This array will be bound to autocomplete.
// if there is no listener or if listener(s) does nothing, the data array will be be automatically filled with all distinct values of the column.



vpGrid.Event.onImageCellRendering = "onImageCellRendering";
//This event is raised when a cell is in display mode and needs to be rendered as an image statement <img>...</img>



vpGrid.Event.onLinkCellRendering = "onLinkCellRendering";
//This event is raised when a cell is in display mode and needs to be rendered as a link statement <a>...</a>
//Event handler must have the following signature : function(source, eventArgs)
//the eventArgs parameter has the following signature :
// var eventArgs = {
// cellName,
// cellValue,
// rowData: data,
// a: {
// href: cellValue,
// title: cellValue,
// target: target,
// },
// html: linkContent
// };
// The event handler can set the eventArgs.a literal object with properties corresponding to html attributes.
// The event handler can set the eventArgs.html to the string that will be rendered as a link.
// The event handler must not change eventArgs.cellName, eventArgs.cellValue and cellValue.rowData.



vpGrid.Event.onCellValidating = "onCellValidating";
//This event is raised when a cell is in edit mode and needs to be validated through custom validation
//Event handler must have the following signature : function(source, eventArgs)
//the eventArgs parameter has the following signature :
// eventArgs = {
// cellName: cellname,
// cellValue: value, -> cellValue is always a string
// cellNativeValue : cellValue converted to the column schema data type (only works for numbers at the moement)
// rowData: -> literal object that contains all cells in the selected row (Inline Cell Editing): {col1:xxx, col2:yyy, ... colN:zzz}
// dialogData, ->literal object that contains all input fields in the jQuery-UI Dialog window (Form Editing) : {col1:xxx, col2:yyy, ... colN:zzz}
// dialogId, -> vpGrid Id of the jQuery-UI Dialog representing the input Form
// isValid : true,
// errorMessage : 'xxx'
// };
// The event handler should set the eventArgs.isValid property to false and the eventArgs.errorMessage property if custom validation fails.



vpGrid.Event.onCellUpdating = "onCellUpdating";
// This Event is raised when a cell is in edit mode and the underlying data is about to be updated.


vpGrid.Event.onCellUpdated = "onCellUpdated";
//This event is raised when a cell has been updated on client-side (after its content has been edited)
//Event handler must have the following signature : function(source, eventArgs)
//the eventArgs parameter has the following signature :
// eventArgs = {
// cellName, -> name of the cell that has been edited
// cellValue, -> value of the edited cell
// rowid, -> id of the HTML table row that holds the updated cell
// rowData -> literal object that contains all cells in the row : {col1:xxx, col2:yyy, ... colN:zzz}
// };
// The event handler uses eventArgs properties to make any additional processing on the grid.
// For example:
// - changing other cells of the same row by applying specific business rules.
// -> to change another cell, the event listener may set the rowData.colName property of the corresponding cell
// - updating the summary row by calling vpGrid.renderSummaryRows()




vpGrid.Event.onRowEditing = "onRowEditing";
//This event is raised when the user click on a row to edit a cell or to delete the row
// This event enable listeners to cancel any modification on the row when the user click on a cell for editing
//Event handler must have the following signature : function(source, eventArgs)
//the eventArgs parameter has the following signature :
// eventArgs = {
// rowid: id, -> HTML TR id of the clicked row
// rowData: data, -> literal object that holds the data of the clicked row
// cancel : false|true (false by default)
// cancelReason : ""
// };
// The event handler can inspect the rowData data object but cannot modify it
// To make the row readonly, the event handler must set the cancel property to true.
// Optionnaly the event handler should set a message to tell the user the row is read only.


vpGrid.Event.onCellEditing = "onCellEditing";
//This event is raised when the user click on a cell to edit its content
// This event enable listeners to prevent user to edit the clicked cell
//Event handler must have the following signature : function(source, eventArgs)
//the eventArgs parameter has the following signature :
// eventArgs = {
// rowid: id, -> HTML TR id of the clicked row
// rowData: data, -> literal object that holds the data of the clicked row
// cellName: xxx -> name of the cell clicked by the user
// cancel : false|true (false by default)
// cancelReason : ""
// };
// The event handler can inspect the rowData data object but cannot modify it
// To make the cell readonly, the event handler must set the cancel property to true.
// Optionnaly the event handler should set a message to tell the user why the cell is read only.



vpGrid.Event.onRowInserted = "onRowInserted";
//This event is raised when a row has been inserted in the grid.
// This event is raised when data is loaded from server and when data has been filtered/sorted in the grid.
//Event handler must have the following signature : function(source, eventArgs)
//the eventArgs parameter has the following signature :
// eventArgs = {
// rowid: id,
// rowData: data
// };
// The event handler uses eventArgs properties to make any additional processing on the grid.
// For example:
// - changing other cells of the same row by applying specific business rules.
// -> to change another cell, the event listener may set the rowData.colName property of the corresponding cell
// To add or update inline summary rows, you MUST use the onInlineSummaryRowRendering event


vpGrid.Event.onInlineSummaryRowRendering = "onInlineSummaryRowRendering";
//This event is raised when a row has been inserted in the grid.
// This event is raised when data is loaded from server, when data has been filtered/sorted in the grid.
// This event enable listeners to insert/update inline summary rows for the target row
//Event handler must have the following signature : function(source, eventArgs)
//the eventArgs parameter has the following signature :
// eventArgs = {
// rowid: id,
// rowData: data
// };
// The event handler uses eventArgs properties as input data to create or update an inline summary row.
// inline summary rows are created/updated using the public methods :
// vpGrid.insertInlineSummaryRowAfter,
// vpGrid.updateInlineSummaryRowAfter,
// vpGrid.insertInlineSummaryRowBefore,
// vpGrid.updateInlineSummaryRowBefore,


vpGrid.Event.onModalDialogClosing = "onModalDialogClosing";


vpGrid.Event.onModalDialogClosed = "onModalDialogClosed";
//Event raised when a modal dialog is closed.
//Event listener must have the signature function(source, eventArgs){}


vpGrid.Event.onModalDialogOpening = "onModalDialogOpening";
//This event is raised when a modal dialog is about to be opened
//Event handler must have the following signature : function(source, eventArgs)
//the eventArgs parameter has the following signature :
// eventArgs = {
// dialogId : '' -> vpgrid id of the modal dialog (enables the listener to know on which form he is called)
// dialogData : literal object that contains all column fields found in the form
// rowData : literal object that represent the select row in the Grid
// cancel : false|true (false by default)
// cancelReason : "",
// iframeUrl: url of the iframe
// };
// The event handler can inspect the dialogData data object but cannot modify it
// The event handler can do any additional processing (that do not need immediate rendering) on the jquery ui-dialog (for example doing some custom initialization)
// The event handler can prevent the dialog to open by setting the cancel property to true and by setting the cancelReason to a message explaining why the dialog cannot open.
// When this event is raised to open an external web page in an iframe, the event handler can change this url by setting the property iframeUrl.


vpGrid.Event.onModalDialogOpened = "onModalDialogOpened";
//This event is raised when a modal dialog is opened
//Event handler must have the following signature : function(source, eventArgs)
//the eventArgs parameter has the following signature :
// eventArgs = {
// dialogId : '' -> vpgrid id of the modal dialog (enables the listener to know on which form he is called)
// dialogData : literal object that contains all column fields found in the form
// };
// The event handler can inspect the dialogData data object but cannot modify it
// The event handler can do any additional processing (that do not need immediate rendering) on the jquery ui-dialog (for example doinf some custom initialization)


vpGrid.Event.onFormValidating = "onFormValidating";
//This event is raised when a form needs to be validated through a custom global validation
//Event handler must have the following signature : function(source, eventArgs)
//the eventArgs parameter has the following signature :
// eventArgs = {
// modalDialogId : '' -> id of the parent modal dialog (enables the listener to know on which form he is called)
// validationResult: validationResult, -> literal object that contains all column fields found in the form:
// validationResult["colname"]= {
// isValid: true -> set this property to false if business validation fails on this field
// message : 'put here the error message for the specified field'
// value : "xxxx" -> value entered by the user in the field (this value is always a string)
// }
// isValid: true
// };
// The event handler can inspect/modify the validationResult object
// The event handler should set the eventArgs.isValid property to false if custom validation fails.





vpGrid.Event.onFileuploading = "onFileuploading";
//This event is raised when a file is about to be uploaded
//Event handler must have the following signature : function(source, eventArgs)
//the eventArgs parameter has the following signature :
// eventArgs = {
// data : data, -> data object built by the jquery File Upload plugin
// formData: formData, -> literal Object that will be added in the POST Request
// cancel : false
// };
// The event handler can prevent the file to be uploaded by setting the cancel property to true.
// The event handler may send any additional data (key/value) to the server by extending the formData object.
// The event handler must not modify the data eventArgs.data object : modfying it is at your own risk.





vpGrid.Event.onUIElementDisabling = "onUIElementDisabling";
//This event is raised when a DOM element is about to be disabled in the UI
//Event handler must have the following signature : function(source, eventArgs)
//the eventArgs parameter has the following signature :
// eventArgs = {
// uiId: xxx , -> value of the data-vpgrid-ui-id attribute that has been setup on the element
// cancel: true|false -> default value is false

// };
// The event handler should set the eventArgs.cancel property to true if the DOM element should be enabled due to specific business rules.

vpGrid.Event.onUIElementEnabling = "onUIElementEnabling";
//This event is raised when a DOM element is about to be enabled in the UI
//Event handler must have the following signature : function(source, eventArgs)
//the eventArgs parameter has the following signature :
// eventArgs = {
// uiId: xxx , -> value of the data-vpgrid-ui-id attribute that has been setup on the element
// cancel: true|false -> default value is false
// selectedRowData : { } -> literal object that holds the data for the selected row (the row that is checked (first column) in jqGrid)
// If no row is checked, the selectRowData is null or is missing
// };
// The event handler should set the eventArgs.cancel property to true if the DOM element should be disabled due to specific business rules.



vpGrid.Event.onGridLoaded = "onGridLoaded";
//This event is raised when the Grid has received data and loaded it in jqGrid.
//this event enables listener to do post-processing on the UI when the grid has loaded its data.
//Event handler must have the following signature : function(source, eventArgs)
//the eventArgs parameter has the following signature :
// eventArgs = {
//
// };


vpGrid.Event.onUserInfoReady = "onUserInfoReady";
//This event is raised when the user info object has been constructed from the data requested to the server.
//this event enables to change or augment the userInfo object.
//Event handler must have the following signature : function(source, eventArgs)
//the eventArgs parameter has the following signature :
// eventArgs = {
// userInfo: {
// name : "name of the user",
// login : "login of the user",
// roles : ["role1", "role2", ...] -> string array that lists all roles the user is in.
// }
// };
//
// After this event is raised, the userInfo object is available at vpGrid.currentUser


vpGrid.Event.onGlobalInfoReady = "onGlobalInfoReady";
//This event is raised when the global info object has been constructed from the data requested to the server.
//this event enables to change or augment the globalInfo object.
//Event handler must have the following signature : function(source, eventArgs)
//the eventArgs parameter has the following signature :
// eventArgs = {
// globalInfo: {
// prop1 : xxxx,
// prop2 : yyyy
// }
// };
//
// After this event is raised, the globalInfo object is available at vpGrid.globalInfo

vpGrid.Event.onWindowClosing = "onWindowClosing";
//This event is raised when the user closes the browser window or when the user refreshes the web page (F5)
// This event enable listeners to cancel the closing operation upon specific business rules
//Event handler must have the following signature : function(source, eventArgs)
//the eventArgs parameter has the following signature :
// eventArgs = {
// data: data, -> literal object that holds the data that will be sent to the server
// cancel : false|true (false by default)
// cancelReason : ""
// };
// The event handler can inspect the data object, but MUST NOT modify it
// To prevent the window from closing, the event handler must set the cancel property to true.
// Optionnaly the event handler should set a message to tell the user why the window cannot be closed


vpGrid.Event.onDataRowValidating = "onDataRowValidating";
//This event is raised when a dataRow needs to be validated through a custom global validation
//Event handler must have the following signature : function(source, eventArgs)
//the eventArgs parameter has the following signature :
// eventArgs = {
// rowData: data, -> literal object that holds the data of a row
// isValid: true|false
// errors : [] -> array of objects containing all errors in the dataRow
// each object in the array must have the following signature:
// {
// propertyName : string -> name of a column/field
// message : string -> put here the error message for the specified column/field
// }
// };
// The event handler should set the eventArgs.isValid property to false if custom validation fails.
// If validation fails, the Event handler should push all error messages as object literals in the errors array

Last edited Nov 18, 2014 at 9:57 AM by HenridOrgeval, version 16