Level: Introductory Mike Boyersmith, Staff software Engineer, IBM Cheng-Yee Lin (clin@us.ibm.com), Development Manager, IBM Rational Software
14 Jun 2005 Updated 03 Oct 2005 The need to communicate model design quickly and easily has become increasingly important to an organization's success. Model publishing solves this problem by providing the means to publish models in HTML. In addition, model publishing provides a facility for generating custom reports. This article takes a closer look at these facilities, and gives real-world examples of how you can customize both the model published HTML output and the reports to suit your businesses needs.
Purpose
The purpose of this article is to describe the XSL-based model publishing transformation templates in enough detail that someone might be able to work with the templates to add or change functionality. This article assumes that you already have an understanding of XSL and related technologies, and therefore will not cover XSL.
Article layout
This article is broken up into three sections:
- A brief look at the IBM® Rational® Software Modeler (RSM) product and what the Model Publishing feature provides
- A "cookbook" that is meant as a Quick Start guide to performing common customization tasks
- A dive into design details, tips, and techniques that you might leverage.
A note about article lifespan
This article is written specifically for the model publishing feature in the RSM and IBM® Rational® Software Architect (RSA) products, version 6.0.0. Newer versions of model publishing may make the information in this article obsolete.
What is RSM and model publishing?
RSM is a visual modeling tool that uses UML (Unified Modeling Language) to describe anything that can be modeled. Note that the RSA product is layered on top of RSM, and contains the same set of base functionality as RSM. When this article mentions RSM, it is also referring to the same functionality that is present in RSA.
RSM and RSA provide a software development platform which you can use to take the Model Development Architecture (MDA) approach for developing software applications. Among the major functionality supported by RSM is the capability to share and communicate the modeled complexity within your team, or across teams through model publishing.
For example, you might wish to model a system of behavior for a payroll system. You can visually model this system using RSM. Once the modeling is complete, you may want to communicate the modeling to others. Using model publishing you can publish the model as HTML; in addition, you can create and generate your own reports from the models you have created.
Figure 1 shows a screen shot of RSM with a UML Modeling project open.
To publish the model in Figure 1, simply click Modeling > Publish > Web. If you wish to generate a report, on the other hand, click Modeling > Publish > Report. Figure 2, following, shows what a model-published model overview looks like, while Figure 3 shows a sample report
| |
Figure 2: Model overview
|
| |
Figure 3: Sample Report
|
This article has hinted that you can customize the model publishing XSL to achieve custom model publishing, and create model reports. The rest of this article will walk you through some useful customization scenarios.
Quick Start "cook book"
This section will illustrate several simple use cases that you may want to add to the XSL. First, you will walk through creating custom report templates, as well as touch on how to embed a font in a PDF report. Then you will learn how to customize the published Start page (for instance, adding a company logo). Finally, this guide will walk you through customizing an XSL UML element handler to output custom documentation.
Note: XSL can be edited using your favorite text editor.
Creating a custom PDF report
Reports accomplish many useful things. For example, you might gather metrics on a model, such as how many classes are in the model per package. If you need this kind of reporting, this section is for you.
The key thing to look for is the plug-in directory, as depending on the software install this directory might be in a different, relative to INSTALLDIR, location:
[INSTALLDIR]/rsm/eclipse/plugins/com.ibm.xtools.publish.uml2_6.0.0
Once you have located the plug-in you will want to navigate to the reports directory. All of the work needed to create a custom report will be done in this directory:
../com.ibm.xtools.publish.uml2_6.0.0/resources/reports
To begin, here are the steps you need to take:
- Add entries to the reports.manifest file to register your new report with RSM
- Create a report.xsl file and flush out the XSL transformation
The reports.manifest file contains information employed by the user interface (UI) to populate a list of reports that you can generate. Internally the reports.manifest file has the following structure:
< reports >
< reportManifest >
< /reportManifest >
< reportManifest >
< /reportManifest >
< /reports > |
To add a report, add a < reportManifest > entry to this file. To do this, copy an existing report manifest entry and change the values to suit your needs. For example:
< reportManifest
name="My UML Metric Report"
description="My Metric report to test adding my own report "
author="Me"
XSLFile="resources/reports/MyReport.xsl"
outFileExt="pdf"
USING_ICONS="false"
EXTRACTING_DIAGRAMS="false"
DIAGRAM_FORMAT="JPG"
DETAIL_LEVEL="FULL" >
< /reportManifest > |
The key fields changed were: name, description, author, and XSLFile. Also note the outFileExt entry, which specifies the type of output document you are generating. In this example, the report will be generated as a PDF document.
Each field in the reportManifest is described in Table 1. Optional fields are marked as such.
| name | The name of the report shown in UI | | description | The description of the report shown in UI | | author | The author of the report | | XSLFile | Where the XSL template can be found | | outFileExt | The extension of the document you are creating | | oclSelfType | The UML type of the data to be selected. This is an optional field, but if this is used, oclQuery is required. Examples of UML types are Class or Package. | | oclQuery | The Object Constraint Language (OCL) phrase to use for data selection on elements of type oclSelfType. This is an optional field, but if this is used, oclSelfType is also required. (See example below) | | USING_ICONS | A boolean attribute indicating if icons are to be included in diagrams. | | EXTRACTING_DIAGRAMS | Boolean attributes indicating if diagrams are to be created. If false, the diagram report is text only. | | DIAGRAM_FORMAT | Format to use for the diagram files created when EXTRACTING_DIAGRAMS is true. Valid values are GIF, BMP, JPG, or JPEG. | | DETAIL_LEVEL | The level of detail to include. Valid values are FULL for everything or MIMINUM for documentation only. |
| |
Table 1: Report manifest fields
|
Here is an example of an OCL query, using the optional OCL report manifest entries:
<reportManifest
name="Package Report"
description="Reports on packages"
author="John Doe"
xsltFile="resources/PackageReports.xsl"
oclSelfType="Package"
oclQuery="self.oclIsKindOf(Package) and not(self.oclIsKindOf(Model))"
outFileExt="pdf"
USING_ICONS="true"
EXTRACTING_DIAGRAMS="true"
DIAGRAM_FORMAT="GIF"
DETAIL_LEVEL="FULL">
</reportManifest> |
Then, to create your report, take an existing sample report, make a copy of it, and rename it MyReport.xsl to match the information added to the reports.manifest file.
Now open the file in a text editor and search for:
< xsl:text > Sample UML Metric Report for #topLevelName< /xsl:text >
Change this to the following:
< xsl:text > My First Metric Report for #topLevelName< /xsl:text >
Next, save the file and bring up the UI for reports. You should see your report listed, as illustrated in Figure 4.
| |
Figure 4: Report listing
|
Select the appropriate report and generate it. Verify that you see My First Metric Report in your HTML viewer. That's all there is to it.
Dealing with PDF reports that use symbolic character sets
If you want to generate a report that has specific symbols or extended symbolic characters (such as the Chinese character set), then you will need to embed the font in the PDF document. This is a PDF requirement. Helpfully, the model publishing feature has a framework that allows you to use the UI not only to generate your report, but to provide fonts that you need in your report as well. To embed a specialized font in a report you must perform the following actions:
- Locate the font you wish to embed
- Generate a metrics-file from the font using Format Object Processing (FOP) tools, which constitute an open-source Java API (application program interface).
- Configure a userconfig.xml file to describe:
- Where the font metrics-file is located
- Where the font to embed is located
- Edit the report XSL file and make reference to the font you wish to use
The details of embedding a font
The following section of this article will walk you through each step mentioned above, in the process describing how to set up your fonts to work with our report generator. Note that this PDF requirement is documented at http://xml.apache.org/fop/fonts.html. Furthermore, you can look at the FAQ at http://xml.apache.org/fop/faq.html.
Locate the font you wish to embed)
First, locate a font you wish to embed. Remember that the font must comply with the font embedding rules explained in the PDF requirement documentation ( http://xml.apache.org/fop/fonts.html). In addition, you must consider the legality of the font you are using. You need to ask, "Is it legally embeddable?". While this document does point out a tool that can give you a hint as to this status, it remains your responsibility to verify legality.
Generate a metrics file (Minor Minor)
You generate the metrics file in order to provide support for custom fonts. This file simply describes the nature of the font file so that it can be embedded in the PDF.
Again, for detailed information on how you can do this, refer to Apache's technical page at http://xml.apache.org/fop/fonts.html#embedding.
This example shows how to embed a TTF (True Type Font).
To get metrics, you will need tools that can extract this information. These tools can be downloaded from http://xml.apache.org/fop/download.html.
Note: It may be much easier to get this part to work if you create a script file (batch or shell) and run the commands from the script.
The command to extract my metrics file looks something like:
java -cp .\build\fop.jar;.\lib\avalon-framework.ja
r;.\lib\xml-apis.jar;.\lib\xercesImpl.jar;.\lib\xalan.jar org.apache.fop.fonts.
pps.TTFReader -ttcname "MS Mincho"
D:\fop-0.20.5\msmincho.ttc
D:\fop-0.20.5\ttfcm.xml |
This outputs the following information:
TTF Reader v1.1.1
Reading D:\fop-0.20.5\msmincho.ttc...
This is a TrueType collection file with 2 fonts
Containing the following fonts:
* MS Mincho
MS PMincho
Number of glyphs in font: 17807
Postscript format 3
Creating xml font file...
Creating CID encoded metrics
Writing xml font file D:\fop-0.20.5\ttfcm.xml...
This font contains no embedding license restrictions |
Pay special attention to the last line of the output, which gives you an indicator as to whether or not the font you are using is legally embeddable.
Configure a userconfig.xml file)
The userconfig.xml file is used to tell FOP (and ultimately our report generator) where to find the fonts that you want to embed. This file can be located under the plug-in directory,(com.ibm.xtools.publish.uml2_6.0.0). This is the key thing to look for, since -- depending on the software install -- this directory might be in a different (relative to INSTALLDIR) location:
[INSTALLDIR]/rsm/eclipse/plugins/com.ibm.xtools.publish.uml2_6.0.0
Once you have located the plug-in, you will want to navigate to the reports directory:
../com.ibm.xtools.publish.uml2_6.0.0/resources/reports
In this directory, you will see a userconfig.xml file. Open it and scroll down, and you will see a fonts section like this:
< !--
*******************************************************
Add fonts here
*******************************************************
-- >
< fonts >
< font >
< /font >
< font >
< /font >
< /fonts > |
You should add an entry to this section.
Note: much of this section is commented out by default, so make sure that you add your font data so that it's not commented out. Comment blocks begin with < !- and end with >.
An entry in the userconfig.xml (on a Linux machine) might look like this:
< font metrics-file="/myfonts/ttfcm.xml" embed-file="/myfonts/msmincho.ttc" kerning="yes" >
< font-triplet name="Mincho" style="normal" weight="normal"/ >
< font-triplet name="Mincho" style="normal" weight="bold"/ >
< font-triplet name="Mincho" style="italic" weight="normal"/ >
< font-triplet name="Mincho" style="italic" weight="bold"/ >
< /font >
< /fonts > |
Once you have finished adding the font entry, save the file and close it.
Edit your report to use the font
The final step is to tell your report to use the font. For example, to allow your sample report (MetricsReport.xsl) to use the Mincho font, you will need to find all relevant sections of < fo:block and edit (or add) a font-family tag.
An updated block might look like this:
< fo:block font-family="Mincho" text-align="center" font-weight="bold" >
...< /fo:block > |
Save the report.
Now you are ready to run and generate a PDF that contains your special font. To verify that your PDF report has the font, you can look at the document's properties in an Adobe® reader.
Alternative report generation
The report generation mechanism is flexible, and is designed so that you can add your own reports
(as described previously). This flexibility allows you to write XSL that outputs data in any format that XSL transformations support.
A few examples might be pure text, HTML, DHTML, and CDF. The following is an example of how to emit a report as HTML.
Generating a report as HTML
Generating a report as HTML is a matter of defining an XSL report template, registering it with the report system, and finally launching RSA/RSM and executing the newly registered report. In this section, I will show you how to create a very simple report that will create an html file that contains the name of the model.
Start by making a copy of the "ModelDiagramReport.xsl" and call it something like "SimpleHTMLReport.xsl".
Wire up to the reporting framework
Next, wire this template up to the reporting framework using the reports.manifest file. The entry in this file should look something like:
<reportManifest
name="Simple HTML Report"
description="A simple HTML report"
author="Myself"
xsltFile="resources/reports/SimpleHTMLReport.xsl"
outFileExt="html"
USING_ICONS="true"
EXTRACTING_DIAGRAMS="true"
DIAGRAM_FORMAT="JPG"
DETAIL_LEVEL="FULL">
</reportManifest>
|
Note: A full walk through of this report registration process is mentioned earlier in this document.
Creating the basic reporting XSL template
Next, open your new "SimpleHTMLReport.xsl" template in an editor and begin by removing all the existing template sections and the call back to Java FOP extension for PDF generation. The template should now look like:
<?xml version="1.0"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0"
xmlns:fo="http://www.w3.org/1999/XSL/Format"
xmlns:xmi="http://www.omg.org/XMI"
xmlns:uml="http://www.eclipse.org/uml2/1.0.0/UML"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:publish="http://www.ibm.com/Rational/XTools/Publish"
xmlns:redirect="org.apache.xalan.xslt.extensions.Redirect"
extension-element-prefixes="redirect"
xmlns:xalan="http://xml.apache.org/xslt"
xmlns:java="http://xml.apache.org/xalan/java"
exclude-result-prefixes="xmi uml xsi publish xalan java">
<!-- === imports, and variable assigns from the GUI==== -->
<xsl:import href="../utilities/StringUtility.xsl"/>
<xsl:import href="GlobalVariables.xsl"/>>
<xsl:import href="ReportUtility.xsl"/>
<xsl:output method="xml"/>
<!-- Style sheet parameters -->
<xsl:param name="outputDir"/>
<!-- Location for root of output -->
<xsl:param name="imagesDir"/>
<!-- Location of images directory -->
<xsl:param name="tempDir"/>
<!-- Location of temp directory -->
<xsl:param name="rootFile" select="'root.html'"/>
<!-- The name of the root html file -->
<xsl:param name="overviewFile"/>
<!-- The name of the overview html -->
<xsl:param name="foContextDir"/>
<!-- this is where we will add our templates in a minute-->
</xsl:stylesheet>
|
Fill in the details
Next, add two templates under the comment:
<!-- this is where we will add our templates in a minute-->
To do this, create an entry point template using the "/" match character to tell XSL that this is where to start working from. It looks something like the following:
<!-- starting Template -->
<xsl:template match="/">
<xsl:apply-templates select="publish:report/uml:Model|publish:report/ownedMember"/>
</xsl:template>
|
Next, add in a second template section which gets called from the main "/" template and looks something like:
<!--called template that generates a simple html page, with model name -->
<xsl:template match="uml:Model|ownedMember">
<xsl:variable name="reportName">
<xsl:value-of select="$rootFile"/>
</xsl:variable>
<xsl:variable name="reportFullPathName">
<xsl:value-of select="concat($outputDir, $fileSep, $reportName)"/>
</xsl:variable>
<redirect:open select="$reportFullPathName"/>
<redirect:write select="$reportFullPathName">
<html>
<xsl:variable name="title" select="@name"/>
<body>
The Name of the Model is: <b> <xsl:value-of select="@name"/> </b>
</body>
</html>
</redirect:write>
<redirect:close select="$reportFullPathName"/>
</xsl:template>
|
Note that the trick in emitting HTML comes down to using XSL processing commands to output your stream of data to a file. In this case we use redirect:open, redirect: write, and redirect:close to do the work of outputting our results to a file.
Finally, save your work and you should be ready to run. If you have RSA or RSM up, you may need to shut down the application and restart it for the new template to be executable.
That's all there is to this. For more detailed reports, you just need to enhance your template match queries and build templates to mine the data. Finally, you need to output your results to a file using the redirect commands.
Customizing model publishing using XSL
This section discusses modifying the model publishing templates directly in order to get custom HTML output of your model. Before you begin to work with the XSL templates, you should back up these files.
Note: This article assumes that you have an understanding of XSL, XPATH, and related technologies.
Modify the Published Models start page
By default, the start page uses a standard graphic and layout, but perhaps you want to display your organization's logo or other information. To customize this page, you need to edit a file called ProjectPublish.xsl, which is found in the plug-in directory:
...\com.ibm.xtools.publish.core_6.0.0\resources
To change the displayed banner, open the ProjectPublish.xsl file and change the following line to point to your image:
< img src="overview_banner.jpg"/ > |
Note: either the image needs to be located where the old image was, or a path must be specified as part of the image information tag.
Next, let's change the font that is used to display the Published Models string. You can do this by taking advantage of CSS (Cascading Style Sheet) information. Looking at the code, you see that the following line describes CSS information about this string:
This statement essentially says, "use the CSS information described under the section LargeTitle".
So how is the CSS information included? If you look at the top part of ProjectPublish.xsl you'll see that this transformation file will generate the following HTML.
< link href="content\WebPublish.css" rel="stylesheet" type="text/css"/ > |
Of note in this code is the "content\Webpublish.css". This is where the real CSS file will be stored when the output is generated. So now the question to ask is, "where is the CSS information initially located?" Well, the CSS file is originally another transformation file called Css.xsl, which can be located under the following directory:
plugins/com.ibm.xtools.publish.uml2_6.0.0/resources
Looking at this file for LargeTitle we find:
.LargeTitle
{
font-size:large;
font-weight:600;
}
Change this to something like:
.LargeTitle
{
color: #ff0000;
font-family: Helvetica;
font-size: 18pt;
text-decoration : underline;
} |
Save the file and generate your model. You should now have a new start page that displays your custom image, and shows the text published models in a large red font with underlining.
Modify what an element reports
Now you'll see how to customize the look, feel, and content of a model element (in this case, to modify the generated output for UML Attribute elements). To do this, create a model that has a class with at least one attribute in it (as shown in Figure 5).
| |
Figure 5: Model with a class with an attribute
|
The first step is to change the default output for the details of attribute A1. Currently -- if HTML is generated for the model -- the output shown in Figure 6 is produced.
| |
Figure 6: Default HTML output for attribute
|
Let's make this a bit snazzier, by doing the following:
- Change the title from just the element name to its Fully Qualified Name (FQN)
- Change the font used in the signature
- Outline the table in the color light blue
To accomplish this, XSL must be modified. Begin by looking at the NamedElementContent.xsl file, which is located in the following directory:
...\plugins\com.ibm.xtools.publish.uml2_6.0.0\resources\uml2content\
This file is responsible for a majority of element transformation details because most model elements have similar internal structures. Once you've opened this file, search for OwnedAttribute, for which you should find six entries. These areas of the XSL file represent transformation code that is related to attribute elements.
Note: The XSL calls a UML attribute an OwnedAttribute because the intermediate XML (Extensible Markup Language) file nodes for attributes are called 'OwnedAttribute'. Here is a snippet of the intermediate XML that your XSL will process for the attribute:
...
< ownedAttribute name="A1" publish:icon="593409.jpeg"
publish:qualifiedname="ClassModel::Package1::C1::A1"
...
< /< ownedAttribute >
... |
In this case you are interested in the details of the attribute, so go ahead and search for the following comment:
< !-- Attribute Details Table -- >
Now look under the < !-- Attribute Details Table -- > for the following lines:
< a name="attribute{@xmi:id}" >
< xsl:value-of select="@name"/ >
< /a >
Change this to:
< a name="attribute{@xmi:id}" >
< xsl:value-of select="@publish:qualifiedname"/ >
< /a >
This will get us the FQN attribute of the OwnedAttribute tag.
Note: In order to effectively tweak the XSL you need to understand what it will be processing. To do so, you can look at the intermediate form. Navigate to where you published your model and look under the content directory, where you will find a series of HTML and XML files. The XML files represent the model that is processed by the XSL. You can inspect the XML using an XML editor to find information about what will be processed. In this example, searching for the intermediate data for the attribute showed how the fully qualified name is recorded. The tag attribute publish:qualifiedname contains this information. For more information, see the A deeper look at the details of model publishing section following.
After that, look below this code just a few lines further to locate the section of XSL code that will generate the attribute signature. To change the font of the attribute signature, edit the following lines:
< pre >
< xsl:value-of select="publish:properties/publish:property[@name='Visibility']/@publish:value"/ >
< xsl:text > < /xsl:text >
< xsl:apply-templates select="./publish:properties/publish:property[@name='Type']"/ >
< xsl:value-of select="@name"/ >
< /pre > |
In particular, you're interested in the HTML tag. Since the goal is to add a font and a color, this seems like a good place to use CSS information. Again, you want to edit the Css.xsl file. This file is found in the root of our resources folder. Edit the Css.xsl file and add:
.AttributeSig
{
font-weight:500;
font-size:larger;
color:#0099FF;
} |
Now, save the Css.xsl file.
Next go back to the NamedElementContent.xsl file and edit the < pre > HTML tag, changing it to:
< pre class="AttributeSig" > |
This will pull in our style information, so that when HTML is generated the signature will appear in blue.
Finally, let's change the color of the table. To do this, look for the following comment in the code a few lines below where you've been editing.
< !-- Output the properties table -- >
< xsl:apply-templates select="publish:properties" >
< xsl:with-param name="indentCount" select="1"/ >
< xsl:with-param name="includeTitle" select="false()"/ >
< /xsl:apply-templates > |
Note: there are 2 comments in the file called < !-- Output the properties table -- > and the one you want is just a few lines lower than our last edit location.
The code makes a call out to a template and the template is matched by the signature of the call. In this case the template can be found in the UML2Utility.xsl file found in the resources\utility directory. In UML2Utility.xsl look for the following:
< xsl:template name="outputPropertyTable" match="publish:properties" > |
Once you have found the template, look in the body for this information:
< table class="PropertiesTable" cellpadding="4" cellspacing="0" border="1" > |
In this instance you need to add another attribute to the tag, so change this line to read:
< table class="PropertiesTable" cellpadding="4" cellspacing="0" border="1" BORDERCOLOR="#0099FF" > |
Note that if you wanted to change the color of the text in the table you could easily edit the PropertiesTable CSS entry.
The net result of your work looks like Figure 7, following.
| |
Figure 7: Customized output
|
A deeper look at the details of model publishing
The rest of this article covers details of structure and design, and offers more insight into working with the model publishing XSL. It is meant as a further resource for customizing and working with your XSL framework.
How the model is published in a nutshell
Publishing a model is done in several steps, which we'll discuss briefly.
To publish a model you need to do the following:
- Create your model
- Select the model element
- Click Modeling > Publish on the menu
At this point the model is published, and the program builds a Document Object Model (DOM) and writes it out to an intermediate XML file (data). This Intermediate XML data is then consumed by the XSL templates, which in turn generate the HTML version of the model that is shown in a browser. Figure 8 illustrates this process.
| |
Figure 8: From model to HTML pages
|
Note that intermediate XML files are created for every package in the model. The root xml file is named using this convention:
__u0xoBbwEdmVsY8gwr-g8A_root.xml
The first series of characters are generated like a Globally Unique Identifier (GUID) to guarantee that the file has a unique name.
Visual layout elements
This section briefly describes how the visual elements relate to the physical file system layout. This will help you understand both the physical XSL file layout, and how things work in concert to build a published model.
Let's start with what your model looks like (shown in Figure 9).
| |
Figure 9: The structure of your model
|
Figure 10 illustrates the HTML start page that results if this model is published.
| |
Figure 10: The HTML start page
|
When you click the model link, in this case jdk17rev, the window displays the details of the model. The details comprise a frameset (shown in Figure 11, following) consisting of three primary frames:
- Package Navigation
- All Elements
- Element Context
| |
Figure 11: Model details
|
The Element Context frame consists of a single HTML page (see Figure 12) that contains:
- A navigation bar
- The details of the element we are looking at
- Potentially, bookmarks for the elements containing children such as a class's attributes and operations
| |
Figure 12: Element context
|
Physical file system layout
The XSL files are located under the install directory of our product; on Linux (and similarly on Microsoft® Windows® operating system) they can be found under the following plug-in directory:
[Product Install Directory]/rsm/eclipse/plugins/com.ibm.xtools.publish.uml2_6.0.0
As discussed previously, com.ibm.xtools.publish.uml2_6.0.0 may be in a different location depending on your installation.
Once you have located the plug-in, you will want to navigate to the resources directory:
../com.ibm.xtools.publish.uml2_6.0.0/resources
From here you will see a structure that looks like that in Figure 13:
| |
Figure 13: The physical file system layout
|
Table 2 describes at a very high level what each of the folders do, or contain. Tables 3 through 7, following, look at these folders in more detail.
Overview of Folder and Files layout
| Folder Name | Description | | . (the current directory, for instance /resources/) | Contains top-level XSL files that do the following: Build the html file structure, describe HTML element style layout, define global variables, and contain the top-level XSL entry point | | l10n | String tables for a given language | | Reports | Report templates for generating reports | | Uml2content | Model element type-specific XSL | | Utility | Utility file for commonly used XSL transformations |
| |
Table 2: Folder layout overview
|
| Resources Folder | Top-level folder contains other folders | | WebPublish.xsl | Entry point where the XSL is applied to the model. It includes most other files (via the import or include XSL commands); look at the template '/' as a starting point to the transformation. | | Css.xsl | Contains style sheet information used by the XSL-generated HTML elements | | FileNameGeneration.xsl | Used to generate path-relative filenames, so that HTML link elements know where to find the physical file to load | | GenerateAllElementsList.xsl | Builds the lower left frame of the frameset and is a list of elements in the model | | GenerateFrameSet.xsl | Top-level html file that sets up the HTML frameset | | GeneratePackageElementsList.xsl | Responsible for generating element information found within a package | | GeneratePackageList.xsl | Generates the package list HTML file for the top left navigation window, and the overview summary content page for the top-level model or package | | GlobalVariables.xsl | Contains global variables used by most XSL templates | | NavigationBar.xsl | Contains templates that build the top frame, which contains navigation information based on element selection context |
| |
Table 3: Resources file details
|
| l10n Folder | The l10n directory contains language-specific string tables that are used in generating the HTML | | Localize.xsl | Contains templates that are able to fetch localized strings from the messages.xml file | | messages.xml | Localized string(s) file |
| |
Table 4: l10n file details
|
| Reports Folder | This folder contains the report-specific implementation and shows off two sample reports, MetricsReport.xsl and ModelDiagramReport.xsl. | | MetricsReport.xsl | Sample Metrics report | | ModelDiagramReport.xsl | Sample Diagram report | | ReportUtility.xsl | Report utility routines | | Userconfig.xml | Used if you are embedding custom fonts in a PDF document (see the The details of embedding a font section for details) | | Reports.manifest | Where you register your new custom report |
| |
Table 5: Reports file details
|
| uml2content Folder | This folder contains a collection of XSL template files used in processing various types of UML Model elements. The naming convention loosely follows the names of UML elements. The most noteworthy of the files in this section are listed below. | | NamedElementContent.xsl | Called by most templates to actually do the work of generating elements details. (This is like a base class template, most templates ultimately call this.) It is the largest and most complex template. | | NestedClassifierContent.xsl | Works directly with nested classifiers | | OwnedMemberContext.xsl | The intermediate form has a notion of Owned members, and when these nodes are processed this file would be invoked. | | DiagramContent.xsl | Generates diagram content |
| |
Table 6: uml2content file details
|
| Utility Folder | Contains several utility files that include well-known or often-used templates | | HTMLUtility.xsl | Contains routines for formatting and generating HTML elements such as tables, links, and anchors | | StringUtility.xsl | Contains routines for manipulating strings (for example, substring substitution) | | UML2Utility.xsl | Contains routines for manipulating the model's intermediate XML, so that you can access various UML element information such as method parameters, return values, and element properties |
| |
Table 7: Utility file details
|
Debugging model publish XSL, tips and resources
This section was written primarily to help you find the files and tools needed to debug model publish XSL. It is not a tutorial on setting up and debugging.
For most simple changes you can probably get away with editing the XSL using a text editor, but for bigger work you probably will want to use an XSL debugger.
To debug XSL, you can do one of the following:
- Add output statements to your XSL (XSL message, or similar built-in XSL routines)
- Use an editor/debugger
Both of these have their place, but if you decide you need a full-blown editor or debugger there are several on the market with varying degrees of features, functionality and cost range. A few we know of are:
Editors / Debuggers
http://www.oxygenxml.com
http://www.xmlspy.com
http://xmlbuddy.com
Note: that we leave it up to you to decide if any of these are worth using
To debug the XSL you will need several things:
- The intermediate XML that was generated when the model was published
- The XSL transformation files
- A debugger
The intermediate XML files are created for every package in the model. The root XML filename has the following pattern to it, identified by _root.xml as the last part:
__u0xoBbwEdmVsY8gwr-g8A_root.xml
The XSL we've discussed previously, and you of course know how to use a debugger.
Resources
Acknowledgements
The following additional people are mentioned for their comments and contributions to the creation of this document: Gary Clarke, Satish Doshi, Boris Dubauski, Rajeev Sikka, and Hiep Tieu.
About the authors  | |  | Mike Boyersmith is an Advisory Software Engineer for the IBM Rational Modeling products. He has been involved in many software engineering projects in his computer science career including, modeling languages, UML, anti-virus technology, security technologies, system utilities, development and system tooling software. His current passions includes spending as much time as he can with his new son, family, and finding time to develop his skills as a writer and artist. Mike also enjoys exploring computer science areas of interest. |
 | |  | Cheng-Yee Lin is a development manager for the IBM Rational modeling products. He has been involved in several projects related to compilers, UML, and API-based integrations. Mr. Lin holds M.S. and M.Ph. degrees in computer science from Yale University. |
Rate this page
|