经典教程翻译系列: Mach-II应用程序配置指南

作者: Mach-II.com 译者: Franks Pan

Mach-II应用程序的配置包括两个文件：mach-ii.xml和index.cfm。
先从www.mach-ii.com下载MachAppSkeleton。

对于www.mach-ii.com提供的范例程序，index.cfm文件被放在程序根目录下(例如 ContactManager/index.cfm)，mach-ii.xml文件则放在一个叫做config的子目录下（例如ContactManager/config/mach-ii.xml）。

Mach-II框架代码是一个一次性安装（译者注：类似绿色软件，解压即可）的工具包，所有Mach-II程序都可以通过统一路径使用它。通常情况下，框架文件（一个MachII的目录以及所有必要文件）需要安装在ColdFusion服务器的wwwroot目录下，否则需要做映射上的调整。调用其中的组件时需要使用组件的绝对路径（例如MachII.framework.AppManager）。

1．index.cfm（以及MachII/mach-ii.cfm）
Index.cfm文件是框架接受请求的入口。需要在这里为框架设置三个重要属性变量：MACHII_CONFIG_PATH，MACHII_CONFIG_MODE，以及MACHII_APP_KEY。

MACHII_CONFIG_PATH必须是你的应用程序设置文件（一般是mach-ii.xml）的绝对路径。可以使用内建函数ExpandPath（）向mach-ii.xml文件传递相关路径，来完善该选项。

MACHII_CONFIG_MODE的值可以是－1，0或者1，改动会在配置文件重新载入是生效。
×－1（从不重新载入）：不重新载入配置文件（推荐供作品部署阶段使用）；
×0（动态载入）：当mach-ii.xml文件更新后，自动载入更新文件（推荐供开发阶段使用）；
×1（经常更新）：一有请求，就更新配置（会影响性能，不推荐使用）。

程序框架在每次配置文件重新载入时复位。这就意味着，很多对象实例会被创建，mach-ii.xml文件被读入，进而被修缮。同样意味着，包含在框架组件（例如listener）中的某些状态信息会被重置。

MACHII_APP_KEY是用来标志cf应用程序下的Mach-II子程序，有助于各个子程序在总程序下相互协作。默认状态下，这个程序标志符会设为程序所在文件夹的名称。

index.cfm的例子：
<!--- Set the path to the application's mach-ii.xml file. --->
<cfset MACHII_CONFIG_PATH = ExpandPath("./config/mach-ii.xml") />
<!--- Set the configuration mode (when to reload): -1=never, 0=dynamic,
1=always --->
<cfset MACHII_CONFIG_MODE = 0 />
<!--- Set the app key for sub-apps within a single cfapplication. --->
<cfset MACHII_APP_KEY = GetFileFromPath(ExpandPath(".")) />

2．mach-ii.xml

Mach-ii.xml是Mach-II程序的总配置文件。该文件的DTD文件名为“mach-ii_1_0.dtd”，也包含在框架代码包里。

<mach-ii>:[version]
配置元素的根元素是带有版本号（是可选项）的<mach-ii>。版本号用来确定配置文件支持的Mach-II框架的版本。

配置文件共有6个主要元素用来定义程序及其组件。

Mach-ii.xml文件的例子：

<mach-ii version="1.0">
<!-- PROPERTIES -->
<properties>
...
</properties>

<!-- LISTENERS -->
<listeners>
...
</listeners>

<!-- EVENT-FILTERS -->
<event-filters>
...
</event-filters>

<!-- EVENT-HANDLERS -->
<event-handlers>
...
</event-handlers>

<!-- PLUGINS -->
<plugins>
...
</plugins>

<!-- PAGE-VIEWS -->
<page-views>
...
</page-views>
</mach-ii>

<properties>
<property> : name, value

<properties>允许你为程序配置框架实例。在每个配置文件中，可以配置6个参数。这些变量可以配置在在<properties>下一级的<property>元素里。

这些必要的参数是：
·defaultEvent：默认事件，如果请求里不含任何事件时，框架会默认地；
·exceptionEvent：异常事件，如果程序里未被定义句柄的异常被触发，框架会触发该事件；
· maxEvents：定义单一请求最大可触发多少事件；
· applicationRoot：程序文件夹相对于服务器根目录的位置（例如：”/SampleApp”）；
· eventParameter：定义传递触发事件的请求变量的名称（form或者url）；
· parameterPrecedence：决定form和url在发生请求冲突的时候，哪个有更高的优先权。

例子：
<mach-ii>
<!-- PROPERTIES -->
<properties>
<property name="defaultEvent" value="showHome" />
<property name="exceptionEvent" value="exception" />
<property name="applicationRoot" value="/ContactManager" />
<property name="eventParameter" value="event" />
<property name="parameterPrecedence" value="form" />
<property name="maxEvents" value="10" />
</properties>
. . .
</mach-ii>

<listeners>
<listener> : name, type
在<listeners>里，你可以为程序注册listener。Listener的name属性必须是独立无雷同的。Type属性中必须给出通向该组件的完整地址。

<invoker> : type
Listener中还需定义<invoker>子元素，其type属性也要所完整路径。

