Import Content Dynamically

Along with the built-in support for various useful URL protocols (such as HTTPS or SFTP), Oxygen XML Author Eclipse plugin also provides special support for a convert protocol that can be used to chain predefined processors to dynamically import content from various sources.

Important: Starting with version 26, the dynamic conversion protocol is disabled by default. To enable it, you must set the com.oxygenxml.enable.convert.url.protocol system property to the value of true.

A dynamic conversion URL chains various processors that can be applied, in sequence, on a target resource and has the following general syntax:

convert:/processor=xslt;ss=urn:processors:excel2d.xsl/processor=excel!/urn:files:my.xls

The previous example first applies a processor (excel) on a target identified by the identifier (urn:files:sample.xls) and converts the Excel™ resource to XML. The second applied processor (xslt) applies an XSLT stylesheet identified using the identifier (urn:processors:excel2d.xsl) over the resulting content from the first applied processor. These identifiers are all mapped to real resources on disk via an XML catalog that is configured in the application, as in the following example:

<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
  <rewriteURI uriStartString="urn:files:" rewritePrefix="./resources/"/>
  <rewriteURI uriStartString="urn:processors:" rewritePrefix="./processors/"/>
</catalog>

The target resource part of the conversion URL must always follow the !/ pattern. It can be any of the following:

An absolute URL that points to a resource.
An identifier that will be resolved to an actual resource via the XML Catalog support in the application. In the example above, the urn:files:sample.xls target resource is resolved via the XML catalog.
A relative location. This location can only be resolved to an actual resource URL when the application has enough information about the location where the URL is referenced.
For example, for a DITA map with a <topicref> such as:
```
<topicref href="convert:/.../processor=excel!/resources/sample.xls"/>
```
the resources/sample.xls path will be resolved relative to the DITA map location.

This type of URL can be opened in the application by using the Open URL action from the File menu. It can also be referenced from existing XML resources via xi:include or as a topic reference from a DITA map.

A GitHub project that contains various dynamic conversion samples for producing DITA content from various sources (and then publishing it) can be found here: https://github.com/oxygenxml/dita-glass.

Conversion Processors

A set of predefined conversion processors is provided in Oxygen XML Author Eclipse plugin. Each processor has its own parameters that can be set to control the behavior of the conversion process. All parameters that are resolved to resources are passed through the XML catalog mapping.

The following predefined conversion processors are included:

xslt Processor - Converts an XML input using the Saxon EE XSLT processor. The ss parameter indicates the stylesheet resource to be loaded. All other specified parameters will be set as parameters to the XSLT transformation.
```
convert:/processor=xslt;ss=urn:processors:convert.xsl;p1=v1!/urn:files:sample.xml
```
xquery Processor - Converts an XML input using the Saxon EE XQuery processor. The ss parameter indicates the XQuery script to be loaded. All other specified parameters will be set as parameters to the XSLT transformation.
```
convert:/processor=xquery;ss=urn:processors:convert.xquery;p1=v1!/urn:files:sample.xml
```
excel Processor - Converts an Excel™ input to an XML format that can later be converted by other piped processors. It has a single parameter sn, which indicates the name of the sheet that needs to be converted. If this parameter is missing, the XML will contain the combined content of all sheets included in the Excel™ document.
```
convert:/processor=excel;sn=test!/urn:files:sample.xls
```
java Processor - Converts an input to another format by applying a specific Java method. The jars parameter is a comma-separated list of JAR libraries, or folders that libraries will be loaded from. The ccn parameter is the fully qualified name of the conversion class that will be instantiated. The conversion class needs to have a method with the following signature:
```
  public void convert(String systemID, String originalSourceSystemID,
 InputStream is, OutputStream os, LinkedHashMap<String, String> properties)
 throws IOException 
```
```
convert:/processor=java;jars=libs;ccn=test.JavaToXML!/
urn:files:java/WSEditorBase.java
```
js Processor - Converts an input to another format by applying a JavaScript method. The js parameter indicates the script that will be used. The fn parameter is the name of the method that will be called from the script. The method must take a string as an argument and return a string. If any of the parameters are missing, an error is thrown and the conversion stops.
```
convert:/processor=js;js=urn:processors:md.js;fn=convertExternal!/urn:files:sample.md
```
json Processor - Converts a JSON input to XML. It has no parameters.
```
convert:/processor=json!/urn:files:personal.json
```
xhtml Processor - Converts HTML content to well-formed XHTML. It has no parameters.
```
convert:/processor=xhtml!/urn:files:test.html
```
wrap Processor - Wraps content in a tag name making it well-formed XML. The rn parameter indicates the name of the root tag to use. By default, it is wrapper. The encoding parameter specifies the encoding that should be used to read the content. By default, it is UTF8. As an example, this processor can be used if you want to process a comma-separated values file with an XSLT stylesheet to produce XML content. The CSV file is first wrapped as well-formed XML, which is then processed with an xslt processor.
```
convert:/processor=wrap!/urn:files:test.csv
```
cache Processor - Caches the converted content obtained from the original document to a temporary file. The cache will be used on subsequent uses of the same URL, thus increasing the speed for the application returning the converted content. If the original URL points to the local disk, the cache will be automatically invalidated when the original file content gets modified. Otherwise, if the original URL points to a remote resource, the cache will need to be invalidated by reloading (Reload (F5) from the toolbar) the URL content that is opened in the editor.
```
convert:/processor=cache/processor=xslt;…..!/urn:files:test.csv
```

Reverse Conversion Processors

All processors defined above can also be used for saving content back to the target resource if they are defined in the URL as reverse processors. Reverse processors are evaluated right to left. These reverse processors allow round-tripping content to and from the target resource.

As an example, the following URL converts HTML to DITA when the URL is opened using the h2d.xsl stylesheet and converts DITA to HTML when the content is saved in the application using the d2h.xsl stylesheet.

convert:/processor=xslt;ss=h2d.xsl/rprocessor=xslt;ss=d2h.xsl!/urn:files:sample.html

Important: If you are publishing a DITA map that has such conversion URL references inside, you need to edit the transformation scenario and set the value of the parameter fix.external.refs.com.oxygenxml to true. This will instruct Oxygen XML Author Eclipse plugin to resolve such references during a special pre-processing stage. Depending on the conversion, you may also require additional libraries to be added using the Libaries button in the Advanced tab of the transformation scenario.