Intersoft WebGrid Documentation
Server-side Events
See Also Send comments on this topic.
Intersoft WebGrid > WebGrid Features Overview > Programming with Server-side API > Server-side Events

Glossary Item Box

WebGrid is implemented with full extensibility and customization as its key design consideration. The WebGrid is specifically designed to be consumed by enterprise web applications that require extensibility to meet complex business requirements.

WebGrid allows you to handle specific events from both client and server side.

Server Events

The following is the list of server-side events:

For more information and walkthroughs on implementing the server events, see Walkthrough Topics. 

Event Sequences of Server-side Events

There are many events in WebGrid, for example InitializeLayout, InitializeDataSource, PrepareDataBinding, etc. The purpose of this article is to give better explanation about which parts of codes are better placed in certain events and also the sequence of the events when they are executed during the first time the page is loaded.

The events sequence ordering in WebGrid are (During Not On The FlyPostBack):

  1. WebGrid_ PreInitialize
  2. WebGrid_Initialize
  3. Page_Load : Event loading of the current page
  4. WebGrid_InitializeLayout : Layout initialization such as assigning static behavior, appearance and styles
  5. WebGrid_InitializeDataSource : Data source initialization
  6. WebGrid_PrepareDataBinding : Column structure retrieval and creation of necessary objects
  7. WebGrid_Load : Indication of successfully preparation of data binding process and data populating in all rows
  8. <<ServerControl Events>> - if Page.IsPostBack: Execution of server control events such as Button1_Click
  9. Page_PreRender
  10.   ...
  11. WebGrid_Load 
  12. WebGrid_PreRender
  13.   ...
  14. Page_SaveViewState
  15. Page_Render
  16.   ...
  17. WebGrid_InitializeTable
  18. WebGrid_InitializeColumn
  19. WebGrid_InitializeRow
  20. WebGrid_InitializeCell
  21. ...
  22. WebGrid_Unload

The events sequence ordering in WebGrid are (During On The Fly PostBack):

  1. WebGrid_PreInitialize : Control initialization
  2. WebGrid_Initialize
  3. Page_Load : Event loading of the current page
  4. WebGrid_InitializeLayout : Layout initialization such as assigning static behavior, appearance and styles
  5. WebGrid_InitializeDataSource : Data source initialization
  6. WebGrid_PrepareDataBinding : Column structure retrieval and creation of necessary objects
  7. WebGrid_Load : Indication of successfully preparation of data binding process and data populating in all rows
  8. WebGrid_InitializePostback
  9. WebGrid_Unload

WebGrid_PrepareDataBinding process preceeds the WebGrid_Load process so that all data has been populated and can be accessed further in WebGrid_Load event. WebGrid_PrepareDataBinding process succeeds the WebGrid_Load process and that caused many limitation because certain objects can not be accessed effectively in any of page's events.

In ordinary ASP.NET control lifecycle methodology, the server events are always fired after Page_Load event. The purpose is obviously to allow access to all objects which should have been loaded during Initialization and Load event. The WebGrid now has followed this methodology which can be seen from the current events sequence.

In this topic, certain important events will be explained extensively in order to give a good programming style of where to place certain codes in proper events in WebGrid. The advantage of following this style is to utilize the advantages of WebGrid component extensively such as data caching feature is enabled if the assignment of WebGrid data source is placed in InitializeDataSource event.


All codes related to the assignment of data source to the WebGrid component should be placed here. Since in this event, an instance of DataSourceEventArgs can be obtained, so the assignment code should be :

e.DataSource = DSName;  // --> instead of WebGrid1.DataSource = DSName;

Avoid assigning the DataSource property to the Grid object such as WebGrid.DataSource = DSName, since in the InitializeDataSource event, developers could obtain an object of DataSourceEventArgs here using e.

Code that related to the DataTable structure creation, DataSet populating process with the DataAdapter and so many data related task could be processed here. In the conclusion, only data populating related codes should be placed here, no process of assigning WebGrid layout should be placed as depicted from the event name (InitializeDataSource)

What are the differences between DesignTime binding and Runtime Binding? DesignTime binding is used when the DataSource is relatively static and can be obtained at the design time without needing the web application to be run first. In example showing the Customers table in the grid. Runtime binding is a more complex scenario when the DataSource can't be obtained at Design Time and the grid needs to wait for users' selection in order to select which particular data source needs to be binded to the grid. For examples, a dropdownlist will show a list of tables to the users. The grid will be in invisible mode until users select a table from the dropdownlist. In this scenario, obviously it's not possible to bind a certain data source to the grid, so the solution is by waiting for a button_click event (for example) in order to switch the data source.

Since the server control events will be invoked after the grid's events, then developers need to invoke ClearCachedDataSource() along with RebindDataSource() in order to force the grid to invoke the InitializeDataSource event again. Afterward, developers could programmatically switch the data source to be binded to the grid according to users selection.

If the data source can't be decided at page_load then it is necessary to assign null to the grid's data source such as this : grid.DataSource = null; otherwise a classic error message will be produced such as this "Please set WebGrid1's datasource e.g. WebGrid1.DataSource = NorthWindLookups.GetProductList();"

