Catalog Files

www.altova.com Print this Topic Previous Page Up One Level Next page

Home >  Customizing MapForce >

Catalog Files

MapForce supports a subset of the OASIS XML catalogs mechanism. The catalog mechanism enables MapForce to retrieve commonly used schemas (as well as stylesheets and other files) from local user folders. This increases the overall processing speed, enables users to work offline (that is, not connected to a network), and improves the portability of documents (because URIs would then need to be changed only in the catalog files.)

 

The catalog mechanism in MapForce works as outlined below.

 

RootCatalog.xml

When MapForce starts, it loads a file called RootCatalog.xml (structure shown in listing below), which contains a list of catalog files that will be looked up. You can modify this file and enter as many catalog files to look up as you like, each in a nextCatalog element. Each of these catalog files is looked up and the URIs in them are resolved according to the mappings specified in them.

 

<?xml version="1.0" encoding="UTF-8"?>
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"
    xmlns:spy="http://www.altova.com/catalog_ext"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="urn:oasis:names:tc:entity:xmlns:xml:catalog Catalog.xsd">
<nextCatalog catalog="%PersonalFolder%/Altova/%AppAndVersionName%/CustomCatalog.xml"/>
<nextCatalog catalog="CoreCatalog.xml"/>
<!-- Include all catalogs under common schemas folder on the first directory level -->
<nextCatalog spy:recurseFrom="%AltovaCommonFolder%/Schemas" catalog="catalog.xml" spy:depth="1"/>
<!-- Include all catalogs under common XBRL folder on the first directory level -->
<nextCatalog spy:recurseFrom="%AltovaCommonFolder%/XBRL" catalog="catalog.xml" spy:depth="1"/>
</catalog>

 

In the listing above, notice that in the Schemas and XBRL folders of the folder identified by the variable %AltovaCommonFolder% are catalog files named catalog.xml. (The value of the %AltovaCommonFolder% variable is given in the table below.)

 

The catalog files in the Altova Common Folder map the pre-defined public and system identifiers of commonly used schemas (such as SVG and WSDL) and XBRL taxonomies to URIs that point to locally saved copies of the respective schemas. These schemas are installed in the Altova Common Folder when MapForce is installed.You should take care not to duplicate mappings in these files, as this could lead to errors.

 

CoreCatalog.xml, CustomCatalog.xml, and Catalog.xml

In the RootCatalog.xml listing above, notice that CoreCatalog.xml and CustomCatalog.xml are listed for lookup:

 

CoreCatalog.xml contains certain Altova-specific mappings for locating schemas in the Altova Common Folder.
CustomCatalog.xml is a skeleton file in which you can create your own mappings. You can add mappings to CustomCatalog.xml for any schema you require but that is not addressed by the catalog files in the Altova Common Folder. Do this using the supported elements of the OASIS catalog mechanism (see below).
There are a number of Catalog.xml files in the Altova Common Folder. Each is inside the folder of a specific schema or XBRL taxonomy in the Altova Common Folder, and each maps public and/or system identifiers to URIs that point to locally saved copies of the respective schemas.

 

Location of catalog files and schemas

The files RootCatalog.xml and CoreCatalog.xml are installed in the MapForce application folder. The file CustomCatalog.xml is located in your MyDocuments/Altova/MapForce folder. The catalog.xml files are each in a specific schema folder, these schema folders being inside the folders: %AltovaCommonFolder%\Schemas and %AltovaCommonFolder%\XBRL.

 

Shell environment variables and Altova variables

Shell environment variables can be used in the nextCatalog element to specify the path to various system locations (see RootCatalog.xml listing above). The following shell environment variables are supported:

 

%AltovaCommonFolder%

C:\Program Files\Altova\Common2019

%DesktopFolder%

Full path to the Desktop folder for the current user.

%ProgramMenuFolder%

Full path to the Program Menu folder for the current user.

%StartMenuFolder%

Full path to Start Menu folder for the current user.

%StartUpFolder%

Full path to Start Up folder for the current user.

%TemplateFolder%

Full path to the Template folder for the current user.

%AdminToolsFolder%

Full path to the file system directory that stores administrative tools for the current user.

%AppDataFolder%

Full path to the Application Data folder for the current user.

%CommonAppDataFolder%

Full path to the file directory containing application data for all users.

%FavoritesFolder%

Full path of the Favorites folder for the current user.

%PersonalFolder%

Full path to the Personal folder for the current user.

%SendToFolder%

Full path to the SendTo folder for the current user.

%FontsFolder%

Full path to the System Fonts folder.

%ProgramFilesFolder%

