Import Content Dynamically

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

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:sample.xls

The previous example first applies a processor called 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 content resulting 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>

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 from DITA maps as topic references.

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 Editor out-of-the box. 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 XSLT 2.0 processing. 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 XQuery processing. 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 be later 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, from which libraries will be loaded. 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
```

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 Editor 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.