Embedding an Edit Link that will Launch Web Author
Edit online

You can control or streamline your documentation review workflow by configuring Edit links that are either sent to reviewers or embedded in an email, web page, published output, or anywhere that you can provide a usable link. These Edit links will automatically launch a particular document in Oxygen XML Web Author. A reviewer then simply clicks the link and they will be redirected to the Oxygen XML Web Author editing page with that particular file open and editable.

URL Parameters

The Edit link can be created with a carefully built target and using URL parameters. The base URL for the link is the URL that you see in the browser when the Dashboard page is opened.

Example: The base URL for Oxygen XML Web Author demo deployment
https://www.oxygenxml.com/oxygen-xml-web-author/

The base URL is then followed by parameters that contain the information about the file to open and the options used to load it.

The allowed URL parameters are as follows:
  • url - The OXY-URL that identifies the file to be opened.
  • folderUrl - You can use this parameter to navigate to the Dashboard with the corresponding repository tab open and the content of the specified folder displayed.
  • userName - The user name of the author.
  • autoSaveInterval - The interval of time (in seconds) to wait until an auto-save is performed. If set to 0 or false, the auto-save is disabled.
  • ccOnEnter - If set to true, the content completion popup window is displayed when the user presses Enter. If set to false, the Enter key works similar to the behavior in a normal word processor application.
  • hideBreadcrumb - If set to true, the breadcrumb will not be displayed in the interface.
  • lang - You can use this parameter to impose a specific language for the Oxygen XML Web Author interface. The possible values are:
    • en_US - English
    • de_DE - German
    • fr_FR - French
    • ja_JP - Japanese
    • nl_NL - Dutch
    • zh_CN - Chinese
  • spell.check.language - Specifies the default language used for spell checking in the document. The value must be in either a 2-digit or 4-digit language code format (for example, en or en_US).
  • trackChanges - Flag that controls whether or not the editor should track changes. The possible values are:
    • default - The status of change tracking is determined by the server's global options.
    • enabled - Change tracking is enabled but the user can disable it using a toolbar action.
    • forced - Change tracking is enabled and the user cannot disable it. The user can reject their own changes, but cannot accept or reject changes made by others.
    If you use a value other than default, the server change tracking status (as configured in the Administration Page) should not be "Stored in the document". For more information about this parameter, see Control Change Tracking State
  • ditamap - (DITA-specific Parameter) The OXY-URL of the DITA Map to use as a context for resolving keys.
  • dita.val.url - (DITA-specific Parameter) The OXY-URL of a DITAVAL filter. It is used for resolving keys whose values depend on profiling conditions and it grays out content that is excluded by the DITAVAL filter.
  • KeyscopeStack - (DITA-specific Parameter) Used for resolving keys when DITA 1.3 key scopes are defined in the DITA map. The value looks like this:
    a b c,d e f
    for a DITA map that has the key scope defined like this:
    <topicref keyscope="a b c"><topicref keyscope="d e f"/></topicref>
  • expandTopicRefs - (DITA-specific Parameter) If set to true, when a DITA map is opened in Oxygen XML Web Author, the content of all topics referenced in the map will be presented.
  • contentType - For cases where Web Author cannot open a document that has an unrecognized file extension, you can use this parameter as a loading option to pass a specific file type so that client-side editing support can be used for editing the document. You can also specify an encoding type. Examples for values:
    • image/png
    • application/xml
    • application/markdown;charset=utf-8
  • textModeReadOnly - If set to true, the Web Author XML text editing mode will always be set to read-only.
  • tags-mode - You can use this parameter to specify the Tags Display Mode for the document. The possible values are:
    • full-tags-with-attributes - Displays full tag names with attributes for both block and inline elements.
    • full-tags - Displays full tag names without attributes for both block and inline elements.
    • block-tags - Displays full tag names for block elements and simple tags without names for inline elements.
    • inline-tags - Displays full tag names for inline elements, while block elements are not displayed.
    • partial-tags - Displays simple tags without names for inline elements, while block elements are not displayed.
    • no-tags - No tags are displayed.
  • compactTagsMode - If the user has the Tags Display Mode option set to any value that shows the XML tags, setting this parameter to true will compact the tags (for example, multiple tags presented on the same line). If set to false, each tag of a block element is presented on a separate line.
  • quickUpDownNavigation - If set to true, horizontal cursor positions between block elements are avoided. It also forces tags of block elements to be displayed on separate lines, if visible.
  • diffUrl - (File Comparison Tool Parameter) This parameter can be used in conjunction with the url parameter to specify files to compare with each other. This parameter specifies the URL of the file to be opened in the right side of the file comparison tool while the url parameter specifies the URL of the file to be opened in the left side.
  • diffBaseUrl - (File Comparison Tool Parameter) This parameter can be used in conjunction with the url and diffUrl parameters to perform a 3-way file comparison. This parameter specifies the URL of the original base file, while the url parameter specifies the URL of the file to be opened in the left side of the file comparison tool (the local file), and the diffUrl parameter specifies the URL of the file to be opened in the right side (the remote file).
  • leftEditorLabel - (File Comparison Tool Parameter) This parameter can be used to specify the label used for the name of the file in the left side of the file comparison tool. Normally, the file name is used.
  • rightEditorLabel - (File Comparison Tool Parameter) This parameter can be used to specify the label used for the name of the file in the right side of the file comparison tool. Normally, the file name is used.
  • schematron.imposed.phase - This parameter can be used to impose the Schematron phase to use when validating with a Schematron file.
  • schematronUrl - (Markdown-specific parameter) This parameter can be used to specify the URL of a Schematron file that will be used to validate the Markdown document.

