MagicAjax.NET Framework<?xml:namespace prefix = o ns = "urn:schemas-microsoft-com:office:office" />
Usage
Table of Contents
- Programming
- Controls
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.
根据PageStore Mode的配制选项，页面的执行周期会有很大的不同（see Configuration Options）对于默认的'NoStore' mode,页面的执行周期将会如同PostBack，你可以进行区分是PostBack 还是AjaxCall发生了，通过检查MagicAjaxContext.Current.IsAjaxCallForPage方法的返回值
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).
注意：有一个属性MagicAjaxContext.Current.IsAjaxCall，如果它为true，那么http请求是AjaxCall是引起的。但是推举的方式是使用IsAjaxCallForPage来进行判断是否是AjaxCall调用。如果页面被创建是由于Server.Transfer的调用（这个调用在AjaxCall期间发生）IsAjaxCallForPage它将会返回false,因此你的页面可以做为常规页面来运行。AjaxPage.IsAjaxCall 属性（可以引起对IsAjaxCallForPage调用）是为了方便才提供的
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:
做为一个ajaxCall的响应MagicAjax发送javascript code到客户端，如果你要发送用户定制的javascript代码，可以用AjaxCallHelper中的静态方法。如:
private void Button1_Click(object sender, System.EventArgs e)
{
AjaxCallHelper.WriteAlert ("Button1 was clicked.");
}
Setting an Ajax refresh timer设定刷新时间
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.
你可以使用AjaxCallHelper.SetAjaxCallTimerInterval方法来设定页面的刷新时间（在这个时间间隔，AjaxCall将会被调用）范围，你可以在初使化页面请求时或在AjaxCall调用期间来调用这个方法,如果interval的值为0，则定时器无效
Example:
private void Page_Load(object sender, System.EventArgs e)
{
if (!IsPostBack)
{
// <?xml:namespace prefix = st1 ns = "urn:schemas-microsoft-com:office:smarttags" />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.
这是个MagicAjax的核心控件，所以在AjaxPanel中的控件的PostBack功能将会被AJAX callback进行替换。如果没有什么特别的处理，AjaxPanel就如同ASP.NET Panel一样，它的内容可以在设计器中可视化显示，你可以设置所有的web控件的属性或改变它
Its AjaxCallConnection property can be set to:
- Asynchronous (Default)
The AjaxCall will be invoked in the background
AjaxCall将会在后台调用
- Synchronous
The client's browser will wait for the AjaxCall to finish
客户端browser将会等到AjaxCall完成
- None
Controls inside the AjaxPanel will invoke a normal PostBack
AjaxPanel中的控件将会调用常规的PostBack
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.
为了降被发送到客户端的html的代码量，AjaxPanel定义了单独的html占位符，如果html占位符在AjaxCall期间改变了，MagicAjax发送整个占位符的html来反应到客户端。每一个直接的ajaxPanel中的子控件被应用分别的占位符，定义占位符是为了literal and HtmlControls content of the AjaxPanel.，因此如果webcontrol（在ajaxPanel中）中的html改变了，仅仅特定的控件将会发送到客户端
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.
一个AjaxPanel(子AjaxPanel)在另一个AjaxPanel（父AjaxPanel）中。这个子AjaxPanel将会定义它的html占位符与父AjaxPanel分离. 父AjaxPanel将会忽略子AjaxPanel的html占位符，仅仅子AjaxPanel负责更新它的内容到客户端。因此你可以将低流量，通过添加更多的AjaxPanel来定义更多的更小的html占位符。例如，如果你想把table入到AjaxPanel中，如果在ajaxCall调用过程中改变了，则整个table的html都会被发送到客户端，另一种方式，如果你添加AjaxPanel到cell级别，如果内容变了，仅仅单元格的内容发送到客户端
In order to monitor the traffic of AjaxCalls that your page is producing, you can enable the tracing configuration option.你可以通过tracing功能来进行跟踪
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.
这是一个AjaxPanel的属性AjaxLocalScope值为true的AjaxPanel。它提供了便利和可读性，当一个AjaxCall是在AjaxZone内部的控件调用时，仅仅包含在这个AjaxZone中的元素值被发磅到服务器，服务器将会check这些改变，然后更新到客户端的AjaxZone中，这个有助于降低数据的流量，和服务器的反应速度，这个的目的是使化成为一个独立的部分，更像一个用户控件
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.
捕获一个控件的客户端事件，事件的名称属性必须设定成客户端的事件如（i.e. "focus", "change", etc.）并且ControlID属性必须设定成一个控件的ID（这个控件将会触发这个事件），例如，ClientEventTrigger 在AjaxPanel内，AjaxCall会被调用，即使那个ControlID所标识的控件不在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).
捕获内部控件的按键事件，
AjaxPage and AjaxUserControl用户控件
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.
IsAjaxCall属性将会对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:
你可以添加特别的属性到asp.net控件中，来确定这些控件如何被MagicAjax处理
- AjaxCall ("Async" or "Sync" or "None")
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.
如果你添加属性"Async"/"Sync"值 ，则具有PostBack功能的控件，则会用ajax功能所代替，即使它不包含在AjaxPanel中。
如果你加天属性为None值，到控件（这个控件中AjaxPanel中）则这个控件执行Postback 而不是AjaxCall.
通过添加AjaxCall属性你可以覆盖父AjaxPanel的AjaxCallConnection属性。（如果ajaxPanel是Asynchronous，你可以设定ajaxCall为sync合控件执行synchronous ajaxCall）.AjaxCall的效果被应用到所有的子控件。
- ExcludeFromPost ("true" or "false")
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.
对于仅仅显示值的控件的数据不需要发送的客户端，你可以设定此属性来防止无用的数据被提交到后台。
- AjaxLocalScope ("true" or "false")
Makes the control behave like an AjaxZone.
- ExcludeFlags (expression)
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.
确定哪个form元素可以被排除发往服务器。在ajaxCall调用时这个form元素将会被排除。它有一组运算表达式，
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.
所有的属性可以通过标记方式或代码方式设定，它们的值和随后的功能在ajaxCall调用时被改变
Example:
Button1.Attributes["ajaxcall"] = "async";