对快速、简单的交流模型设计的需求，对于一个组织的成功变得越来越重要。模型发布通过提供用HTML发布模型的方法解决了这个问题。另外，模型发布还提供了一种产生定制报告的工具。本文将近距离观察这种工具，并提供实例来展示如何定制符合业务需要的 HTML输出和报告。

目的

本文的目的是详细描述基于XSL的发布转换模板，你可以利用模板来增加或改变功能。本文假定你已经理解了XSL和相关技术，因此将不再介绍XSL。

文章结构

本文分成以下几部分：

概述 IBM? Rational? Software Modeler (RSM)产品以及模型发布提供的特色

一本“菜谱”——作为一份快速开始向导，展示常见的定制任务

深入到设计细节、技巧，以及你可能使用到的技术

关于本文使用期限的说明

本文是专门论述RSM和 IBM? Rational? Software Architect (RSA) 产品中的模型发布功能。可能不适用于模型发布的更新版本

什么是RSM和模型发布？

RSM是一种利用UML（统一建模语言）来描述任何可以被建模的事物的可视化模型工具。注意到RSA产品位　于RSM产品的顶层，包含与RSM同样的基本功能集。因此当本文提到RSM时，也同样适用于RSA中的相同功能。

RSM和RSA提供了一种软件开发平台，你可以在该平台用Model Development Architecture (MDA)开发软件应用程序。RSM支持的主要功能是在你的团队中，或者利用模型发布在团队间，分享交流复杂模型的能力。

例如，你可能希望模拟一个薪金系统。你可以使用RSM可视化的模拟这个系统。一旦完成建模，你可能想和其他人交流这个模型。使用模型发布你可以用HTML形式 发布模型；另外，你可以从建立的模型中创建和生成你自己的报告

图1所示为用RSM打开一个UML模型项目的屏幕截图

图1： 在RSM中的一个UML项目

为了要公布图1中的模型，只要简单点击 Modeling > Publish > Web。另一方面，如果你希望生成一个报告，点击 Modeling > Publish > Report。下面的图2显示模型发布模型概览，图3显示一个简单的报告。

图2： 模型概览

本文已经指出你可以定制模型发布 XSL来得到自定义的模型发布，并且创建模型报告。下面将带领你漫游一些有用的定制场景。

快速开始“菜谱”

这部分将举一些你可能希望加到XSL中的简单的用例。首先，你将浏览定制报告模板的创建，还将涉及如何在一个PDF格式的报告中嵌入一种字体。然后，你将学习如何定制并发布起始页面（例如，增加一个公司标志）。最后，这个向导将带你通过定制一个XSL UML元件管理器来输出定制文档。

注意：XSL可以用你喜爱的文本编辑器编辑。

创建一个定制的PDF报告

报告能完成许多有用的功能。例如，你可能在做模型统计，比如每个程序包中的模型有多少个类。如果你需要这类报告，这部分内容很适合你。

需要寻找的关键点是插件的路径，取决于软件的安装，该路径可能不同，相对于INSTALLDIR的位置是：

一旦找到插件位置后，你将要进入报告路径。创建定制报告需要的所有工作都将在这个路径完成：

在开始前，有一些步骤你需要做：

增加入口到reports.manifest文件，以在RSM注册你的项目

创建一个report.xsl文件并且执行XSL转换

reports.manifest 文件包含用户接口（UI）使用的信息，移植一系列你可以创建的报告。reports.manifest文件　内部结构如下：

要增加一个报告，增加一个 <reportManifest> 入口到这个文件。要这样做，拷贝一个现有的报告显示入口然后改变数值以符合你的需要。例如：

改变的关键域为： 姓名，描述，作者，和 XSLFile。还要注意 outFileExt 入口，它定义生成的输出文件类型。在这个例子中，将生成PDF格式的报告。

reportManifest 的各个域如表1所示。可选域同样被标出。

表1： 报告显示域

下面是一个OCL查询的例子，使用可选择的OCL报告显示入口：

然后开始创建你的报告，获得现有的报告样本，复制然后重命名为 MyReport.xsl，与加到reports.manifest文件的信息相匹配。

