Configuring XML Catalogs

You can add catalog files to your Document Type Association using the Catalogs tab from the Document Type dialog.

[Important]Important

<oXygen/> XML Editor collects all the catalog files listed in the installed frameworks. No matter what the Document Type Association matches the edited file, all the catalog mappings are considered when resolving external references.

[Important]Important

The catalog files settings are available for all editing modes, not only for the Author mode.

In the XML sample file for SDF we did not used a xsi:schemaLocation attribute, but instead we let the editor use the schema from the association. However there are cases in which we must refer for instance the location of a schema file from a remote web location. In such cases the catalog may be used to map the web location to a local file system entry.

In the following section we will present an use-case for the XML catalogs, by modifying our sdf.xsd XML Schema file from the Example Files Listings.

The sdf.xml file refers the other file abs.xsd through an import element:

<xs:import namespace=
 "http://www.oxygenxml.com/sample/documentation/abstracts" 
 schemaLocation="abs.xsd"/>

The schemaLocation attribute references the abs.xsd file located in the same directory. What if the file was on the web, at the http://www.oxygenxml.com/SDF/abs.xsd location for instance? In this case the attribute value will be:

<xs:import namespace=
 "http://www.oxygenxml.com/sample/documentation/abstracts" 
 schemaLocation="http://www.oxygenxml.com/SDF/abs.xsd"/>

There is a problem with this approach. What happens if an Internet connection is not available? How will we check our document for errors if a part of the schema is not available? The answer is to create a catalog file that will help the parser locate the missing piece containing the mapping:

http://www.oxygenxml.com/SDF/abs.xsd -> ../local_path/abs.xsd

To do this create a new XML file called catalog.xml and save it into the {oXygen_installation_directory}/frameworks/sdf directory. The content of the file should be:

<?xml version="1.0"?>
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
    <system 
      systemId="http://www.oxygenxml.com/SDF/abs.xsd" 
      uri="schema/abs.xsd"/>
</catalog>

This means that all the references to http://www.oxygenxml.com/SDF/abs.xsd must be resolved to the abs.xsd file located in the schema directory.

[Note]Note

The references in the XML catalog files are relative to the directory that contains the catalog.

Save the catalog file and modify the sdf.xsd file by changing its import element, then add the catalog to the Document Type association. You can do this in the Catalogs tab by pressing the New button. Enter ${frameworks}/sdf/catalog.xml in the displayed dialog.

 

Figure 7.28. Adding Catalogs to the Document Type Association

Adding Catalogs to the Document Type Association

To test the catalog settings, restart <oXygen/> and try to validate a new sample Simple Documentation Framework document. There should be no errors.