3.1.2 跳跃的精灵——小工具

3.1.2          跳跃的精灵——小工具

小工具安插在 Fusion 提供的基础平台上，用以提供众多用户需要的功能。

一个小工具由一个 XML 格式的小工具信息文件和一个 Javascript 脚本文件和一些可选的辅助性文件构成。

小工具信息文件都被放置在一个指定文件夹中。如果您安装的是开源版 MapGuide ，您会在默认为“ <FusionRoot>/widgets/widgetinfo ”的文件夹下面找到它们。但是，这个文件夹的默认位置是可以改变的，您可以打开 <WebRoot>/webconfig.ini 配置文件（本章中除特殊说明外， <WebRoot> 指的是开源版“ C:/Program Files/OSGeo/MapGuide/Web/www ”文件夹或企业版“ C:/Program Files/Autodesk/MapGuideEnterprise<version>/WebServerExtensions/www ”文件夹），修改其中 WebApplicationProperties 组中的 WidgetInfoFolder 配置项来修改该文件的默认位置。

小工具信息文件采用的是 XML 格式编写的，用来像平台描述小工具的信息。每个小工具信息文件与小工具的种类是一一对应的，比如 About 小工具的描述文件仅有一个，而且该文件里只描述 About 这一种小工具。一个典型的小工具信息文件的格式如下面代码 3-1 所示：

<WidgetInfo> <Type>About</Type> <LocalizedType>About</LocalizedType> <Description>This widget displays information about the application including the license and copyright information retrieved from a URL set as a parameter</Description> <Location></Location> <Label>About</Label> <Tooltip>Click to show information about this application</Tooltip> <StatusText></StatusText> <ImageUrl>images/icons.png</ImageUrl> <ImageClass>about</ImageClass> <StandardUi>true</StandardUi> <ContainableBy>Any</ContainableBy> <Parameter> <Name>AboutURL</Name> <Description>This is a pointer to the URL that will be displayed in the popup window</Description> <Type>String</Type> <Label>URL pointing to the About page</Label> <DefaultValue>widgets/About/About.html</DefaultValue> <IsMandatory>false</IsMandatory> </Parameter> </WidgetInfo>

代码 3-1 小工具信息文件格式示例

代码 3-1 是 “ 关于 ”(About) 小工具的信息，其中一些常见的节点如下：

1.       Type ：类型，这个类型表示着将来如何去获取这个小工具的脚本代码。

2.       LocalizedType ：经过本地化的类型名称，用于 MapGuide 配置工具使用。

3.       Description ：对于小工具完成功能的描述。

4.       Location ：小工具脚本所在的服务器位置，如果为空，则意味着该小工具脚本放置在“ <FusionRoot>/widget ”文件夹下。

5.       Label ：该小工具的标签，可能会因小工具类别不同而在界面上起不同的作用，如果是工具栏上的按钮，则表示该按钮上的文字。

6.       Tooltip ：提示内容，可能会因小工具类别不同而在界面上起不同的作用，如果是工具栏上的按钮，则是按钮的提示。

7.       StatusText ：状态栏上的文字，可能会因小工具类别不同而在界面上起不同的作用。

8.       ImageUrl ：小工具使用图片的 URL 地址，可能会因小工具类别不同而在界面上起不同的作用。

9.       ImageClass ：如果小工具使用的图片是一个大图片上的一部分（有些人会通过设置式样（ style ）中不同的 background-position 来让某一部分网页区域所采用的图片是一个大图片上的一部分，这样，浏览器可以一次加载那个包含着所有图片的大图片，而不用为每一个图片请求一次服务器，从而减小带宽占用，提高性能），这个是该小工具采用的图片所用的式样（ style ）。

10.   Extension ：做为小工具信息的扩展，用于包含一些该小工具独有的信息，在代码 3-1 中未示意出。

11.   StandardUi ：小工具是否是标准界面的一部分，这个属性被 MapGuide 配置工具使用，如果是 true ，在新建一个灵活网页布局的时候会将这个小工具加入到界面中。

12.   ContainableBy ：该工具可以被包含在什么容器中。这个属性被 MapGuide 配置工具使用。如果是 Any ，就表示可以是任何容器，大部分工具栏上的小工具都是用的这个值。如果是 Splitterbar ，就表示只能放置在状态栏中。如果是空，则一般是只能独立放置在窗格中。

13.   Parameter ：该工具支持的参数，这个参数的值可以由网页布局配置人员利用 MapGuide 配置工具生成，最终放置在网页布局文件中。类似于该小工具的“选项”。