现在用文本编辑器打开文件然后寻找：

将其改为：

接着，保存文件并生成报告的UI。你应该看到列出的报告如图4 所示。

图4： 报告列表

选择并生成适合的报告。检查你在HTML浏览器中看到的 My First Metric Report 。也不过如此而已。

使用符号字符集处理PDF报告

如果你想产生一个有特殊符号或者扩展符号字符（例如中文字符集）的报告，那么你将需要在PDF文件中嵌入这种字体。这是PDF要求的。模型发布 feature有一个框架，允许你不仅可以使用UI生成自己的报告，还可以提供报告中需要的字体。要在报告中嵌入一种特殊的字体，你必须按照下面步骤做：

找到你想要嵌入的字体

从字体中利用Format Object Processing (FOP)工具生成一个metrics-file，它构成一个开源的Java API(应用程序接口)。

配置userconfig.xml文件来描述：

字体metrics-file的位置

字体将要被嵌入的位置

编辑 报告 XSL文件，并说明你想要使用的字体

嵌入字体的详细资料

本文下面的部分将带领你走过上面提到的每一步，在这个过程中描述如何设置你的字体使它与报告生成器一起工作。注意PDF要求记录在 http://xml.apache.org/fop/fonts.html。此外，你可以查看FAQ http://xml.apache.org/fop/faq.html。

找到你想嵌入的字体

