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

Glossary Item Box

This topic provides an overview of Server-side API in WebGrid.

This topic contains the following sections:

Understanding Server-side Events

WebGrid design is to enable seamless interactions between client and server. In previous version, many tasks become difficult to be implemented because the limitation of the architecture. The new version’s improvements in the core architecture now allow you to perform client tasks easily. 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.

For more information, see Server-side Events.

 

Create WebGrid in Server-side programmatically

With the provided server-side events, you can also create WebGrid in server-side programmatically. You can also apply the settings and structure in server-side events.

For more information, please read How-to: Create WebGrid in Server-Side programmatically.

 

Working with Client Action

ClientAction is another great improvement to the OnTheFlyPostback architecture. This object is attached per grid instance and designed to bridge the gaps between client and server. It enables predefined client actions to be executed directly from server code during OnTheFly Postback, therefore avoiding writing unnecessary client-side codes.

This powerful and easy-to-use feature also allows you to invoke your own client function directly from the server codes, remove many erroneous which is time consuming.

For more information, see ClientAction Engine overview.

 

ClientAction Engine

ClientAction is another great improvement to the OnTheFly Postback architecture. This object is attached per grid instance and designed to bridge the gaps between client and server. It enables predefined client actions to be executed directly from server code during OnTheFly Postback, therefore avoiding writing unnecessary client-side codes.

This powerful and easy-to-use feature also allows you to invoke your own client function directly from the server codes, remove many erroneous which is time consuming.

There are two types of predefined client actions, one is in global scope, means that it does not require grid's instance, for example, Alert, NavigateTo, OpenWindow and so on. The other is in grid's scope, such as Refresh, SetFocus, SetStatus and so on. These kind of actions can also be applied to different grid instance, for example, you can call WebGrid2.ClientAction.Refresh() while the grid performing OnTheFly Postback is WebGrid1. This capability will enable you to create any types of interactive web applications easier than ever before.

Scenario 1 - Display messagebox to user if UpdateRow can't be done for specific case

C# Copy Code 
private void WebGrid1_UpdateRow(object sender, ISNet.WebUI.WebGrid.RowEventArgs e)
{
    if (e.Row.Cells.GetNamedItem("Country").Text == "UK")
    { 
        // Display alert to user 
        WebGrid1.ClientAction.Alert("You can't update this row!");
        DataRowView drv = (DataRowView)e.Row.DataRow;
        drv.Row.RejectChanges();
        e.ReturnValue = false;
    }
}

In previous version, you could also achieve above scenario but with more codes and efforts. You have to implement OnAfterResponse client side event and write the function to check for many cases in the Onafterresponse event in order to achieve one easy task.

Scenario 2 - Refreshing second grid after invoking send custom request of first grid

C# Copy Code 
private void WebGrid1_InitializePostBack(object sender,
ISNet.WebUI.WebGrid.PostbackEventArgs e)
{
    if (e.Action == PostBackAction.Custom) 
    {
        // perform business logic here
        WebGrid2.ClientAction.Refresh();
    }
}

As you can see, you only need one code to perform refresh to Grid2. The ClientAction is able to perform "cross-grid" operation like in the above scenario where the grid in context (WebGrid1) is different with grid to refresh (WebGrid2). In previous version, you need to implement wgCustomActionResponse clientside event to parse the Xml result and then call the grid2's refresh client API to perform the refresh. With the ClientAction, wgCustomActionResponse is no longer required although the mechanism is still available to use.

Scenario 3 - Navigate to specific page after record addition

C# Copy Code 
private void WebGrid1_AddRow(object sender, ISNet.WebUI.WebGrid.RowEventArgs e)
{
    if (e.Row.Cells.GetNamedItem("Status").Text = "0")
    {
        oleDbDataAdapter1.Update();
        WebGrid1.ClientAction.NavigateTo("StatusForm.aspx?UserId=" +
            e.Row.Cells.GetNamedItem("UserId").Value.ToString());
    }
}

The ClientAction engine is designed to "bridge" client and server interactions to produce transparent and smooth result without having to write codes in client side. The ClientAction works in conjunction with OnTheFly Postback technology

 

Preserving checked/selected rows on FlyPostBack actions

Now that WebGrid has two ways to allow users to perform multiple row selection. The first is using IsRowChecker feature which is introduced back in WebGrid version 4.0. The latter one is using Multiple Row Selection, which is a new feature in this release.

One important requirement related to the multiple row selection is the ability to persist the checked/selected rows between postbacks and AJAX callbacks (FlyPostBack). This requirement is especially useful when used in conjunction with Classic Paging feature. Users will then be able to check some rows in a page, moving to another page or perform sorting and check some more rows, and finally submit all checked/selected rows to server. The previous version of WebGrid already includes a function called PersistRowChecker to persist checked rows on postback. It is, however, applies only to Full Postback.

New to WebGrid 6.0 in this second 2008 release is the new feature to automatically preserve checked/selected rows on both FullPostBack and FlyPostBack. With this feature, users can now preserve the previously checked rows while performing other actions such as moving to other pages, grouping, sorting, and filtering and so on. Furthermore, WebGrid will mark back the checked rows when it found the previously checked rows in the page. It will also restore the checked selection so that users can easily notice on checked rows.

The checked rows are now automatically restored after FlyPostBack™ actions.


The setting to enable this feature is controlled by RestoreRowSelection property inside the LayoutSettings property of WebGrid. This property has 4 possible values:

 

Preserving expanded child rows

WebGrid 6.0 in this new release includes a nice enhancement to preserve expanded child rows automatically. A new property named RestoreExpandedChildRows is now added to the LayoutSettings.

When enabled, WebGrid automatically tracks the child rows that end users expanded during user interaction. Next, when users performed any FlyPostBack™ actions - such as sorting, refresh, filtering, etc - WebGrid will restore any matching child rows that expanded previously. This long-awaited enhancement is also applicable to any level of nested tables.

To enable this feature, simply set RestoreExpandedChildRows property to true value.

See Also

©2012 Intersoft Solutions Corp. All Rights Reserved.