History | Edit

Oxygen XML Web Author works with files such as DITA documents, images referenced from documents, and DITA maps used as a context for editing. Oxygen XML Web Author can be instructed to load or save a particular file using an OXY-URL that identifies that file.

An OXY-URL is a URL from a technical point of view, but it is not a normal HTTP URL like the ones that browsers use. It should have several characteristics:
  1. It must have a unique scheme (something like mycms should work).
  2. It should behave like an identifier for the file that it references.
  3. It is usually different from other URLs identifying the file, such as one that would open it in a CMS web interface (herein called CMS-URL) or the one that is used to access the raw content of the file (herein called RAW-URL).

OXY-URL for a File in Oxygen's User Manual

Suppose that the OXY-URL for the DITA/topics/intro.dita topic from the Oxygen User Manual (hosted on GitHub) is the following:
gitgh://https%3A%2F%2Fgithub.com%2Foxygenxml%2Fug/master/DITA/topics/introduction.dita
Notice that:
  1. The URL scheme is gitgh.
  2. It uniquely identifies the file DITA/topics/introduction.dita on branch master in the repository oxygenxml/ug on GitHub.
  3. It is different from the URL used to access the file in the GitHub web interface (CMS-URL) https://github.com/oxygenxml/ug/blob/master/DITA/topics/introduction.dita and from the URL used to access the file's raw content (RAW-URL) https://raw.githubusercontent.com/oxygenxml/ug/master/DITA/topics/introduction.dita.

Opening and Saving Files

For Oxygen XML Web Author to be able to open and save files identified by an OXY-URL, you need to provide a ro.sync.ecss.extensions.api.webapp.plugin.URLStreamHandlerWithContext class and associate it with the scheme of your OXY-URL.

User Authentication

The URLStreamHandlerWithContext receives a contextId for each open and save. This contextId is the session ID of the user for which the file will be opened or saved.

Resolving References to Other Files

The XML content edited in Oxygen XML Web Author may contain references to other files. To access a referenced file, Oxygen XML Web Author needs to compute its OXY-URL based on the OXY-URL of the edited file and the value of the reference to it.

For example, the value of the reference of the following image:
<img src="../image/iris.jpg" />
is
../image/iris.jpg

Relative References

Oxygen XML Web Author tries to resolve relative references against the OXY-URL of the currently open file. Also, when inserting references to other files (for example, images), Oxygen XML Web Author tries to insert relative URLs.

Absolute References (Usually CMS-URL)

For this case, you need to provide a URIResolver that will receive the OXY-URL of the currently opened file and the CMS-URL of the referenced file.
Note: This resolver will need to make sure that the any userinfo from the OXY-URL of the currently open file is transferred to the result.

For example, suppose an image is referenced in a DITA topic and the OXY-URL of the topic (from a GitHub repository) is:

gitgh://ff33bba498@https%3A%2F%2Fgithub.com%2Foxygenxml%2Fug/master/DITA/topics/intro.dita

and the CMS-URL of the referenced image is:

https://github.com/oxygenxml/ug/blob/master/DITA/img/login.png

then the resolved OXY-URL of the image should be:

gitgh://ff33bba498@https%3A%2F%2Fgithub.com%2Foxygenxml%2Fug/master/DITA/img/login.png

WebDAV Example

If the main document is loaded over WebDAV, the following URIResolver rewrites references to HTTP URLs to use WebDAV and inherit the credentials:
URIResolver uriResolver = new URIResolver() {
    @Override
    public Source resolve(String href, String base) throws TransformerException {
      if (base != null && base.indexOf("webdav-") == 0) {
        if (href.indexOf("http://") == 0 || href.indexOf("https://") == 0) {
          try {
            URL hrefUrl = new URL(href);
            URL baseUrl = new URL(base);
            final URL hrefWithUserInfo = 
                URLUtil.attachUserInfo(hrefUrl, baseUrl.getUserInfo(), null);
            return new Source() {
              
              @Override
              public void setSystemId(String systemId) {
              }
              
              @Override
              public String getSystemId() {
                return "webdav-" + hrefWithUserInfo.toExternalForm();
              }
            };
          } catch (MalformedURLException e) {
          }
        }
      }
      return null;
    }
  };

To make Oxygen XML Web Author insert an absolute CMS-URL in content, you should also provide a RelativeReferencesResolver to be used in the Java server-side code and a ReferencesResolver to be used by the JavaScript client-side code.