使用 Anthem.NET 的常见回调（Callback）处理方式小结

在 Anthem.NET 中，通过 XmlHttp 或 XmlHttpRequest 组件对服务器端所作的一次无刷新调用（通常是异步模式），称为一个回调（Callback）。

本文内容是对 Anthem.NET 框架自带范例代码的整理和归纳，着重小结一下在使用 Anthem.NET 进行 Ajax 开发的时候所涉及的调用流程控制相关的内容。至于控件的使用，因为逻辑简单，这里不做叙述。

在本文后，计划写一篇文章对调用流程及其编程时的可控制点做比较完备的归纳。


一、普通的调用

<%@ Register TagPrefix="anthem" Namespace="Anthem" Assembly="Anthem" %>
<anthem:Button id="button" runat="server" Text="Click Me!" />
<anthem:Label id="label" runat="server" />
<script runat="server">
void button_Click(object sender, EventArgs e) {
label.Text = DateTime.Now.ToString();
label.UpdateAfterCallBack = true;
}
</script>



二、在回调前后添加自定义客户端函数的执行逻辑

几个常用的属性：

PreCallBackFunction：用于定义回调前执行的函数，通常可以在这里加入确认的判断。
在这个函数里 return false 将会取消回调。

PostCallBackFunction: 回调后执行的函数。
TextDuringCallBack： 用于定义回调过程中控件显示的提示信息（通常是提示等待的文字）
EnabledDuringCallBack： 在回调过程中，控件是否禁用。
CallBackCancelledFunction: 如果回调被取消，则会调用这个函数。

代码例子：

<anthem:Button id="button1" runat="server" Text="Click Me!" TextDuringCallBack="Working..." EnabledDuringCallBack="false" PreCallBackFunction="button1_PreCallBack" PostCallBackFunction="button1_PostCallBack" CallBackCancelledFunction="button1_CallBackCancelled" />

<script language="javascript" type="text/javascript">
// 回调之前，可在这里取消回调
function button1_PreCallBack(button) {
if (!confirm('Are you sure you want to perform this call back?')) {
return false;
}
document.getElementById('button2').disabled = true;
}


// 回调完成后
function button1_PostCallBack(button) {
document.getElementById('button2').disabled = false;
}

// 取消回调后
function button1_CallBackCancelled(button) {
alert('Your call back was cancelled!');
}
</script>

注意以上这些客户端处理函数中，都可以传递 control 本身作为参数，因此在必要的情况下这些函数是可以被重用的。（比如对一组类似的控件的回发事件进行处理）


三、调用服务器页面的方法

服务器端需要做的事情：

[Anthem.Method]
public int Add(int a, int b) {
return a + b;
}

void Page_Load() {
Anthem.Manager.Register(this);
}

客户端：
<input id="a" size="3" value="1">
<input id="b" size="3" value="2">
<button onclick="DoAdd(); return false;" type="button">Add</button>
<input id="c" size="6">

// 参数的含义依次是：
// 服务器方法的名字，
// 方法的参数（以 js 数组形式传递），
// 服务器端方法返回结果时调用的回调函数（因为是异步模式）。
Anthem_InvokePageMethod(
'Add',
[document.getElementById('a').value, document.getElementById('b').value],
function(result) {
document.getElementById('c').value = result.value;
}
);

调用后，在回调函数的参数中得到的 result 变量，是一个包含 value 和 error 两个属性的对象。如果在服务器端发生错误，则 value 为 null, 而 error 中包含错误数据。


四、如何处理回调时可能发生的异常

在页面中定义 Anthem_Error js 函数，则可处理所有回调时的未处理异常。

<script type="text/javascript">
function Anthem_Error(result) {
alert('Anthem_Error was invoked with the following error message: ' +
result.error);
}
</script>

异常也可以在服务器端处理。只要定义下列名称的方法：

void Page_Error()
{
Anthem.Manager.AddScriptForClientSideEval("window.location = 'http://anthem-dot-net.sf.net/'");
}

在服务器端处理有一些额外的好处，主要是可以将异常信息记录到日志.


五、页面跳转

在 Callback 的处理中，不能用 Response.Redirect 来处理页面跳转，因为这些函数是通过 js 的无刷新来调用的。代替的办法是用 Anthem.Manager 回传一段 js 给客户端去用 eval 的方式执行，从而达到页面跳转的效果（推而广之，这个 eval 的功能当然不限于跳转页面，可以干很多其他的事情）。

代码示例：

Anthem.Manager.AddScriptForClientSideEval("window.location = 'http://anthem-dot-net.sourceforge.net/';");


六、几个全局级别的客户端回调函数

我们可以在客户端定义几个特殊名字的函数，以供 Anthem 在每一次回调的前后调用。这些函数包括：
Anthem_PreCallBack(),
Anthem_CallBackCancelled(),
Anthem_PostCallBack(),

除此之外还包括前面说到的 Anthem_Error() 等。

这里典型的一个应用场景是，在每次回调开始后，我们在 Anthem_PreCallBack() 中创建一个“loading”信息的层，然后在取消(Anthem_CallBackCancelled) 或成功回调后(Anthem_PostCallBack)，移除这个层。
这样可以很方便的模拟出类似 Gmail 中的加载效果。


七、回调过程中向页面添加了新的 js 脚本

这种情况下必须设定一个额外的属性：
Anthem.Manager.IncludePageScripts = true;

例子：


<script runat="server">

protected void button1_Click(object sender, EventArgs e)
{
HtmlButton button = new HtmlButton();
button.InnerText = "Now click me!"
button.Attributes["onclick"] = "ThankYou();"
placeholder1.Controls.Add(button);
placeholder1.UpdateAfterCallBack = true;
string script = @"<script type=""text/javascript"">
function ThankYou() {
alert('Thank you!');
}
</" + "script>"
#if V2
Page.ClientScript.RegisterClientScriptBlock(typeof(Page), script, script);
#else
Page.RegisterClientScriptBlock(script, script);
#endif
Anthem.Manager.IncludePageScripts = true;
}
</script>


八、PreUpdate 事件

控件在 Render 之前，如果 UpdateAfterCallBack 为 true，则会引发这个事件。
目前这个事件的用途似乎不大。