Full path to the Program Files folder for the current user.

%CommonFilesFolder%

Full path to the Common Files folder for the current user.

%WindowsFolder%

Full path to the Windows folder for the current user.

%SystemFolder%

Full path to the System folder for the current user.

%CommonAppDataFolder%

Full path to the file directory containing application data for all users.

%LocalAppDataFolder%

Full path to the file system directory that serves as the data repository for local (nonroaming) applications.

%MyPicturesFolder%

Full path to the MyPictures folder.

 

How catalogs work

Catalogs are commonly used to redirect a call to a DTD to a local URI. This is achieved by mapping, in the catalog file, public or system identifiers to the required local URI. So when the DOCTYPE declaration in an XML file is read, the public or system identifier locates the required local resource via the catalog file mapping.

 

For popular schemas, the PUBLIC identifier is usually pre-defined, thus requiring only that the URI in the catalog file point to the correct local copy. When the XML document is parsed, the PUBLIC identifier in it is read. If this identifier is found in a catalog file, the corresponding URL in the catalog file will be looked up and the schema will be read from this location. So, for example, if the following SVG file is opened in MapForce:

 

<?xml version="1.0" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
"http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
 
<svg width="20" height="20" xml:space="preserve">
<g style="fill:red; stroke:#000000">
    <rect x="0" y="0" width="15" height="15"/>
    <rect x="5" y="5" width="15" height="15"/>
</g>
</svg>

 

This document is read and the catalog is searched for the PUBLIC identifier. Let's say the catalog file contains the following entry:

 

<catalog>
 ...
  <public publicId="-//W3C//DTD SVG 1.1//EN" uri="schemas/svg/svg11.dtd"/>
 ...
</catalog>

 

In this case, there is a match for the PUBLIC identifier, so the lookup for the SVG DTD is redirected to the URI schemas/svg/svg11.dtd (this path is relative to the catalog file), and this local file will be used as the DTD. If there is no mapping for the Public ID in the catalog, then the URL in the XML document will be used (in the example above: http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd).

 

The catalog subset supported by MapForce

When creating entries in CustomCatalog.xml (or any other catalog file that is to be read by MapForce), use only the following elements of the OASIS catalog specification. Each of the elements below is listed with an explanation of their attribute values. For a more detailed explanation, see the XML Catalogs specification. Note that each element can take the xml:base attribute, which is used to specify the base URI of that element.

 

<public publicId="PublicID of Resource" uri="URL of local file"/>
<system systemId="SystemID of Resource" uri="URL of local file"/>
<uri name="filename" uri="URL of file identified by filename"/>
<rewriteURI uriStartString="StartString of URI to rewrite" rewritePrefix="String to replace StartString"/>
<rewriteSystem systemIdStartString="StartString of SystemID" rewritePrefix="Replacement string to locate resource locally"/>

 

In cases where there is no public identifier, as with most stylesheets, the system identifier can be directly mapped to a URL via the system element. Also, a URI can be mapped to another URI using the uri element. The rewriteURI and rewritsSystem elements enable the rewriting of the starting part of a URI or system identifier, respectively. This allows the start of a filepath to be replaced and consequently enables the targeting of another directory. For more information on these elements, see the XML Catalogs specification.

 

File extensions and intelligent editing according to a schema

Via catalog files you can also specify that documents with a particular file extension should have MapForce's intelligent editing features applied in conformance with the rules in a schema you specify. For example, if you create a custom file extension .myhtml for (HTML) files that are to be valid according to the HTML DTD, then you can enable intelligent editing for files with these extensions by adding the following element of text to CustomCatalog.xml as a child of the <catalog> element.

 

<spy:fileExtHelper ext="myhtml" uri="schemas/xhtml/xhtml1-transitional.dtd"/>

 

This would enable intelligent editing (auto-completion, entry helpers, etc) of .myhtml files in MapForce according to the XHTML 1.0 Transitional DTD. Refer to the catalog.xml file in the %AltovaCommonFolder%\Schemas\xhtml folder, which contains similar entries.

 

XML Schema and catalogs

XML Schema information is built into MapForce and the validity of XML Schema documents is checked against this internal information. In an XML Schema document, therefore, no references should be made to any schema for XML Schema.

 

The catalog.xml file in the %AltovaCommonFolder%\Schemas\schema folder contains references to DTDs that implement older XML Schema specifications. You should not validate your XML Schema documents against either of these schemas. The referenced files are included solely to provide MapForce with entry helper info for editing purposes should you wish to create documents according to these older recommendations.

 

More information

For more information on catalogs, see the XML Catalogs specification.


© 2019 Altova GmbH