ArcGIS Server9.3 AJAX系列(一)之CallbackResults

       NOTE：本系列面向ArcGIS Server for .NET ADF开发人员，并假设其已经具备了基本的ASP.NET及AJAX知识。

       ArcGIS Server93的Web ADF为开发人员提供了可以在AJAX环境中管理客户端与服务器之间传输的框架。这个框架称之为“callback results framework“，包括服务器端的一些类(CallbackResultCollection，CallbackResult)及控件(Web ADF controls)和客户端的JavaScript库(Web ADF JavaScript)，如下图所示。

       服务器与客户端之间的响应是通过CallbackResult来实现的。事实上，一个CallbackResult是由服务器端的Web ADF control生成的、特定的、以JSON格式化的字符串。所有的Web ADF controls都具有CallbackResults属性，通过CallbackResultsCollection可以添加、删除这些CallbackResults，或者将其转换为字符串显示。当然，也可以自己定义一个CallbackResult，而不是由服务器控件生成，这将在后面的内容中介绍。服务器端将CallbackResult传到客户端之后，就交由客户端的Js函数ESRI.ADF.System.processCallbackResult()来实现客户端内容的刷新。总体上说来，callback result框架简化了开发人员的工作，以异步的方式实现了ADF以及非ADF控件内容的刷新。

       按照需要刷新控件的不同，我们分Web ADF控件和非Web ADF控件的刷新两部分来介绍。

       一、Web ADF控件的刷新

       Web ADF为开发者提供了一系列的控件，比如常用的Map、Toc、Toolbar等。改变地图范围、图层是否可视、地图渲染等都需要刷新上述控件。之前提到每个ADF控件都具有CallbackResult属性，我们需要做的就是将需要刷新的ADF控件的CallbackResult复制到Map.CallbackResults，再返回给客户端的Web ADF Js函数processCallbackResult()处理。

       例如，添加了一个新的图层，需要刷新Map以及Toc，我们就需要添加如下代码：

       Toc1.Refresh();

       Map1.CallbackResults.CopyFrom(Toc1.CallbackResults);

       实际的过程如下图所示：

       在Web ADF控件之间管理callback result依赖于CallbackResultCollection类。它提供了一些方法，可以方便的添加、删除CallbackResult。最常用到的包括Add方法和CopyFrom方法。前者用于向CallbackResultCollection添加自定义的CallbackResult实例，后者用于复制某个CallbackResultCollection实例到另一个    CallbackResultCollection实例。当然，你也可以用ToString方法将CallbackResult转换为字符串。更多关于CallbackResultCollection类的使用请参照ArcGIS Server的离线帮助，这里不一一赘述。

       这里需要强调的是，并不是所有ADF控件的刷新都需要明确的在服务器调用刷新方法，这在Map控件上体现的尤为明显。比如，地图范围的改变或者地图比例的变化都会引起Map控件自动更新其callback result collection。其他情况，如更改地图的可见性或者添加删除某个地图资源都需要明确调用刷新方法。下面列出一些Web ADF控件之间的内联关系，在这些情况下，不需要明确调用刷新方法。

       1.当工具栏控件绑定到地图控件，在工具栏上的任何操作都会自动将地图的callback result添加到工具栏的call back result collection。

       2.当Toc控件绑定到地图控件，控制Toc里图层可见性的按钮也会实现自动刷新。

       二、非Web ADF控件的刷新

       页面中除了Map、TOC等ADF控件，一般还包含有很多非ADF控件，比如Button、Label、GridView等等。刷新这些控件的内容，可以完全脱离ArcGIS Server的CallbackResult，比如用UpdatePanel。如果你还想使用CallbackResult，当然也是可以的，但必须自己定制CallbackResult字符串。

       CallbackResult类定义了一些静态方法可以方便开发者快速定制自己刷新客户端非Web ADF控件的内容。如下表所示：

       CallbackResult

       Static Method Description

       CreateSetContent   Set the outerHTML property of an html element.

       CreateSetInnerContent  Set the innerHTML property of an html element.

       CreateSetImageSource   Set the src property of an image element.

       CreateJavaScript     Execute JavaScript. on the client.

       CreateIncludeJavaScript Include JavaScript. on the client

       CreateIncludeStyleSheet          Include a CSS style. sheet on the client

       服务器端定制的CallbackResult实例都会被客户端的Web ADF Javascript函数processCallbackResult()处理。processCallbackResult函数将包含以下代码来处理定制的CallbackResult内容：

[JavaScript]

if(action==='javascript') {

         var method = function() {

                   try { eval(params[0]); }

. . .}

else if (action==="content") {

         var o = $get(controlID);

         if (o) { o.outerHTML=params[0]; }

. . .}

else if (action==="innercontent") {

         var o2 = $get(controlID);

         if (o2) { o2.innerHTML=params[0]; validResponse = true; }

. . .}

else if (action==="image")

{

         var o3 = $get(controlID);

         if (o3) { o3.src = params[0]; }

. . .}

else if (action=='include') {

         var id = params[0];

         var elm = (id?$get(id):null);

. . .

         if(elm) { elm.parentNode.removeChild(elm); }

         document.getElementsByTagName('head').item(0).appendChild(elm);

. . .}

       最后要强调的是，无论使用哪种AJAX模式，回调技术(callback)还是部分页面刷新(partial postback,或称为ASP.NET AJAX)，callback result的内容以及客户端处理callback result的函数都是一样的。

       下一篇将介绍ArcGIS Server AJAX框架的Client CallBack解决方案。