MagicAjax.NET Framework
Usage
Table of Contents
Programming
Depending on the PageStore Mode configuration option, the page's execution cycle will differ significantly (see Configuration Options). For the default 'NoStore' mode, the page's execution cycle will be the same as a PostBack. You can distinguish if a PostBack or an AjaxCall occured, by checking the return value of the MagicAjaxContext.Current.IsAjaxCallForPage method.
Note: There is a MagicAjaxContext.Current.IsAjaxCall property that is true if the http request was originated by an AjaxCall, but the recommended method of checking whether an AjaxCall was invoked is by using IsAjaxCallForPage. If the page is created because of a Server.Transfer call that occured during an AjaxCall, IsAjaxCallForPage will return false so that your page can execute as a normal page request. The AjaxPage.IsAjaxCall property, that makes a call to IsAjaxCallForPage, is provided for convenience (see AjaxPage).
MagicAjax sends javascript code to the client as a response to an AjaxCall. If you want to send your custom javascript along with MagicAjax's, you can use the static functions of AjaxCallHelper. For example:
private void Button1_Click(object sender, System.EventArgs e)
{
AjaxCallHelper.WriteAlert ("Button1 was clicked.");
}
You can use the AjaxCallHelper.SetAjaxCallTimerInterval method to set a page wide timer that will invoke AjaxCalls at the intervals that you define. You can call it either at the initial page request or during an AjaxCall to initiate it or change the interval value. If you call it with an interval value of zero, the timer will deactivate.
Example:
private void Page_Load(object sender, System.EventArgs e)
{
if (!IsPostBack)
{
// Ajax refresh every 10 seconds
MagicAjax.AjaxCallHelper.SetAjaxCallTimerInterval(10000);
}
}
Controls
This is the core control of the MagicAjax framework. The PostBack functionality of all the controls that are inside an AjaxPanel will be replaced by an AJAX callback (AjaxCall), unless defined otherwise. AjaxPanel works like the ASP.NET Panel, its contents are visible on the designer, you can set all the WebControl attributes to it, change its Visible property etc.
Its AjaxCallConnection property can be set to:
Its ExcludeFlags property determines which form elements should be excluded from posting to the server during an AjaxCall, thus reducing the AjaxCall traffic. It sets the ExcludeFlags MagicAjax ASP.NET control attribute. A child AjaxPanel automatically "inherits" the ExcludeFlags of its parent AjaxPanel. The child can mark more form elements to exclude through its ExcludeFlags property but it cannot send to the server form elements that have been marked for exclusion by its parent AjaxPanel.
In order to reduce the amount of html needed to send to client, AjaxPanel defines individual 'html holders'. If the html of a holder changes during an AjaxCall, MagicAjax sends the whole html of the holder so that it can be reflected to the client's browser. Every immediate WebControl child of an AjaxPanel is considered a separate holder, and one extra holder is defined for the literal and HtmlControls content of the AjaxPanel. Thus, if the html of a WebControl, that is enclosed inside an AjaxPanel, changes, only the html of the particular WebControl will be sent to the client.
An AjaxPanel (child AjaxPanel) that is inside another AjaxPanel (parent AjaxPanel), define its html holders separately from its parent. The parent AjaxPanel will ignore the html of the child AjaxPanel; only the child AjaxPanel will be responsible for reflecting its holders on the client. Thus, you can reduce the traffic of AjaxCalls, by adding many AjaxPanels that define more and smaller html holders. For example, if you put a table inside an AjaxPanel and change one of its cells during an AjaxCall, the complete html of the table is going to be sent to the client. On the other hand, if you add an AjaxPanel for each cell, only the html of the contents of the changed cell will be sent to the client.
In order to monitor the traffic of AjaxCalls that your page is producing, you can enable the tracing configuration option.
It's an AjaxPanel that has the MagicAjax attribute AjaxLocalScope set to true. It is provided for convenience and readability. When an AjaxCall is invoked from a control inside an AjaxZone, only the values of the form elements that are contained inside this AjaxZone will be sent to the server and the server will check for changes and "reflect" only the AjaxPanels that are inside the AjaxZone. This helps reduce the Ajax traffic and speed up a bit the server's response. It's intented for isolated and independent portions of a page, like UserControls.
An AjaxZone can contain other AjaxZones. A control belongs to the AjaxZone that is its immediate parent.
Captures a client event of a control. The EventName property must be set to the client event (i.e. "focus", "change", etc.) and the ControlID property must be set to the ID of the control whose event you want to capture. The AjaxCall that will be invoked is dependent at the ClientEventTrigger's placement, not the placement of ControlID's control. For example, if the ClientEventTrigger is inside an AjaxPanel an AjaxCall will be invoked even if the ControlID's control is not inside an AjaxPanel. The ClientEventTrigger must be inside the same NamingContainer (i.e. UserControl) as the ControlID's control.
Captures the KeyPress, KeyDown, and KeyUp client events of its inner controls. The KeyPress event has the IE behaviour across all browsers (invoked when a character is typed or Enter is pressed).
Making your pages and usercontrols inherit from AjaxPage and AjaxUserControl is not required; they're provided only for convenience. They expose the MagicAjax's stored page events (see Session/Cache PageStore modes) and provide the IsAjaxCall property that makes a call to MagicAjaxContext.Current.IsAjaxCallForPage.
AjaxHtmlAnchor and AjaxHtmlImage
These controls are intented to be used only for the Session/Cache PageStore modes. When these modes are selected, ASP.NET's HtmlAnchor and HtmlImage loose their href and src attributes during an AjaxCall. AjaxHtmlAnchor and AjaxHtmlImage can be used in their place.
MagicAjax attributes for ASP.NET controls
You can add special attributes to ASP.NET controls that define how they will be handled by MagicAjax:
If you add the AjaxCall attribute with "Async"/"Sync" value to a control that has PostBack functionality (i.e. Button, LinkButton, CheckBox, etc.) the PostBack functionality of the control will be replaced by AJAX functionality, even if it is not contained inside an AjaxPanel. If you add the AjaxCall attribute with "None" value to a control that is inside an AjaxPanel, the control will perform a PostBack instead of an AjaxCall. By adding the AjaxCall attribute, you override the AjaxCallConnection property of its parent AjaxPanel (if the AjaxPanel is set to Asynchronous, you can add AjaxCall with "sync" value to a control to make it perform a synchronous AjaxCall). The effect of the AjaxCall attribute is applied to all the children of the control, so if you add it to a plain ASP.NET Panel, all the controls that are contained inside this Panel will get the effect of the AjaxCall attribute.
When an AjaxCall is invoked, the client sends the values of the form elements to the server as POST data. If there is a control that is used only to display information and not to get input from the user, you can add the ExcludeFromPost attribute with "true" value and the value of this control will not be sent to the server. For example, if your page contains a readonly TextBox that is used to display chat messages, sending its contents for every AjaxCall is unnecessary traffic; you can avoid it by using the ExcludeFromPost attribute.
Makes the control behave like an AjaxZone.
Determines which form elements will be excluded from posting to server during an AjaxCall. These form elements will be excluded when an AjaxCall is invoked from the control or one of its children. It should be set to an arithmetic expression that has an integer as a result. The javascript constants excfViewState, excfFingerprints, excfUserHidden, excfAllHidden, excfFormElements, excfAllElements can be used for convenience.
Example:
<asp:button excludeflags="excfFormElements | excfViewState" ...>
All the attributes can be added inside the control's tag statement or by code. Their values, and consequently their function, can be changed during an AjaxCall.
Example:
Button1.Attributes["ajaxcall"] = "async";
Copyright © 2005-2006 by The MagicAjax.NET Team