- 1 Overview
- 2 Configuration
- 3 HTML
- 4 DOCX / Office Open XML WordprocessingML
- 5 Inclusion of UML Diagrams
ISO 19110:2005 specifies a methodology for classifying and organizing feature types into a feature catalogue. ShapeChange contains a target for generating an ISO 19110-compliant feature catalogue from an application schema (or one of its contained packages).
The Feature Catalogue target can produce a feature catalogue in the following formats:
- HTML (single or multi page)
The output is handled “under the hood” by XSLT stylesheets and transformations.
The <Target> element definition for the Feature Catalogue target is a standard ShapeChange target. An example from the generation of a feature catalogue for INSPIRE application schemas is given below.
<Target class="de.interactive_instruments.ShapeChange.Target.FeatureCatalogue.FeatureCatalogue" mode="enabled"> <targetParameter name="outputDirectory" value="result/fc"/> <targetParameter name="outputFilename" value="FC_INSPIRE"/> <targetParameter name="package" value=""/> <targetParameter name="inheritedProperties" value="false"/> <targetParameter name="changeInfo" value="false"/> <targetParameter name="outputFormat" value="HTML"/> <targetParameter name="name" value="'INSPIRE application schemas'"/> <targetParameter name="scope" value="This feature catalogue gives an informative overview of the spatial object types and data types defined in the INSPIRE data specifications. These types are used by data providers for the exchange and classification of spatial objects from data sets that relate to one or several INSPIRE spatial data themes.[NEWLINE]For the normative requirements, please refer to the <a href='http://eur-lex.europa.eu/LexUriServ/LexUriServ.do?uri=OJ:L:2010:323:0011:0102:EN:PDF'>COMMISSION REGULATION (EU) No 1089/2010 of 23 November 2010 on the interoperability of spatial data sets and services</a>. For a more detailed description of the application schemas, see the data specification guidance documents at <a href='http://inspire.jrc.ec.europa.eu/index.cfm/pageid/2'>http://inspire.jrc.ec.europa.eu/index.cfm/pageid/2</a>.[NEWLINE]All application schemas for spatial data themes of Annex II or III are draft schemas."/> <targetParameter name="versionNumber" value="n/a (each application schema is versioned separately)"/> <targetParameter name="versionDate" value="March 2012"/> <targetParameter name="producer" value="European Commission, INSPIRE Drafting Team 'Data Specifications' and Thematic Working Groups"/> <targetParameter name="xsltPath" value="https://shapechange.net/resources/xslt"/> <targetParameter name="xslhtmlFile" value="html.xsl"/> <targetParameter name="featureTerm" value="Spatial Object"/> </Target>
The class for the Target implementation is de.interactive_instruments.ShapeChange.Target.FeatureCatalogue.FeatureCatalogue.
The <targetParameter>s recognized for the Feature Catalogue target include the following:
|Parameter Name||Default Value||Explanation|
|changeInfo||false||A Boolean; if “true”, information on an element’s last change (stored in the “lastChange” tagged value) will be added to that element in the catalogue output.|
|cssPath||(same as the directory referenced by the xsltPath parameter)||The path (without a trailing “/”) where the stylesheet.css template for the creation of a frame-based HTML feature catalogue is located.|
|docxTemplateFilePath||https://shapechange.net/resources/templates/template.docx||Path to to the template for the conversion to docx.|
|featureTerm||Feature||A string indicating the term to be used for a Feature (a different term can be substituted if necessary).Usually this parameter will not be needed, it has been added to support INSPIRE, which does not use the term “feature” and uses “spatial object” instead.|
|true||A boolean which indicates if the URI of code lists (available via tagged value ‘codeList’ or ‘vocabulary’) shall be encoded as hyperlink on the name of a code list type in the feature catalogue.
Set to ‘false’ to disable this behavior (can be useful for example when the overall linking to external code lists is not ready for publication yet).
|includeDiagrams||false||A boolean which indicates if diagrams shall be included to document model elements. more|
|includeVoidable||true||A boolean which indicates if information whether or not a property is voidable shall be included in the documentation of the property.|
|inheritedProperties||false||A Boolean; if “true”, all of a type’s inherited properties will be output.|
|javaOptions||<none>||Can be used to set options – especially ‘Xmx’ – for the invocation of the java executable identified via the parameter “pathToJavaExecutable”.NOTE: when processing documents of 100Mbytes or more, it is recommended to allocate – via the Xmx parameter – at least 5 times the size of the source document.Example: “-Xmx6000m”|
|name||unknown||The name to be used for this feature catalogue.|
|noAlphabeticSortingForProperties||false||By default, properties of a class are listed alphabetically in the feature catalogue. If this parameter is set to ‘true’, the properties are listed as defined by their ‘sequenceNumber’ tagged values.NOTE: this parameter is ignored if a diff is performed.|
|outputDirectory||<the current run directory>||The path to which the Feature Catalogue (XML) files will be written.|
|outputFilename||FeatureCatalogue||The name of the output file without extension. The appropriate extension will be added depending on the output format.|
|outputFormat||Required||(Required) A string representing the desired output formats. The possible values are:
Case is unimportant.
Multiple values may be provided separated with commas.
|package||<the entire application schema>||A string value indicating the name of the UML package in the application schema which is to be output as a Feature Catalogue.The default is the entire application schema; this parameter should not be specified or be left blank, if this is desired.|
|pathToJavaExecutable||<none>||Path to a java executable (usually 64bit). This parameter should be used whenever the feature catalogue to produce will be very large (hundreds of megabytes to gigabytes). Set the options for execution – especially ‘Xmx’ – via the parameter “javaOptions”.Example: “C:/Program Files/Java/jdk1.8.0_45/bin/java.exe”|
|producer||unknown||The producer name. Note: The producer is a mandatory property of a feature catalogue according to ISO 19110.|
|referenceModelFileNameOrConnectionString||<none>||Provide information for accessing the reference model for performing an application schema diff:
|referenceModelType||<none>||A string describing the format of the application schema to be transformed. The current options are:
|scope||unknown||Information on the scope of this feature catalogue. This may contain HTML markup and “[NEWLINE]” to separate paragraphs.|
|versionDate||unknown||The version date for this feature catalogue.|
|versionNumber||unknown||The version number for this feature catalogue.|
|xsldocxFile||docx.xsl||Name of the XSLT script for converting to DOCX.|
|xslframeHtmlFileName||frameHtml.xsl||Name of the XSLT script for converting to frame-based HTML.|
|xslhtmlFile||html.xsl||Name of the XSLT script for converting to HTML.|
|xsltPath(also: xsltPfad)||https://shapechange.net/resources/xslt||The path (without a trailing “/”) where the required XSLT files are located.|
|xslTransformerFactory||org.apache.xalan.processor.TransformerFactoryImpl||Identifies the XSLT processor implementation.The default is used for XSLT 1.0 transformations.In order to process XSLT 2.0 transformations (which some of the XSLTs require), this parameter must point to the implementation of an XSLT processor that is capable of XSLT 2.0.The recommended XSLT 2.0 processor is Saxon-HE (home edition; open source):
Documentation of tagged values
A feature catalogue can include tagged values of model elements. By default, tagged values are not included. However, by setting the input parameter representTaggedValues, the user can define the tagged values that shall be included when a feature catalogue is generated.
ShapeChange can create feature catalogue output in different languages.
The localization functionality introduces the following additional target parameters:
|Parameter Name||Default Value||Explanation|
|lang||en||Identifier of the language to be used by the feature catalogue.Currently supported by ShapeChange:
Additional languages can be added in customized localizationMessages.xml files (see Adding Additional Languages).
|localizationMessagesUri||If this parameter is not set in the configuration, ShapeChange assumes that the localizationMessages.xml file is contained in the same directory as the XSLT file used to create the feature catalogue (which is determined by the xsltPath target parameter).||URI pointing to the localizationMessages.xml file, which contains a list of all messages required when creating the feature catalogue, in different languages. This file can be customized to support additional languages. Examples:
Unless a customized message file shall be used for the creation of the feature catalogue this parameter does not need to be set.
|xslLocalizationUri||If this parameter is not set in the configuration, ShapeChange assumes that the localization.xsl file is contained in the same directory as the XSLT file used to create the feature catalogue (which is determined by the xsltPath target parameter).||URI to the localization.xsl file.Unless a custom directory was chosen for the XSLT that creates the feature catalogue in a specific format (e.g. html or docx) this parameter does not need to be set.|
Adding Additional Languages
In order to add another language, create a local copy of the localizationMessages.xml (available here) and simply add a translation for each message, like this:
<message id="fc.Abstract"> <text lang="en">Abstract</text> <text lang="de">Abstrakt</text> <text lang="fr">Abstrait</text> </message>
The value of the lang Attribute is the value to be used in the lang target parameter.In order to configure French as the language, you would need to follow these steps:
- Complete the translation of all messages in the localizationMessages.xml.
- Add the targetParameter localizationMessagesUri to your configuration, pointing to the modified localizationMessages.xml.
- Set the targetParameter lang to “fr”.
There are two types of HTML output that ShapeChange can create: a single HTML page and frame-based HTML.
Single HTML Page
In order to create a feature catalogue on a single HTML page, use ‘HTML’ as value of the outputFormat parameter.
Application Schema Diff
If the outputFormat is ‘HTML’ and the configuration of this target contains valid values for the parameters referenceModelType and referenceModelFileNameOrConnectionString then ShapeChange will perform a diff between the application schemas from the input model and the reference model.
More details can be found here.
A frame-based HTML feature catalogue is much like an API documentation for Java classes. It uses HTML iframes to provide a navigation bar (for application schema and their contents) and a view to show details about a selected schema, package, or class.
In order to create a frame-based HTML feature catalogue:
- Use ‘FRAMEHTML’ as value of the outputFormat parameter.
- Use an XSLT 2.0 processor implementation (configured via the xslTransformerFactory target parameter).
Cascading Style Sheets (CSS)
CSS can be used to modify the appearance of an HTML feature catalogue.
DOCX / Office Open XML WordprocessingML
ShapeChange can create a feature catalogue in a copy of an existing template .docx file (more precisely, the file is formatted according to ISO/IEC 29500 (2012) – Office Open XML WordprocessingML). The template file can be a local or remote file. Its path is provided to ShapeChange via the docxTemplateFilePath targetParameter. The default template is located at https://shapechange.net/resources/templates/template.docx
In order to create a feature catalogue in docx format:
- Use ‘DOCX’ as value of the outputFormat parameter.
- Use an XSLT 2.0 processor implementation (configured via the xslTransformerFactory target parameter).
ShapeChange ensures that images are scaled to fit the page width. At the moment the max width of an image is set to 18cm. This assumes a DIN A4 page layout. This setting can be adjusted via the parameter maxWidthCm (in docx.xsl; the location to a custom docx.xsl can be set via the target parameters xsltPath and xsldocxFile).
A specific placeholder text must be present in the template file. ShapeChange looks for this text and replaces it with the content of the feature catalogue. The placeholder that ShapeChange looks for is the word: ShapeChangeFeatureCatalogue
NOTE: sometimes (e.g. when writing half of the text, then saving, then writing the other half) word stores text in multiple pieces. If this happens with the placeholder then ShapeChange cannot create the docx feature catalogue.
To prevent this issue, either write the placeholder as a single word without intermediate saving, or copy-paste the placeholder into the template document.
ShapeChange requires the first three levels of headings to be set in the template. If the template doesn’t already contain such headings, simply create a heading in the template for each required level and save the document. Once the feature catalogue has been created, these headings can be removed in the resulting docx file.
Table of contents and page numbers
ShapeChange does not create page numbers or a table of contents (TOC) when writing a feature catalogue in docx format.
If the template itself already has page numbering and/or a TOC, then using this template results in a file that Word declares as being invalid. An according warning is issued when attempting to open the file. Word can repair that file, but we think that in this case it is better to avoid Word’s auto-repair facility.
We suggest the following procedure: use a template without page numbering and a TOC to generate the feature catalogue. Open the resulting file and copy the complete feature catalogue into another word document that has page numbering and/or a TOC. Then make sure to update the whole document (press Ctrl+A, then F9).
Requirements for including UML diagrams
The following requirements apply to the template if it shall be used to create a feature catalogue with UML diagrams.
Diagrams are saved as .jpg images. In order for the correct content type to be available, the template should contain a an image whose format is .jpg. If the template doesn’t already contain such an image, simply insert one and save the template document. Once the feature catalogue has been created, the image can be removed in the resulting docx file.
ShapeChange requires the caption style to be set in the template. If the template doesn’t already contain such a caption, simply create one (e.g. for the required image – see above) and save the document. Once the feature catalogue has been created, this caption can be removed in the resulting docx file.
Inclusion of UML Diagrams
NOTE: currently this feature is available for EA input models and feature catalogues in the following formats:
- frame HTML (since 2.2.0)
Per default, a feature catalogue documents an application schema with relevant information about packages, feature types, properties etc. ShapeChange also supports the inclusion of diagrams to document schema elements.
In order for diagrams stored in the input file to be available to the feature catalogue target, the appropriate input parameters need to be set (see here for further details) and the targetParameter includeDiagrams must be set to ‘true’ for the feature catalogue target.
- Package and logical/class diagrams are currently supported.
- By default the diagrams are sorted by their name. This can be disabled via the input parameter ‘sortDiagramsByName’.
- Diagrams outside of selected application schema packages are ignored.
- The setting under Tools > Options > Diagram -> “Scale Saved Bitmaps to” in the EA input file controls the size and resolution of the diagrams):
- 400% results in big images (causing a large document) with good resolution
- 200% is ok
- 100% results in small images with rather poor resolution
- For DOCX feature catalogues, you can update the numbering of the figures in the resulting document by first pressing Ctrl+A (to select everything) and then F9 (to update everything).