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

的无参数函数。