WebGrid has successfully binded its DataSource which defined using e.DataSource. In this event, developers can conveniently populate all the columns structure. There are many cases that developers often forgot to place all "object creation" codes under !IsPostBack condition, so please remember to place WebGrid1.RetrieveStructure() or WebGrid1.RetrieveHierarchicalStructure() under !IsPostBack condition. There are cases such as users has utilized resizing columns, sorting and grouping features and invoked PostBack to the server, but after the PostBack all the features applied are overrided back to the first configuration erasing all features that have been applied.

When the InitializeDataSource event is invoked and the codes inside the InitializeDataSource event are executed, WebGrid will proceed to invoke the PrepareDataBinding event automatically. If there is no single codes to be executed in the InitializeDataSource, then the grid will simply skip the PrepareDataBinding event.

There are some cases that developers would like to invoke InitializeDataSource event in order to assign a new DataSource to the WebGrid in the certain events such as Button1_Click event. The solution for that case is by simply invoking WebGrid1.ClearCachedDataSource() to remove all cached DataSource and proceed by invoking WebGrid1.RebindDataSource(). Whenever RebindDataSource method is invoked, WebGrid will automatically reinvoke InitializeDataSource event, so the concept of centralized DataSource initialization still persist.

Another issue is about the difference between using old tradition DataBind compared to using RebindDataSource in version 3.5. The data binding process can be processed only once in the internal processing. In order to overcome that limitation, a new method called RebindDataSource is introduced in order to invoke the InitializeDataSource event once again, but it is under one condition that ClearCachedDataSource is invoked first before invoking RebindDataSource, otherwise RebindDataSource will only invoke PrepareDataBinding event because there is a cache maintained inside the WebGrid.

InitializeLayout event is originally designed to let developers programmatically configure static WebGrid's behavior, appearance, look and feel, styles etc. It is quite easy to configure the layout by just using e.Layout , since in this event developers could obtained the LayoutSetting properties from LayoutEventArgs. No dynamic objects or data related settings should be placed here especially if those objects are created during runtime.

This event is also an important event in order to modify the grid's layout and styles. All the layout settings could be configured and persisted here while it will be ignored at other events. Pay attention to the events sequences for developers who use Runtime Binding. Since the InitializeLayout event will be called before InitializeDataSource event and PrepareDataBinding event, then it won't be possible for grid to obtain the tables' name and columns' name. Try to reference this : WebGrid1.RootTable.Columns.GetNamedItem("CustomerID").CellStyle.HorizontalAlign = HorizontalAlign.Center, then developers will get the "Object Error", because the tables and columns population are created using either RetrieveStructure() or RetrieveHierarchicalStructure() at PrepareDataBinding. So what's the solution then ?

The solution is by manually configuring the root table and its child tables along with all columns at InitializeLayout event, such as this :

C# Copy Code 
protected void WebGrid1_InitializeLayout(object sender, ISNet.WebUI.WebGrid.LayoutEventArgs e)
{
  WebGrid1.RootTable = null;
  WebGrid1.RootTable.Columns.Clear();
  WebGrid1.RootTable.ChildTables.Clear();
  WebGrid1.RootTable.DataMember = "Customers";
  WebGrid1.RootTable.DataKeyField = "CustomerID";
  foreach(string col in UseProfileRoot)
  {
     WebGrid1.RootTable.Columns.Add(new WebGridColumn(col, col, col));
  }

  WebGridTable childTable = new WebGridTable();
  childTable.DataMember = "Orders";
  childTable.DataKeyField = "OrderID";
  foreach(string col in UseProfileChild)
  {
     childTable.Columns.Add(new WebGridColumn(col, col, col));
  }
  WebGrid1.RootTable.ChildTables.Add(childTable);
}

For developers who use Runtime Binding, make sure that the RootTable is null along with its child tables and also all columns, in order to avoid the clash between old data source and the new data source. The sign of conflict can be seen when the project is running and producing "The assign column 'ColumnName' can't be found in the DataSource"

All the events ordering explained above are only applied during the first time the page is loaded and also during "normal" PostBack condition. It is not applied during OnTheFly PostBack. The reason behind that is because WebGrid is developed to avoid duplication calling of those all events. The duplication calling is avoided because the "action" against a request could be only performed after WebGrid_Load event. That is one reason why WebGrid PostBack process is much faster compared to the other conventional server controls.

The following sections explain the comparison between conventional server postback and WebGrid's postback process.

Conventional Server Control PostBack Process

  1. Init
  2. RestoreViewState (All objects are restored in this point which makes the process slow, in example 500 records of rows)
  3. Load
  4. RaisePostBackEvent (All objects are recreated again due to DataBinding process in order to response an action)

WebGrid OnTheFlyPostBack Process

  1. Init
  2. RestoreViewState (Only restore dynamic objects and modified objects, no data population here, so there would be no problem even there are 1000 records)
  3. Load
  4. RaisePostBackEvent (Invoke InitDataSource  or obtain from cache if data is cached and call other required events), continue to populate data according to user's action)

As can be seen from the comparison table, RestoreViewState process is extremely fast here (1 point), FlyPostBackHandler will use cached data (AutoDataCache feature - 1 point) and finally all data are populated directly based on user's action (1 point). So in the conclusion WebGrid is 3x times faster compared to conventional  server control.

See Also

©2012 Intersoft Solutions Corp. All Rights Reserved.