这里要注意的是，小工具的信息文件并不包含该小工具界面上的布局信息，而只是用 ContainableBy 给出小工具可以被布局的方式（放置在工具栏 / 状态栏 / 窗格）。界面上的布局信息位于我们后面会详细介绍的网页模板中。

除了小工具信息文件之外，每个小工具还要提供一个包含有其执行脚本的 js 文件。如果小工具信息的 Location 没有特别说明的话，小工具的执行脚本文件会位于 “<FusionRoot>/widgets” 文件夹下，其名称为 “< 小工具类型 >.js” 。在这个文件中，由于 Fusion 中小工具执行脚本采用的是面向对象的方式编程，所以小工具需要将执行脚本封装在一个 Javascript 类中并实现一些平台规定的 API ，这样它就会被基础平台正确的加载和调用了。

代码 3-2 是 About 组件执行脚本的源代码，该文件位于 <FusionRoot>/widgets/About.js 中，从中我们可以看出编写一个小工具执行脚本需要做些什么。

/** * Fusion.Widget.About * * $Id: About.js 1656 2008-11-08 21:44:26Z madair $ * * Copyright (c) 2007, DM Solutions Group Inc. * Permission is hereby granted, free of charge, to any person obtaining a * copy of this software and associated documentation files (the "Software"), * to deal in the Software without restriction, including without limitation * the rights to use, copy, modify, merge, publish, distribute, sublicense, * and/or sell copies of the Software, and to permit persons to whom the * Software is furnished to do so, subject to the following conditions: * * The above copyright notice and this permission notice shall be included * in all copies or substantial portions of the Software. * * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER * DEALINGS IN THE SOFTWARE. */ /******************************************************************** * Class: Fusion.Widget.About * * About widget to display a pop-up window about the application. The contents * of the page are come from an HTML page set as the AboutUrl extension property. * * **********************************************************************/ Fusion.Widget.About = OpenLayers.Class(Fusion.Widget, { uiClass: Jx.Button, _nWidth: 500, _nHeight: 400, /* the url to open. If specified, it is relative to the * application, not fusion */ _sAboutUrl: null, /* the default url */ _sDefaultUrl: 'widgets/About/About.html', /* * Constructor: About * * Parameters: * * widgetTag - JSON node for this widget from the Application definition * */ initializeWidget: function(widgetTag) { var json = widgetTag.extension; this._sAboutUrl = (json.AboutURL) ? json.AboutURL[0] : this._sDefaultUrl; if (this._sAboutUrl == this._sDefaultUrl) { this._sAboutUrl = Fusion.getFusionURL() + this._sAboutUrl; } this.enable(); }, /** * Function: execute * * opens a pop-up window with the about information when invoked * */ activate: function() { //console.log('About.execute'); var sFeatures = 'menubar=no,location=no,resizable=no,status=no'; sFeatures += ',width=' + this._nWidth; sFeatures += ',height=' + this._nHeight; window.open(this._sAboutUrl, 'AboutPopup', sFeatures); } });

代码 3-2 “关于”小工具的脚本代码

我们可以看到，该文件声明了一个继承自 Fusion.Widget ，名字为 Fusion.Widget.About 的类。这是平台要求的，小工具必须继承自为 Fusion.Widget ，且名字为 Fusion.Widget.< 小工具类型 > 。这里要说明的是，虽然 Fusion.Widget.Map 从用户角度看起来是小工具，而且也是放置在 Fusion.Widget 命名空间下的，但是它并不是继承自 Fusion.Widget 而是 Fusion.Lib.EventMgr ，而且在 Fusion 框架中，该组件的处理方式明显与其他小工具不同，所以，在解释代码结构的时候，我们倾向于不把它解释为小工具。

如果小工具是放置在工具栏 / 状态栏中的，那么它的 uiClass 属性就会被用来表示最终小工具在界面中的样子。这里 About 仅仅是一个按钮，因此它的该属性值为 Jx.Button 。这样，在初始化界面控件的时候， Fusion 就会调用 Jx.Button 来初始化该小工具。

Fusion.Widget.About 重写了其父类中一个含有参数 widgetTag 名为 initializeWidget 的函数，这个函数就是小工具的初始化函数。当 Fusion 框架初始化小工具的时候，就会调用这个函数，传入的 widgetTag 就是对应的网页布局中跟该小工具相关的配置项转换而成的 Javascript 对象。

       Fusion.Widget.About 还重写了其父类中一个名为 activate 的无参数函数，这个函数会在该小工具被激活时候调用。根据小工具在界面中的样子不同，激活小工具的方式也不相同。激活按钮形式的小工具的方法就是点击该小工具在界面上的按钮。如果小工具需要在小工具取消激活状态时做一些工作的话，那么它还需要重新父类中名为 deactivate 的无参数函数。