MagicAjax.NET Configuration

Table of Contents

Setting configuration options
- Web.config
- By code
Configuration options
- ScriptPath
- OutputCompareMode
- Tracing
- PageStore

Setting Configuration Options

Web.config

You can set the configuration options for MagicAjax inside web.config's configuration section. The options will be applied to all the pages of your application that use MagicAjax. If you ommit an option from web.config, MagicAjax will use its default setting. A sample of MagicAjax's default configuration options is this:

(note: There is a sample web.config file inside the 'Core' folder of the distribution with short descriptions for each available option)

	<configSections>
		<section name="magicAjax" 
			type="MagicAjax.Configuration.MagicAjaxSectionHandler, MagicAjax"/>
	</configSections>

	<magicAjax
		outputCompareMode="HashCode"
		tracing="false">
		<pageStore
			mode="NoStore"
			unloadStoredPage="false"
			cacheTimeout="5"
			maxConcurrentPages="5"
			maxPagesLimitAlert="false"
		/>
	</magicAjax>

By code

The web.config MagicAjax settings can be overriden for a particular page, by code. The MagicAjaxContext.Current.Configuration property carries all the options and you can change any of them at the Load event of your page. Example:

	private void Page_Load(object sender, System.EventArgs e)
	{
		MagicAjaxContext.Current.Configuration.PageStore.Mode = MagicAjax.Configuration.PageStoreMode.Session;
	}

Any changes you make to the configuration options by code will be stored in a hidden field of the page and will be restored for a PostBack/AjaxCall. Thus, the following example has the same effect as the previous:

	private void Page_Load(object sender, System.EventArgs e)
	{
		if ( !IsPostBack )
		{
			MagicAjaxContext.Current.Configuration.PageStore.Mode = MagicAjax.Configuration.PageStoreMode.Session;
		}
	}

Note: Configuration options can be changed during a PostBack, but changing them during an AjaxCall is not allowed and will throw an exception.

Configuration Options

ScriptPath

Type: string
Default: null (omitted)
Description: MagicAjax's script files are embedded in the dll and are put on page using script tags like this:

	<script type="text/javascript" src="AjaxCallObject.js.aspx"></script>

If you set ScriptPath to a value, the src attribute of the script tag will contain the path of ScriptPath. That way you can use your own modified versions of MagicAjax's script files. Example:

	<magicAjax ScriptPath="~/script" />

OutputCompareMode

Type: enumeration (HashCode / MD5 / FullHtml)
Default: HashCode
Description: When an AjaxCall is invoked, MagicAjax compares the previous html renderings of controls included in an AjaxPanel with the current ones, to see if changes occured. Instead of keeping the complete html string, MagicAjax produces 'fingerprints' of the html rendering strings to compare them. When 'NoStore' PageStore mode is selected, the fingerprints are kept on page in hidden fields. This option defines how the fingerprints are going to be produced:

HashCode: The String.GetHashCode() method is used. This produces the smaller in size fingerprints but with the bigger chance for collisions.

MD5: MD5 hashing is used. It is slower and larger in size, but practically there is no chance for collisions.

FullHtml: The full html rendering is kept. This is provided only for debugging purposes.

Tracing

Type: boolean
Default: false
Description: If tracing is enabled, when an AjaxCall is invoked, a tracing window is created that displays the information about the data that were sent by the client to the server as POST data and the javascript code that the client received as a response from the server. That way you can monitor the traffic of AjaxCalls for debugging purposes or to find a page setup with less AJAX traffic.

PageStore - Mode

Type: enumeration (NoStore / Session / Cache)
Default: NoStore
Description: This is the option that has the most impact on how MagicAjax is going to function and to the page's execution cycle. Study the different modes carefully before deciding which one suits the needs of your application.

NoStore : The default and recommended PageStore mode. The page's execution cycle for an AjaxCall is the same as a PostBack. The page and its controls are recreated at each AjaxCall, nothing is kept on the server, and the ASP.NET control events (Load, Unload etc.) are raised. This mode works for both NET 1.1 and NET 2.0.