Listener里也可以用<parameters>和<parameter>元素来定义更具体的配置信息。

例子：
<mach-ii>
...
<!-- LISTENERS -->
<listeners>
<listener name="ContactManager"
type="ContactManager.model.ContactManager">
<invoker type="MachII.framework.invokers.CFCInvoker_EventArgs" />
<parameters>
<parameter name="param1" value="value1" />
</parameters>
</listener>
</listeners>
. . .
</mach-ii>

<event-filters>
<event-filter> : name, type

<event-filrers>元素用来注册事件过滤器。各个过滤器的name属性不可以雷同。Type必须是组件的完整路径。
例子：

<mach-ii>
. . .
<!-- EVENT-FILTERS -->
<event-filters>
<event-filter name="simpleFilter" type="Test.filters.SimpleFilter " />
<parameters>
<parameter name="param1" value="value1" />
</parameters>
</event-filter>
</event-filters>
. . .
</mach-ii>

<plugins>
<plugin> : name, type

使用<plugin>注册插件。属性设置要求和上面讲过的listener，event-filter一样。

例子：
<mach-ii>
. . .
<!-- PLUGINS -->
<plugins>
<plugin name="simplePlugin" type="Test.plugins.SimplePlugin">
<parameters>
<parameter name="param1" value="value1" />
</parameters>
</plugin>
</plugins>
. . .
</mach-ii>

<event-handlers>
<event-handler> : event, [access]
<event-handlers>用来指定触发程序事件的途径。属性设置要求和上面讲过的listener、event-filter一样。Access属性为可选项，值只能是public或者private，其中public为默认值。

在请求的参数中明确过的event必须是public的，经由同程序的listener通告的事件可以是public的，也可以是private的。

例子：
<mach-ii>
. . .
<!-- EVENT-HANDLERS -->
<event-handlers>
<event-handler event="showHome" access="public">
. . .
</event-handler>
</event-handlers>
. . .
</mach-ii>

任何<event-handler>体内都可以设置一下元素：
<announce> : event, [copyEventArgs]
<announce>元素用来通告一个新的事件。copyEventArgs 属性确定是否拷贝当前事件的<event-arg>变量。

例子：
<event-handler event="editUser" access="public">
<announce event="showEditUserForm" copyEventArgs="true" />
</event-handler>

<event-arg> : name, [value], [variable]
<event-arg>元素设置当前触发事件的变量。Name属性确定变量名称，可选项value属性值可以为变量确定一个明确的值。可选项variable为变量设置供引用的变量。以上两个属性每次最多只可设置一个。如果variable为被设置，其值由空白字符串代替。

例子：
<event-handler event="editUser" access="public">
<event-arg name="submitFormEvent" value="editUser" />
<event-arg name="user" variable="session.user" />
...
</event-handler>

<event-mapping> : event, mapping
<event-mapping>元素可以为事件间提供临时映射。它值存在于当前被触发事件的生命中期里。
例子：
<event-handler event="createContact" access="public">
<event-mapping event="contactAdded" mapping="showContact" />
...
</event-handler>

<event-bean> : name, type, [fields]
<event-bean>元素用来在当前事件里生成一个bean。Name属性确定其名称。Type属性确定其路径。可选项field确定事件的哪个域来调用bean.

例子：
<event-handler event="createContact" access="public">
<event-bean name="address" type="model.Address"
fields="street,city,state,zip" />
...
</event-handler>

<filter> : name
<filter> 用来提供过滤器给触发事件。Name属性用来引用<event-filter>。可以为其设置多个<parameter>元素。

例子：
<event-handler event="editContact" access="public">
<filter name="loggedInFilter">
<parameter name="invalidEvent" value="showLoginForm" />
</filter>
</event-handler>

<notify> : listener, method, [resultKey]
<notify>元素用来调用listener方法来使用当前事件及其变量。Listener属性指定一个注册的listener。Method属性指定要调用哪个listener方法。可选项resultKey指定一个用来存放方法返回值的变量名。

例子：
<event-handler event="createContact" access="public">
<notify listener="loginListener" method="login"
resultKey="session.isLoggedIn" />
</event-handler>

<view-page> : name, [contentKey], [append]
<view-page>用来调用一个page-view来发布，同时还可以储存已经生成的内容。Name属性值指向一个注册的page-view。可选项contentKey可储存生成的视图内容给指定变量，来代替输出行为。可选项append（默认为false）指contentKey值不追加（而是覆盖）在旧值之后，若这值为true则相反。

例子：
<event-handler event="showContactForm" access="public">
<view-page name=”header” contentKey=”request.header”
append=”true” />
view-page name="contactForm" />
</event-handler>

<page-views>
<page-view> : name, page
<page-views>元素用来注册page-view(网页视图)。Name属性不可雷同。Page属性指定CFM页在程序根目录下的相对位置。

例子：
<mach-ii>
. . .
<!-- PAGE-VIEWS -->
<page-views>
<page-view name="mainTemplate" page="/views/mainTemplate.cfm" />
</page-views>
. . .
</mach-ii>