AJAX Details

In This Topic

All AJAX features of the Nevron web controls require Visual Studio 2005 or later and Microsoft .NET Framework 2 with ASP.NET AJAX Framework 1.0 or Microsoft .NET Framework 3+.

How to enable AJAX mode for Nevron web controls

To activate AJAX mode for Nevron web controls, change the value of the AjaxEnabled property to true.

By default Nevron AJAX web controls absorb all client-side JavaScript errors. This way the end-user of the AJAX-enabled Chart or Diagram control will not be disturbed by any accidental JavaScript error messages that may be caused by unexpected web browser problems.

To allow the error reporting please set the AjaxScriptBuild property of the web control to Debug. If there are multiple AJAX-enabled Nevron web controls on the same page, setting the AjaxScriptBuild property of only one of the controls to Debug will affect all controls.

Controller and Tools

When used in AJAX mode, Nevron web controls load the Nevron JavaScript Library to the client web browser. The Library implements the client side functionality required for user input to be intercepted, routed and handled at the server and feedback to be returned. It also implements pure client side interactivity.

The general patterns, used by Nevron web controls at the client, are: priority event pools; and controller and tools.

When a user input event is intercepted by the web browser and it is recognized as relevant to the web control, the event is first delivered to an event pool. If there is an event that is being processed at the moment, the new event is stored by the pool for delayed processing. Otherwise, the event is routed to the controller. The controller passes the event to all registered and enabled tools in a row. Every tool optionally adds one or more commands to a command queue and returns. Afterwards the commands are executed synchronously in the order they have entered the queue. Some commands may perform client-only actions, like displaying tooltips or redirecting the web browser. Other commands may invoke an AJAX callback server request and wait until the server responds or the request timeouts.

Tools can be initially configured at the server from the code behind. Also, tools can be added, removed, enabled or disabled at the client from custom JavaScript code.

For usage details, please refer to the AJAX web examples that are installed by the Nevron .NET Vision installation.

Also, a good source of information is the Nevron AJAX How To topic, included later in this chapter.

Asynchronous callbacks for client-side mouse events

The following tools can be used to implement existing or custom interactivity:

NAjaxMouseClickCallbackTool (client side JavaScript class: NMouseClickCallbackTool) – intercepts the click event and routes it to the server for processing; handle the AsyncClick server side event of the web control to process client side clicks
NAjaxMouseDoubleClickCallbackTool (client side JavaScript class: NMouseDoubleClickCallbackTool) – intercepts the double click event and routes it to the server for processing; handle the AsyncDoubleClick server side event of the web control to process client side double clicks
NAjaxMouseDownCallbackTool (client side JavaScript class: NMouseDownCallbackTool) – intercepts the mouse down event and routes it to the server for processing; handle the AsyncMouseDown server side event of the web control to process the client side mouse down event
NAjaxMouseMoveCallbackTool (client side JavaScript class: NMouseMoveCallbackTool) – intercepts the mouse move event and routes it to the server for processing; handle the AsyncMouseMove server side event of the web control to process the client side mouse move event
NAjaxMouseOutCallbackTool (client side JavaScript class: NMouseOutCallbackTool) – intercepts the mouse out event and routes it to the server for processing; handle the AsyncMouseOut server side event of the web control to process the client side mouse out event
NAjaxMouseOverCallbackTool (client side JavaScript class: NMouseOverCallbackTool) – intercepts the mouse over event and routes it to the server for processing; handle the AsyncMouseOver server side event of the web control to process the client side mouse over event
NAjaxMouseUpCallbackTool (client side JavaScript class: NMouseUpCallbackTool) – intercepts the mouse up event and routes it to the server for processing; handle the AsyncMouseOver server side event of the web control to process the client side mouse up event
NAjaxDynamicCursorTool (client side JavaScript class: NDynamicCursorTool) – changes the mouse cursor over interactive visual elements
NAjaxRedirectTool (client side JavaScript class: NRedirectTool) – redirects the browser to a specified URL when interactive visual elements are clicked
NAjaxTooltipTool (client side JavaScript class: NTooltipTool) – displays tooltips over interactive visual elements

The server side event handler of a mouse event receives an NCallbackMouseEventArgs parameter that can be used for hit-testing. The result of the hit test depends on the web control you are using – Chart or Diagram. Here are two examples, one for using the HitTest method of the Chart and one for the Diagram:

C#	Copy Code
protected void NChartControl1_AsyncDoubleClick(object sender, EventArgs e) { //The following code will change the fill color of a clicked //floating bar data point to red NHitTestResult result = NChartControl1.HitTest(e as NCallbackMouseEventArgs); if (result.ChartElement == ChartElement.DataPoint) { NFloatBarSeries series = result.Series as NFloatBarSeries; series.FillStyles[result.DataPointIndex] = new NColorFillStyle(Color.Red); } } protected NDrawingView1_AsyncClick(object sender, EventArgs e) { // The following code will change the fillcolor of a clicked shape to red NNodeList hitResult = NDrawingView1.HitTest(e as NCallbackMouseEventArgs); hitResult = hitResult.Filter(Nevron.Diagram.Filters.NFilters.Shape2D); if (hitResult.Count == 0) return; NShape shape = hitResult[hitResult.Count - 1] as NShape; shape.Style.FillStyle = new NColorFillStyle(Color.Red); }

Copy Code

protected void NChartControl1_AsyncDoubleClick(object sender, EventArgs e)
{ 
    //The following code will change the fill color of a clicked
    //floating bar data point to red
    NHitTestResult result = NChartControl1.HitTest(e as NCallbackMouseEventArgs);

    if (result.ChartElement == ChartElement.DataPoint)
    {
        NFloatBarSeries series = result.Series as NFloatBarSeries;
        series.FillStyles[result.DataPointIndex] = new NColorFillStyle(Color.Red);
    }
}

protected NDrawingView1_AsyncClick(object sender, EventArgs e)
{
    // The following code will change the fillcolor of a clicked shape to red
    NNodeList hitResult = NDrawingView1.HitTest(e as NCallbackMouseEventArgs);
    hitResult = hitResult.Filter(Nevron.Diagram.Filters.NFilters.Shape2D);
    if (hitResult.Count == 0)
        return;
    NShape shape = hitResult[hitResult.Count - 1] as NShape;
    shape.Style.FillStyle = new NColorFillStyle(Color.Red);
}

To optimize the mouse move event handling the new AsyncMouseOver and AsyncMouseOut events can be used instead of the AsyncMouseMove event. For more details, see the documentation on NInteractivityStyle and the web examples that are installed on your machine.

For usage details and sample code, please refer to the AJAX web examples that are installed by the Nevron .NET Vision installation.

Asynchronous callbacks for refresh events

At client-side, Nevron web controls provide the capability for enforcing a refresh of the web control content and for auto-refresh. In both cases a callback event is raised to the server:

Client-side event	Server-side "…Enabled" property	Server-side event
Refresh	AsyncRefreshEnabled	AsyncRefresh
Auto-refresh	AsyncAutoRefreshEnabled	AsyncRefresh

The refresh event is invoked by calling the Refresh() method of the client-side JavaScript callback service object, which can be obtained from JavaScript the following way for a Nevron Chart web control with ID "NChartControl1", respectively for a Nevron Diagram web control with ID "NDrawingView1":

JavaScript	Copy Code
if(typeof(NChartCallbackService) != "undefined") { var cs = NChartCallbackService.GetCallbackService('NChartControl1'); cs.Refresh(); } if(typeof(NDiagramCallbackService) != "undefined") { var cs = NDiagramCallbackService.GetCallbackService('NDrawingView1'); cs.Refresh(); }

JavaScript

Copy Code

if(typeof(NChartCallbackService) != "undefined")
{
    var cs = NChartCallbackService.GetCallbackService('NChartControl1');
    cs.Refresh();
}

if(typeof(NDiagramCallbackService) != "undefined")
{
    var cs = NDiagramCallbackService.GetCallbackService('NDrawingView1');
    cs.Refresh();
}

To obtain and change the value of a "…Enabled" property of a Nevron Chart web control with ID "NChartControl1", respectively for a Nevron Diagram web control with ID "NDrawingView1", the following JavaScript code can be used:

JavaScript	Copy Code
if(typeof(NChartCallbackService) != "undefined") { var cs = NChartCallbackService.GetCallbackService('NChartControl1'); cs.SetAutoRefreshEnabled(!cs.GetAutoRefreshEnabled()); } if(typeof(NDiagramCallbackService) != "undefined") { var cs = NDiagramCallbackService.GetCallbackService('NDrawingView1'); cs.SetAutoRefreshEnabled(!cs.GetAutoRefreshEnabled()); }

JavaScript

Copy Code

if(typeof(NChartCallbackService) != "undefined")
{
    var cs = NChartCallbackService.GetCallbackService('NChartControl1');
    cs.SetAutoRefreshEnabled(!cs.GetAutoRefreshEnabled());
}

if(typeof(NDiagramCallbackService) != "undefined")
{
    var cs = NDiagramCallbackService.GetCallbackService('NDrawingView1');
    cs.SetAutoRefreshEnabled(!cs.GetAutoRefreshEnabled());
}

The following table enumerates the get- and set-functions of the refresh event "…Enabled" properties of the client-side callback service object:

Client-side event	Client-side "…Enabled" property get function	Client-side "…Enabled" property set function
Auto-refresh	GetAutoRefreshEnabled()	SetAutoRefreshEnabled(bool)

The auto-refresh feature can be configured at design-time by modifying the AsyncRefreshInterval property of the Nevron web control. There is no interface exposed to change this value at client-side. Although, the following client-side JavaScript code can do the job:

JavaScript	Copy Code
if(typeof(NDiagramCallbackService) != "undefined") { var cs = NDiagramCallbackService.GetCallbackService('NDrawingView1'); cs.SetAutoRefreshEnabled(false); cs.timer.Timeout = 2000; cs.SetAutoRefreshEnabled(true); }

JavaScript

Copy Code

if(typeof(NDiagramCallbackService) != "undefined")
{
    var cs = NDiagramCallbackService.GetCallbackService('NDrawingView1');
    cs.SetAutoRefreshEnabled(false);
    cs.timer.Timeout = 2000;
    cs.SetAutoRefreshEnabled(true);
}

Additional information on asynchronous callbacks for client-side events

Nevron AJAX client-side framework executes only one callback at a time per web control. Until an AJAX request completes or times out, all intermediate callback requests are ignored. Also, for the time of the AJAX request a wait cursor can be displayed over the Nevron web control. To enable/disable the wait cursor at design-time, use the AsyncRequestWaitCursorEnabled property of the web control. To enable/disable the wait cursor at client-side, use the GetWaitCursorEnabled() and SetWaitCursorEnabled(bool) functions of the client-side callback service object. To modify the wait cursor state a client-side use the SetWaitCursor() and ClearWaitCursor() functions of the client-side callback service object. Consider the following sample code:

JavaScript	Copy Code
if(typeof(NChartCallbackService) != "undefined") { var cs = NChartCallbackService.GetCallbackService('NChartControl1'); cs.SetWaitCursorEnabled(!cs.GetWaitCursorEnabled()); } if(typeof(NChartCallbackService) != "undefined") { var cs = NChartCallbackService.GetCallbackService('NChartControl1'); cs.SetWaitCursor(); // do something time consuming cs.ClearWaitCursor(); }

JavaScript

Copy Code

if(typeof(NChartCallbackService) != "undefined")
{
    var cs = NChartCallbackService.GetCallbackService('NChartControl1');
    cs.SetWaitCursorEnabled(!cs.GetWaitCursorEnabled());
}

if(typeof(NChartCallbackService) != "undefined")
{
    var cs = NChartCallbackService.GetCallbackService('NChartControl1');
    cs.SetWaitCursor();
    // do something time consuming
    cs.ClearWaitCursor();
}

Timeouts

Because Nevron web controls are intended to run on random client platforms and browsers over a possibly unstable communication environment such as Internet, several timeout values can be configured by the developer who uses the web controls in order to provide most safe behavior of the web controls.

Server-side property	Description
AsyncImageLoadTimeout	When an image is being retrieved by the web control from the server, it is loaded in background and is displayed when the whole image is loaded. By certain circumstances, the image load event can be never invoked by the web browser and although the image is available at the client, it will never be displayed to the user. To avoid this misbehavior, after a certain timeout the image is forcibly displayed to the user, loaded or not. This timeout is set as the value of the AsyncImageLoadTimeout property.
AsyncCallbackTimeout	Every Nevron web control can be configured independently how long to wait for an asynchronous HTTP request to complete, before canceling it. There is no error reported to the user on callback timeout.
AsyncAdaptiveRefreshIntervalFactor	On request timeout the auto-refresh interval is multiplied by this value. By default is set to 1.
AsyncImageLoadIePollingInterval	Because under certain conditions Internet Explorer fails to fire an event when an image is completely loaded, a client side timer is initialized to test periodically the images being loaded in the background. It is not recommended to modify the default value of this property.

Compatibility and System Requirements

The client-side JavaScript code is compatible with JavaScript 1.2

Browser	Is tested and supported
Microsoft Internet Explorer 6	YES
Microsoft Internet Explorer 7	YES
Mozilla Firefox 2+	YES
Opera 9+	YES
Safari 3+ for Apple Macintosh	YES
Google Chrome	YES

The ASP.NET 2.0 AJAX 1.0 Framework or Microsoft .NET Framework 3.5 or later is required to use Nevron web controls in AJAX mode.