2010年7月29日_周四_Working with CallbackResults
/*******************************************************/
//Working with CallbackResults
//
/*******************************************************/
The Web ADF contains a framework to manage the synchronization of server-client content in an asynchronous (AJAX) environment. This framework, termed the "callback results framework", consists of server-side classes and control properties and client-side Web ADF JavaScript logic. During user interaction with a Web application, the state of a Web ADF control and other content on the server will often change. Web ADF controls communicate changes in their state on the server with Web ADF controls in the browser via callback results.
Web adf 包含来一个框架来管理异步环境下服务器和客户端之间内容的同步传输。这个框架被称为“回调结果框架”，她包括服务器端的类以及控件的属性和客户端的web adf JavaScript逻辑。 当用户和一个web 应用程序进行交互的时候，服务器端的web adf 控件的状态和其他的内容就会经常发生改变。 服务器端的web adf 控件通过回调结果集同客户端浏览器里面的web adf 控件交流他的状态。
A "callback result" is a Web ADF specific, JSON (JavaScript Object Notation) formatted string generated on the server, often by Web ADF controls. Custom callback results can also be created using the Web ADF CallbackResult class. All Web ADF controls have a CallbackResults property which references a collection of CallbackResult instances in a Web ADF CallbackResultCollection.
一个"callback result" 是一个web adf 特定的，通常是由web adf 控件指定的。自定义回调结果 页可以使用web adf CallbackResult 类来创建。所有的web adf 控件都有一个callbasekresults 属性，他们提到在一个Web ADF CallbackResultCollection.中的一个callbackresult 实例的集合。
Collections of callback results can be managed using the CallbackResultCollection class, which means you can add, remove and convert the entire collection to a string. Web ADF callback results are explicitly designed to be processed by the Web ADF JavaScript function ESRI.ADF.System.processCallbackResult(). Some Web controls also maintain their own processCallbackResult() function for control specific processing of callback results.
CallbackResultCollection类可以管理callback results 的集合，这个就意味着你可以添加、删除和将所有的集合转换为一个字符串。Web adf 回调集合被明确的设计为使用web adf javascriptd 的功能ESRI.ADF.System.processCallbackResult()来处理。 一些web 控件还可以保持他们自己的processCallbackResult()功能用来控制回调结果的特殊的处理。
In essence（实质上）, the Web ADF callback results framework makes it easier for you, the developer, to use managed server-side classes to modify both Web ADF and non-Web ADF content in the client browser. The following diagram highlights the components of the callback results framework on the client and server.
从实质来说，web adf 回调结果框架让你，一个开发者，使用服务器端的类来修改浏客户端览器里面的web adf 或者非web adf 的内容更加容易一些。
Web ADF controls will always use callback results to update client-side content in the browser, regardless of whether you explicitly create or manage them. For example, when calling the Zoom method on a Map control, the Map control will generate a callback result. The following diagram illustrates the initial Web request which calls the Zoom() method on the Map control (server-side), then the Map control packages callback results in the Web response. The Map control is a script control, thus it is represented on the client as a JavaScript object and on the server as a .NET Server control.
Web adf 控件经常使用callback结果来更新客户端浏览器里面的内容，而不管你是否明确的创建或管理他们。比如：当在地图控件上面触发一个缩放的方法，地图控件将会产生一个回调结果。下面的图标说明了web 请求的开始，这个请求调用来地图控件上的缩放方法。然后地图控件在web 相应中封装来回调结果。 Map 控件是一个脚本控件，因此他在客户端就代表一个JavaScript对象，在服务器端代表一个.NET服务器的控件。
Important note: Although the technique for packaging callback results will differ depending on the AJAX pattern you choose for your page (callback versus partial postback ), callback result content and processing callback results by Web ADF JavaScript on the client will remain the same.
重要说明：尽管回调结果的封装技术根据你为你的页面所选择的ajax类型的不同而不同，但是回调结果的内容和客户端由web adf JavaScript来处理的结果是相同的。
If a Web ADF control initiates a Web request, it will automatically package its callback results in a Web response. In some cases, a developer may want to change or interact with other controls or elements in the page besides the Web ADF control that initiated the request. This may include both Web ADF and non-Web ADF content. To use the Web ADF callback results framework to update client content, a developer must package custom messages in a CallbackResult class and make sure it is processed on the client by the Web ADF JavaScript processCallbackResult() function.
如果一个web adf 控件发出来一个web 请求，她将会自动的在一个web 相应中封装回调结果。 在一些情况下，一个开发者可能想要改变或者与页面中的其他控件进行交互，这些控件可以是除了引起触发请求的web adf控件。这些可能会既包括web adf 和非web adf 内容。为来使用web adf 回调结果框架来更新客户端的内容，一个开发者必须在一个CallbackResultL类中封装自定义的消息并且确保在客户端由web adf JavaScript 的processCallbackResult（）函数来进行处理。
For Web ADF content, there are a number of inherent（内在的，固有的） relationships between Web ADF controls where callback results are copied to the Web ADF control that packages the callback results for the response (see the section on internal callback result creation below for more details). If the Web ADF control you want to change is not covered by a pre-defined relationship, you must explicitly manage its callback results. This means you must copy the callback results for the Web ADF control you changed (via the CallbackResults property) into the callback results collection of the Web ADF control responsible for generating the callback results in the Web response. The code and diagrams below provide an example where the Web ADF Map control initiates a request and packages callback results in a response and the Toc control needs to be refreshed to reflect changes in the state of the map (e.g. a new map resource item was added). The Toc's callback results are copied to the Map callback results collection via the CopyFrom() method. The diagram shows the actual callback results being combined and returned in the response and provides a brief view of the underlying format of a CallbackResult and CallbackResultCollection.
对于web adf 的内容，在web adf 控件之间这里有很多内在的关系，这里也是回调结果拷贝到web adf 控件并且作为相应结果封装起来。 如果你想改变的那个web adf 控件没有包括在你预先定义的的关系里面，你就必须明确的管理他的回调结果集。 这就意味着你必须将你所改变的web adf 控件的回调结果拷贝到负责在web 响应中产生产生回调结果集的web adf 控件的回调结果集合。下面的代码和表格提供一个例子来说明web adf 地图控件在什么地方触发一个请求以及在响应里面回调结果的封装，toc 控件需要被重新刷新来显示地图状态的改变。Toc 控件的回调结果集是通过capyform()方法从map 回调结果集中拷贝的。 下面的图表显示来实际的别合并的回调结果集并在相应中返回，并且提供了一个理解callbackresult和callbackresultCollection大致的概念。
CallbackResults example code
[C#]
<new map resource item added>
Toc1.Refresh();
Map1.CallbackResults.CopyFrom(Toc1.CallbackResults);
CallbackResults process
Actual CallbackResult string content
The ability to manage callback results within and between Web ADF controls hinges on the capabilities of a CallbackResultsCollection. The CallbackResultCollection class provides a convenient means for managing multiple CallbackResult objects. While each Web ADF control maintains a CallbackResultCollection (accessible（容易取得的） via the CallbackResults property) you can also create a CallbackResultCollection for your own use. The following table lists a number of methods on a CallbackResultCollection object you may find beneficial:
管理web adf内部以及web adf控件之间的回调解决的能力是CallbackResultsCollection的能力相关的。CallbackResultCollection 类提供了一个管理多个CallbackResult对象省力的方法。每一个web adf 控件维持一个CallbackResultCollection（通过CallbackResults属性容易获取的），那么你也可以创建一个CallbackResultCollection 为你自己所用。下面的表格里面列出来一系列CallbackResultCollection对象的方法你可能会感觉有用。
| CallbackResultCollection Method Name |
Description |
| Add |
Used to add individual CallbackResult instances to a collection. Often useful when creating custom CallbackResult instances and adding them to the existing callback collection for a Web ADF control. |
| CopyFrom |
Used to copy an entire CallbackResultCollection to another collection. Often useful when you need to update a Web ADF control whose callback results are not automatically included in a response. Merely copy its callback results into the Web ADF control responsible for generating the callback results in a response. |
| ToString |
Used to convert a CallbackResultCollection into a string with the appropriate formatting for the processCallbackResult() function to parse and utilize its content. Often useful in cases where the control responsible for generating the callback results for a response is not a Web ADF control -or- the AJAX pattern requires callback results be explicitly packaged as a string . |
So far, this section has discussed existing CallbackResults and CallbackResultCollections associated with Web ADF controls. In many cases, you may want to work with non-Web ADF content in your page. For non-Web ADF content, you have a choice of using AJAX pattern specific techniques or the Web ADF callback result framework. For example, to update a ListBox or GridView using the partial postback pattern, you can use an UpdatePanel. If you do choose to leverage the callback result framework, a custom CallbackResult object should suit your needs. The next section focuses solely【单独的，唯一的】 on custom CallbackResult objects and capabilities.
到现在为止，这个章节已经讨论来和web adf 控件相关联的CallbackResults 和CallbackResultCollections。 在很多的情况下，你可能想要在你的页面中使用非web adf的东西。 对于非 web adf 内容你有一个选择：使用AJAX模型特定的技术，或者web adf 回调框架。例如，使用部分回调模型来封信一个列表框控件或者GridView控件，你可以使用一个UpdatePanel控件。 如果你选择使用一个影响回调结果集的框架，那么一个自定义的回调结果对象应该满足你的要求。下一个章节我们见单独的重点关注自定义的CallbackResult对象和能力。
Custom callback results
The CallbackResult class defines a set of arguments that enable you to work with almost any html content in the page by utilizing client-side technologies and the browser DOM (document object model) to locate and interact with elements in the page. For example, custom JavaScript code can be executed on the client as needed. The table below defines a set of static methods on the CallbackResult class which can be used to interact with browser content.
CallbackResult 类定义来一系列的参数使你能够利用客户端的ijshu和浏览器的DOM来和几乎任何一个页面中的html内容并且和页面中的元素进行交互。比如：自定义脚本代码可以在客户端根据需要被运行。 下面的表格里面定义了一系列固定的CallbackResult 类中的方法，这些方法可以被用来和浏览器的内容进行交互。
| CallbackResult |
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 |
The following example illustrates how to execute a line of JavaScript code associated with a custom CallbackResult using the CreateJavaScript static method. A Map control named "Map1" will generate the callback results for a Web response, so the custom CallbackResult will be added to Map1's callback results collection. When this code is executed at runtime and processed by Web ADF JavaScript， a message box will display in the browser containing the phrase "Hello World":
下面的列子介绍来如何使用CreateJavaScript的static方法来执行一行和自定义callbackresult 相关的JavaScript代码。一个名称为 map1的地图控件将会为一个web 响应产生一个回调结果，因此自定义的CallbackResult 将会被添加到map1的回调结果集合当中。当这个代码在运行的时候被执行并且被web adf javascript 处理后，一个包含”HELLO WORLD”的字符串将会出现在浏览器里面。
[C#]
string javascriptString = "alert('Hello');";
CallbackResult customCallbackResult = CallbackResult.CreateJavaScript(javascriptString);
Map1.CallbackResults.Add(customCallbackResult);
Each custom CallbackResult instance is designed to be processed by the Web ADF JavaScript function processCallbackResult() in the ESRI.ADF.System.js library. The processCallbackResult() contains the following logic to process the custom CallbackResult content:
[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);
. . .}
Many samples included with the developer help illustrate the use of custom callback results and the CallbackResult class including Common_Callback, and Common_SelectBufferTool .
很多包含开发帮助的例子都介绍来如何使用自定义的回调结果集，CallbackResult类包含Common_Callback, and Common_SelectBufferTool .
Internal callback result management in Web ADF controls
In some cases, a Web ADF control may generate callback results without requiring an explicit call to refresh the control on the server. This is often the case with the Map control. Merely（仅仅） changing map extent or scale will automatically cause the Map control to update its callback result collection. In other cases, an explicit call to refresh is required, such as when layer visibility changes or a resource is added or removed. It's important to be aware that an explicit call to refresh the Map control is not always necessary. In many cases, you do not need to explicitly copy callback results from one Web ADF control to another. Listed below are a number of inherent（内在的，天生固有的） relationships between Web ADF controls:
在一些情况下，一个web adf 控件可能会产生一个callback result而没有要求一个明确的调用来更新在服务器端的空间。这种情况经常和map控件相关。如果仅仅是改变地图显示的范围或者是显示的比例那么将会自动的因此地图控件更新它的callback result collection . 另外一种情况是，一个明确的更新请求被请求，比如：当一个图层可见性改变后或者一个资源被添或者被删除。明白一个明确更新地图控件的请求并不是每次都是必须的是很重要的。 在很多的情况下，你没有必要明确把回调结果集从一个web adf 控件拷贝到另一个web adf 控件。下面的列表是一些web adf 之间固有的关系。
When a Toolbar is buddied to a Map, any command action on the toolbar will copy the Map's callback results to the Toolbar's callback results collection. So if the command changed the Map, the callback results are already added to the Toolbar callback results which will generate the Web response. The same applies for a PageLayout if a Toolbar is buddied to it.
当一个工具条绑定到一个地图上的时候，toolbar上的任何一个动作都会将map 的回调结果集拷贝到toolbar的回调结果集合。因此，如果命令改变来地图，callback Results已经添加到 toolbar回调结果而生成web 的响应。 如果将一个pagelayout和一个toolbar进行绑定那么将会产生同样的效果。
- When a Toc is buddied to a Map, a NodeChecked event, will copy the Map's callback results to the Toc's callback results. When the Map and Toc contain a scale dependent layer, a ScaleChanged event will copy Toc's callback results to the Map's callback results.
当一个toc控件绑定到一个地图上，一个节点单击事件就会把map的callback results拷贝到toc控件的callback results。 当一个地图和一个toc控件包含一个比例可以改变的图层的时候。一个比例变化事件就会把toc控件的callback result拷贝到map控件的地图回调结果集里面。
- When a ScaleBar control is buddied to a Map, the ScaleBar抯 PreRender event will copy the ScaleBar抯 callback results to the Map抯 callback results.
- 当一个比例工具条绑定到一个地图，比例工具处理事件将会把scalebar控件拷贝到map控件的回调结果集合。
Exceptions for non-Web ADF controls
In general, some controls that have been added to the page, but are not visible or do not contain any content, do not add an html element when the page is rendered in the client browser. Since callbacks are designed to work with the browser抯 DOM to update content dynamically, they need an element (object) to work with. The GridView control exhibits（显示） this behavior. If the GridView has been added to a page, but is not visible or is empty, no complimentary object on the client is available. When the GridView is populated on the server and needs to be rendered on the client via a callback, you need to provide a location to render the content using the browser's DOM. One widely accepted solution to this problem involves using a div element on the client to wrap（包裹） the GridView. When the GridView needs to be updated via a callback, the innerHTML of the div can be completely replaced and the location and style of the GridView is maintained in the page, regardless of its visibility. Two samples illustrate this solution: Common_AddCustomTool and Common_SelectBufferTool.
一般来说，一些控件已经添加到页面上去，但是他们不可见或者他们根本没有什么内容，当页面在客户端浏览器理念处理的时候，不要将一个html元素添加到页面。因为callbarck 被设计为和浏览器以及DOM一起工作来动态的更新内容，因此他们需要一个原来在一起工作。 GridView control 说明来这个原理。 如果一个GridView control被添加到一个页面，但是他是不可见的或者是空的，在客户端没有免费的对象是可以获取的。当一个GridView 在服务器端注册并且需要通过一个回调在客户端进行操作，你需要使用浏览器的DOM提供一个位置去操作内容。一个被广泛接受用于解决该问题的方法是用一个div元素将GridView包裹起来。 当GridView控件需要通过一个回调来更新的时候，div的内置HTML文件就会被完全替换并且GridView的位置和样式仍然在页面中保持而不用管她是否是可见的。两个例子说明来这个解决方案： common add custom tool 和 comm SelectBufferTool.