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 所示:
代码 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 中,从中我们可以看出编写一个小工具执行脚本需要做些什么。
代码 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 的无参数函数。