Session : The page object of the request is stored at the server in Session, and MagicAjax raises the various events on the stored page object. This mode bypasses the ASP.NET Page execution cycle; the control events (Init, Load, PreRender, Unload) are not raised but instead MagicAjax's stored page events are raised (AjaxCall, PreWriteScript, AjaxCallEnd) and the PostBack events of controls (Click, SelectedIndexChanged, CheckChanged etc.)

In order to handle the stored page events you need to implement the appropriate interfaces (IAjaxCallEventHandler, IPreWriteScriptEventHandler) on your Page/Usercontrol/Custom control class, or use AjaxPage/AjaxUserControl (see Usage ).

This mode offers better performance than 'NoStore' and less AJAX traffic, at the expense of consuming server's memory. Also, keeping the page object 'alive' has the benefit that any control that gets created during an AjaxCall, will be available during the next AjaxCall. For example, if you wanted to have a button that every time it is clicked, a new checkbox is added in a panel, here's how you can do it with an AjaxPanel and 'Session' mode:

	private void Button1_Click(object sender, System.EventArgs e)
	{
		CheckBox check = new CheckBox();
		check.Text = "Checkbox" + AjaxPanel1.Controls.Count;
		AjaxPanel1.Controls.Add (check);
	}

On the other hand, if you wanted to do the same with a normal PostBack or 'NoStore' mode, you would have to implement code that keeps track of the created CheckBoxs and recreate them at the Load event. The 'alive' page object can be programmed almost like a desktop application form.

This mode has drawbacks that you must consider:

It works only with 'InProc' Session state mode; it will not work with 'StateServer' or 'SQLServer' Session state modes.
It is supported only for NET 1.1
HtmlAnchor and HtmlImage controls loose their attributes during an AjaxCall; AjaxHtmlAnchor and AjaxHtmlImage should be used in their place. (see Usage)

Cache: This mode works like 'Session' with the only difference being that the page object is stored in server's Cache, so the 'StateServer' and 'SQLServer' Session state modes can be used.

PageStore - UnloadStoredPage

Type: boolean
Default: false
Description: (Applicable only to Session/Cache PageStore modes) If the page object is stored (Session/Cache PageStore modes), this option defines whether the stored page object should be dropped when the browser's page is unloaded (when the user closes the window, navigates to another page, etc.). If it is enabled, an invisible AjaxCall is invoked at the Unload event of the browser's page, requesting that the server should drop the page object immediately. Although this can reduce a bit the memory consumption of page storing modes, it has the drawback that the page's state is not kept in browser's cache, so if the user returns to the MagicAjax-enabled page using the browser's Back button, the page will not have kept any AJAX changes and the user will see the initial page before any AjaxCalls were invoked.

PageStore - CacheTimeout

Type: integer
Default: 5
Description: (Applicable only to Cache PageStore mode) Defines the time in minutes that the page object will be kept in server's Cache, if Cache PageStore mode is selected.

PageStore - MaxConcurrentPages

Type: integer
Default: 5
Description: (Applicable only to Session/Cache PageStore modes) Every new page request creates a new page object on the server. MagicAjax distinguishes page objects based on the user's session id and the requested page. If the user opens, in his session, the same page more than once, MagicAjax stores the page objects that belong to the same page and session, but only until MaxConcurrentPages limit is reached. If the limit is reached and the user requests the same page in his session, MagicAjax will not store the new page object, but instead it will find the page object that was accessed less recently and use this for the new page request as well.

If the MaxConcurrentPages limit didn't exist, a new page object would have to be created and stored on the server every time the 'Refresh' button of the client's browser was clicked.

PageStore - MaxPagesLimitAlert

Type: boolean
Default: false
Description: (Applicable only to Session/Cache PageStore modes) If this option is true, when a page request by the user reaches the MaxConcurrentPages limit, a notification alert box appears. Provided mainly for debugging purposes.