MagicAjax.NET Framework<?xml:namespace prefix = o ns = "urn:schemas-microsoft-com:office:office" />
Configuration
Table of Contents
- Setting configuration options
- Configuration options
- ScriptPath
- OutputCompareMode
- Tracing
- PageStore
Setting Configuration Options
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:
你可以在web.config文件中设定配制选项，这些选项将会被应用到你项目的所有页面。如果你忽略一个选项，则MagicAjax使用默认值。
(note: There is a sample web.config file inside the 'Core' folder of the distribution with short descriptions for each available option) 有一个例子 web.config中Core目录中，其中有简短的有效选项的描述。
<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>
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:
web.config MagicAjax设定可以被特定页的设定覆盖。通过代码， MagicAjaxContext.Current.Configuration属性拥有所有的配制选项，你可以在页的load事件中执行它
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:
通过代码你对配制做的任何改变，将会被存在页的隐藏域中，并且在回传（PostBack/AjaxCall）时取出来。下面的便子与前面的效果是一样的。
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.
注意：配制选项仅仅可以在PostBack时被改变，不能在AjaxCall被改变，否则抛异常。
Configuration Options
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:
MagicAjax's的脚本文件被放到dll中，把它们放到页面的引用是如下形式。
<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:
如果你设定ScriptPath属性，则，src属性将会包含ScriptPath值，这是可以使用你自己脚本的方式
<magicAjax ScriptPath="~/script" />
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:
当AjaxCall被调用的时候，MagicAjax把先前的在AjaxPanel中的控件的输出与当前的进行比较。来看看是否改变发生了。为了取替总是保持完整的html输出，MagicAjax产生输出html指纹来比较它们，录这'NoStore' PageStore两种模式被选择的时候，“指纹”就会存在页面的陷藏域中，这个选项定义了是如何“指纹”被产生的。
HashCode: The String.GetHashCode() method is used. This produces the smaller in size fingerprints but with the bigger chance for collisions.
String.GetHashCode()这个函数被使用，这个产生最小尺寸的指纹，但是最大的是为防止冲突
MD5: MD5 hashing is used. It is slower and larger in size, but practically there is no chance for collisions.
MD5散列被使用，它可以放大或缩小尽寸，但是事实上没有机会发生冲突
FullHtml: The full html rendering is kept. This is provided only for debugging purposes.
全部的html都被产生出来，这个仅仅是debug目的
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 <?xml:namespace prefix = st1 ns = "urn:schemas-microsoft-com:office:smarttags" />AJAX traffic.
是否跟踪是有效的，当AjaxCall被调用的时候，一个跟踪窗口就是被创建来显示，从客户端post到服务器端的数据和客户端收到的javascript代码。那个方法，你可以监控AjaxCall的调用过程，以Debug的目的。or to find a page setup with less AJAX traffic.
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.
这个选项，是关于如果执行MagicAjax功能，和页面的执行周期，在确定哪种模式适合你的应用之前，认真的研究一下它们的不同，
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.
这是默认的和推举使用的PageStore模式。对于AjaxCall页面的执行周期和PostBack是一样的，页面和它们控件被重新创建，在每次AjaxCall调用中，在服务器端什么也不进行保留，asp.net控件的事件要被触发的，这种模式工作在.net1.1和.net2.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.)
请求的页面对象被缓存在服务器端的Session中。且MagicAjax激发各种事件on the stored page object（在页存储对象的上）。绕过asp.net page的执行周期，控件的事件将不会发生(Init, Load, PreRender, Unload)，仅仅MagicAjax的stored page events(AjaxCall, PreWriteScript, AjaxCallEnd)和控件的postBack事件(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 ).
为了处理stored page events，你需要在Page/Usercontrol/Custom control class, or use AjaxPage/AjaxUserControl中你的实现合适的气接口，(IAjaxCallEventHandler, IPreWriteScriptEventHandler)
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:
比起NoStore模式，这种模式提供了更好的性能和少量的ajax的数据的传递，但是有服务器内存的消耗，保持页对角处于”alive”状态的价值在于，任何控件可以在AjaxCall时被创建，在下一下AjaxCall调用时将是有效的，不需要创建。例如，如果你想要一个每次被单击的按钮，一个新checkbox被添加到Panel中，这里你可以做这件事情用ajaxPanel和 Session model
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.
另一种方式，如果你想要做如同常规的PostBack或NoStpore模式，你可以实现代码（在Load事伯中，可以保持对创建CheckBox和重建它们的跟踪）。这种页面（'alive'）对象可以像桌面应用一样来编程
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.
- 它仅仅可以工作在InProc Session模式下
- It is supported only for NET 1.1
- 它仅仅支持.net 1.1
- HtmlAnchor and HtmlImage controls loose their attributes during an AjaxCall; AjaxHtmlAnchor and AjaxHtmlImage should be used in their place. (see Usage)
- HtmlAnchor and HtmlImage将会失去它们的属性在ajaxCall调用时，应该使用AjaxHtmlAnchor and AjaxHtmlImage
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.
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.
（仅仅可以适用于Session/Cache PageStore模式）如果页面对象被存储（Session/Cache PageStore modes） 这个选项定义是否stored page object 应该被丢弃，当客户端页面被卸载时（当用户关闭窗口，导航到另一个页面），如果是有效的，在浏览器的Unload事件中一种不可见的AjaxCall被调用，要求服务器应该立即丢弃页面对象。尽管这种方式可以降低内存的占用。它的缺点是页面的状态并不保持在浏览器的缓存中，这个页将不保持ajax改变，用户将会看到ajaxCall调用之前的初使页面。
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.
（仅仅可以适用于Cache PageStore模式）页面对象保存在服务器上的时间，哪果Cache PageStore被选中，
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.
（仅仅可以适用于Session/Cache PageStore模式）每一个新的页面请求去在服务器端创建一个新的页面对象。MagicAjax根据用户的Session id来区分页面对象。如果在用户的session中，它打开同一页面不止一次,在MaxConcurrentPages达到极限之前，MagicAjax存储页面对象（这个对象属于同样的页面和session）。如果这个极限达到了，用户请求同样的页面在它的session中，MagicAjax将不会存储新的页面对象，取而代之的是查找最近很少访问的页面对象来使用它做为新的页面请求
如果MaxConcurrentPages并不存在，每次客户端的Refresh按钮，一个新页面对象将必须在服务器端创建和存储
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.
(应用仅仅针对于Session/Cache PageStore模式)如果这个选项是有效的，如果页面的请求达到了MaxConcurrentPages极限，一个警告框将会出现，提供debug的目的。