Example: OXY-URL for a Sample Deployment

Suppose that the Oxygen XML Web Author is deployed at the following URL:
http://www.example.com/web-author-component-integration/
The user (John Doe) wants to edit a file (located at http://www.test.com/topics/topic.xml) in the context of a DITA map (located at http://www.test.com/map.xml). In this case, the editing URL should be:
http://www.example.com/web-author-component-integration/app/oxygen.html
?url=http%3A%2F%2Fwww.test.com%2Ftopics%2Ftopic.xml
&ditamap=http%3A%2F%2Fwww.test.com%2Fmap.xml
&userName=John%20Doe
Note: The parameter values are percent-encoded before being added to the editing URL.

How to Embed the Edit Link in Published DITA Output (WebHelp or PDF)

Oxygen XML Editor/Author comes bundled with a built-in DITA-OT plugin that can be used to embed an Edit link in the WebHelp and PDF output for each topic.

To embed an Edit link for each topic in DITA WebHelp or PDF output, follow this procedure:
  1. In Oxygen XML Editor/Author, edit a DITA Map WebHelp Responsive or DITA Map PDF transformation scenario and open the Parameters tab.
  2. Set values for the following parameters:
    • editlink.remote.ditamap.url - The custom OXY-URL of the DITA Map suitable for opening in Oxygen XML Web Author.
    • editlink.web.author.url - The URL of the Web Author installation (for example: https://www.oxygenxml.com/oxygen-xml-web-author/).
  3. Run the transformation scenario.

Result: In the WebHelp or PDF output, all topics will have an Edit link to the right side of the title and clicking the link will launch that particular document in Oxygen XML Web Author.

Tip: For PDF output, if you want the edit link to be attached to an entire bookmap, you need to call the add-map-edit-link named template in your front page customization. For example:
<xsl:template name="createFrontCoverContents">
  <!-- set the title -->
  <fo:block xsl:use-attribute-sets= class="code-quote">"__frontmatter__title">
    <xsl:choose>
      <xsl:when test="$map/*[contains(@class,' topic/title ')][1]">
        <xsl:apply-templates select="$map/*[contains(@class,' topic/title ')][1]"/>
      </xsl:when>
      <xsl:when test="$map//*[contains(@class,' bookmap/mainbooktitle ')][1]">
        <xsl:apply-templates select="$map//*[contains(@class,' bookmap/mainbooktitle ')]
[1]"/>
      </xsl:when>
      <xsl:when test="//*[contains(@class, ' map/map ')]/@title">
        <xsl:value-of select="//*[contains(@class, ' map/map ')]/@title"/>
      </xsl:when>
      <xsl:otherwise>
        <xsl:value-of select="/descendant::*[contains(@class, ' topic/topic ')]
[1]/*[contains(@class, ' topic/title ')]"/>
      </xsl:otherwise>
    </xsl:choose>
    <fo:block>
      <xsl:call-template name="add-map-edit-link"/>
    </fo:block>
  </fo:block>
    
  <!-- set the subtitle -->
  <xsl:apply-templates select="$map//*[contains(@class,' bookmap/booktitlealt ')]"/>
  <fo:block xsl:use-attribute-sets= class="code-quote">"__frontmatter__owner">
    <xsl:apply-templates select="$map//*[contains(@class,' bookmap/bookmeta ')]"/>
  </fo:block>
</xsl:template>

How to Embed the Edit Link in Published PDF5 Output

To embed an Edit link for each topic in DITA PDF5 output (obtained using the PDF5-ML plugin), follow this procedure:
  1. Add the following import xsl:include href="../../com.oxygenxml.editlink/pdf5.xsl"/> in the com.antennahouse.pdf5.ml/customization/dita2fo_custom.xsl file of the PDF5 plugin.
  2. In the com.oxygenxml.editlink/plugin.xml file, uncomment the lines that configure the parameters for the PDF5 plugin:
    <feature extension="com.antennahouse.pdf5.ml.param" value="params.xml" type="file"/>
<feature extension="com.antennahouse.pdf5.ml.saxon.param" value="params.xml" type="file"/>
<feature extension="com.antennahouse.pdf5.ml.psmi.param" value="params.xml" type="file"/>
  3. In Oxygen XML Editor/Author, edit a DITA Map PDF5 transformation scenario and open the Parameters tab.
  4. Set values for the following parameters:
    • editlink.remote.ditamap.url - The custom OXY-URL of the DITA Map suitable for opening in Oxygen XML Web Author.
    • editlink.web.author.url - The URL of the Web Author installation (for example: https://www.oxygenxml.com/oxygen-xml-web-author/).
  5. Run the transformation.

Result: In the PDF output, all topics will have an Edit link to the right side of the title and clicking the link will launch that particular document in Oxygen XML Web Author.