首先，找到你想嵌入的字体。记住这个字体必须遵守PDF要求文档中规定的字体嵌入规则(http://xml.apache.org/fop/fonts.html)。另外，你必须考虑到所使用字体的合法性。你需要问，“这是一个合法的嵌入吗？”。尽管本文指出一个工具可以给你关于这个状态的提示，你仍有责任确定其合法性。

生成一个metrics文件(Minor Minor)

你生成统计文件是为了给定制字体提供支持。本文简单描述了字体文件的属性，它可以被嵌入到PDF中。

此外，要得到关于如何去做的详细信息，查询Apache的技术页面http://xml.apache.org/fop/fonts.html#embedding。

这个例子展示了如何嵌入一个TTF（True Type字体）。要得到统计数据，你需要能够获得这种信息的工具，这些工具可以从 http://xml.apache.org/fop/download.html。

注意：如果你创建一个脚本文件（批处理或者命令行）并且从脚本执行命令来做这项工作，可能容易得多。

得到统计文件的命令如下：

将输出以下信息：

特别注意输出的最后一行，它告诉你关于你使用的字体嵌入是否合法的提示。

配置一个userconfig.xml文件

userconfig.xml文件用来告诉FOP（和我们最后的报告生成器）到哪里寻找你想嵌入的字体。这个文件可以放在插件程序路径下(com.ibm.xtools.publish.uml2_6.0.0)。这是查找时的关键点，因为——依赖于软件安装——这个路径可能不同：

找到插件程序后，你将要进入报告路径：

在这个路径下，你将看到userconfig.xml文件。打开它，将会看到如下所示的字体部分：

你应该给这部分增加一个入口。

注意：这部分大多注释为默认值，所以确定你加入了你的字体数据，这样它就不会被注释了。注释部分以 <!- and end with >开头。

一个userconfig.xml的入口（在Linux机器上）看起来可能是这样的：

增加字体入口后，保存并关闭它。

编辑你的报告来使用这种字体

最后一步就是告诉你的报告使用这种字体。例如，让你的样例报告(MetricsReport.xsl)使用Mincho字体，你需要找到所有与 <fo:block 相关的部分，并且编辑（或增加）一个字体——系列标签。 一个更新块可能如下所示：

保存报告。

现在你已经准备好运行生成一个包含特殊字体的PDF报告。为了验证你的PDF报告有这种字体，你可以用 Adobe? reader查看文件。

选择性生成报告

报告生成机制是灵活及可设计的，因此你可以增加你自己的报告（如前所述）。这种灵活性允许你编写XSL支持，以任何格式输出数据。一些简单的可能纯文本，HTML，DHTML和CDF。如果你在输出PDF格式时遇到任何问题，考虑编写XSL，这样就可以生成不同的输出。

使用XSL定制模型发布

这部分讨论直接修改模型发布模板来得到定制的模型HTML输出。在开始工作之前，你应该备份这些文件。

注意：本文假定你已经理解XSL，XPATH，以及相关技术。

修改已经发布的模型开始页面

默认值，开始页面使用一个标准图形和布局，但是也许你希望显示自己公司的标志或其它信息。要定制该页，你需要编辑一个叫做ProjectPublish.xsl的文件，它可以在插件程序路径找到：

要改变标题，打开ProjectPublish.xsl文件改变下面一行内容以放置你的图片：

注意：新图象需要放在旧图象的位置，或者路径必须被指定为图象信息票签的一部分。

然后，让我们改变Published Models使用的字体。你可以利用CSS（Cascading Style Sheet）信息。看到下面代码一行描述这个串的CSS信息：

这个声明本质上是说，“使用CSS信息在LargeTitle部分下描述”。

因此CSS信息是如何包括的？如果你观察ProjectPublish.xsl的顶部，你将看到这个转换文件将生成如下HTML。

要注意这个代码“content\Webpublish.css”。当生成输出时，这里是真正的CSS文件将存储的地方。因此，现在要问的问题是：“CSS信息最初存储在哪里呢？”CSS文件最初是另外一个转换文件叫做Css.xsl，它可以在下面地址找到：

观察我们找到的LargeTitle文件：

保存文件并生成你的模型。现在你应该有一个新的首面显示你定制的图片，并且用一种大号红色带下划线的字体显示 published models 。

修改元件报告

现在你将看到如何定制一个模型元件的外形、感觉和内容（本例中，修改为UML Attribute元件生成的输出）。要做这些，创建一个模型，该模型有一个类包含至少一个属性（如图5所示）。

图5： 包含一个属性的类的模型

第一步是改变属性 A1的详细资料的默认输出。通常——如果HTML为模型而生成——将出现如图6所示的输出。

图6： 属性的默认HTML输出

让我们通过如下步骤把它变得时髦些：

把元件标题从元件名改成元件的全名 (FQN)

改变签名字体

用浅蓝色勾勒表格边框

要完成这些内容，XSL必须被修改。首先寻找NamedElementContent.xsl文件，该文件位于如下路径：

这个文件负责大多数的元件转换详细资料，因为大多数模型元件有这类似的内部结构。一旦你打开这个文件，搜索OwnedAttribute，你应该可以找到六个入口。XSL文件的这些区域代表与属性元件相关的转换代码。

注意：XSL称UML属性为OwnedAttribute， 因为属性的中间XML (可扩展标志性语言)文件节点被称为‘OwnedAttribute'。 这里是你的XSL为属性处理的中间XML的一个片段：

在此你感兴趣的是属性的详细资料，因此继续查找如下注释：

它将使我们得到OwnedAttribute标签的FQN 属性。

注意：了有效的调整 XSL，你需要理解它将处理的内容。要这样做，你可以查看中间形式。到你发布模型的地方并向内容目录下看，在那里你将发现一系列HTML和XML文件。XML文件代表由XSL处理的模型。你可以利用XML编辑器检查XML来寻找有关处理内容的信息。在这个例子中, 为属性查找中间数据的过程显示，全名是如何被记录的。标签属性 publish:qualifiedname包含了这些信息。要得到更多信息，查看后面的 深入观察模型发布的详细资料部分。

接下来，往后看这段代码的下面几行，你将找到XSL代码部分，这些代码将生成属性签名。要改变属性签名的字体，编辑下面几行：

特别地，你对 <pre> HTML标签感兴趣。既然我们的目的是增加一种字体和一种颜色，这看起来适合使用CSS信息的地方。此外，你希望编辑Css.xsl文件。在我们的源文件夹根部找到这个文件，编辑Css.xsl文件并增加：

现在保存Css.xsl文件。

然后回到NamedElementContent.xsl文件并编辑 <pre>HTML标签，将它改为：

这将引入我们的样式信息，因此当HTML生成时，签名将显示为蓝色。

最后，让我们改变表格的颜色。要改变表格颜色，在我们刚编辑过的代码下面几行的如下注释。

注意：在文件中有两个注释叫 <!-- Output the properties table --> ，其中你想要的就在刚编辑过的代码下面几行。

由代码向模板发出命令，模板与调用签名相匹配。在本列中，模板可以在resources\utility目录中的UML2Utility.xsl文件中找到。在UML2Utility.xsl中寻找下面的内容：

一旦你找到模板，在主机中寻找如下信息：

在这个例子中，你需要增加另一个属性到标签，所以改变如下行：

注意，如果你想要改变表格中文本的颜色，可以简单的编辑PropertiesTable CSS入口。

你的工作最终成果如下图7所示。

图7： 定制的输出

深入观察模型发布的详细资料

本文的剩余部分介绍了结构和设计的详细资料，并提供更多关于在模型发布 XSl环境中工作的情况。这意味着作为定制和使用XSL框架的更深入的资源。

模型是如何在一个nutshell里发布的呢？

发布一个模型有一系列步骤，我们将简要的讨论。

要发布一个模型你需要按照如下步骤：

创建你的模型

选择模型元件

在菜单中点击 Modeling > Publish

在这里模型已经发布了，程序建立了一个Document Object Model (DOM)并且将其写入中间的XML文件（数据）。这个中间的XML数据随后被XSL模板使用，XSL轮流生成HTML版本的模型，并展现在浏览器里。图8说明了这个过程。

图8： 从模型到HTML页面

注意到中间的XML文件是从模型的各个程序包中创建的。根XML文件按照这种习惯命名：

每一系列字母被生成，如Globally Unique Identifier (GUID)，以证明这个文件的名字是唯一的。

可见的布局元件

这部分简要的描述了可见元件是如何与物理文件系统布局相关联的。这将帮助你理解物理XSL文件布局和事物是如何正确工作，以建立一个发布的模型。

让我们看看你的模型（如图9所示）。

图9： 模型结构

图10说明模型发布后的HTML开始页面。

图10： HTML开始页面

当你点击模型链接时，在本例中是jdk17rev，窗口显示模型的详细资料。详细资料由框架组成（如下图11所示），包含三个主要框架：

图11： 模型详细资料

Element Context框架由一个HTML页面（见图12）组成，包含：

一个导航条

我们查看的元件的详细资料

如果可能，还有包含子系统的元件书签，如一个类的属性和操作。

图12： Element context

物理文件系统布局

XSL文件存储在产品安装路径下；在Linux (同样在 Microsoft? Windows?操作系统)，可以在如下的插件程序路径找到：

如前文所述，由于安装路径不同，com.ibm.xtools.publish.uml2_6.0.0可能存储在不同路径下。

当你找到插件程序后，转到资源目录：

从这里你将看到如图13所示的结构：

图13： 物理文件系统布局

表2在一个非常高的层面描述各个文件夹的作用或内容。表3至7，详细展示这些文件夹。

文件夹和文件布局的总体回顾

表2： 文件夹布局总体回顾

表3： 资源文件详细资料

表4： l10n文件详细资料

表5： 报告文件详细资料

表6： uml2content文件详细资料

表7： 应用文件详细资料

调试发布XSL，提示和资源的模型

这部分是为了帮助你找到文件和工具，它们是调试发布XSL所需要的。而不是关于设置和调试的教程。　

对于大多数简单的改动，你大概可以侥幸地使用文本编辑器编辑XSL，但是对于大型的工作,你大概就需要使用XSL调试器了。

要调试XSL，你可以采用下面方法的一种：

给XSL增加输出语句（XSL消息，或者类似的内置XSL常式）

使用编辑器/调试器

这两者有各自适用的时候，但如果你需要一个成熟的编辑器或者调试器，市场上有几个可供选择，它们有不同的功能等级，操作和价格范围。我们知道的一些是：

编辑器/调试器

注意：我们留下这些由你决定它们是否有用

要调试XSL你需要一些东西：

当模型发布时生成的中间的XML

XSL转换文件

一个调试器

中间的XML文件由模型中的每个程序包生成。根XML文件名依照下面的方式命合，可以通过最后的 _root.xml 来识别：

我们前面已经讨论过XSL，你当然知道如何使用调试器。