Edit online

Embedding an Edit Link that will Launch Web Author

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/app/oxygen.html

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:

General Parameters

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, 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.
  Note: 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 the State of Change Tracking.
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
- text/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).
diffType (File Comparison Tool parameter) - Use merge for the value to allow merging. This opens the comparison in the Merge tool. If this parameter is not specified, the normal File Comparison tool is opened and the left editor is not editable.
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.
runDiffOnChange (File Merge Tool parameter) - This parameter can be used to control whether or not the visual highlights are updated automatically when the user makes changes to the document in the Web Author Merge tool. Possible values are: true, false, and auto (default value and it means that the value is set as true if the size of the merged file is less than 10 KB, otherwise it is set to false). It is useful to set this parameter to false for large documents.
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.
searchMode - This parameter can be used to specify whether the search action opens the Find/Replace mechanism as a pop-up window or as a side view. The possible values are: dialog (default) or sideView.
outlinePlacement - Specifies the side of the interface where the Outline pane is placed. Accepted values are: left or right.
image-cache-size - Specifies the size (in bytes) of the in-memory image cache that Oxygen XML Web Author uses inside the web browser. By default, the cache size is 10000000 bytes. If you encounter images loading slowly (particularly when the same images are loaded multiple times), you can increase the cache size limit to improve performance.

DITA-specific Parameters

ditamap - The OXY-URL of the DITA Map to use as a context for resolving keys.
ditaMapSide - Used to control whether the DITA Map pane is displayed on the left or right side of the editor. Possible values are left or right.
dita.project.url - Specifies the URL of the DITA project file.
dita.project.contextid - Can be used in conjunction with the dita.project.url parameter to specify the context declared inside the DITA project file.
dita.val.url - 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.
show.excluded.content - If set to true, when a DITAVAL filter is used, the content excluded by the DITAVAL filter will be shown as being grayed out. If set to false, the excluded content is hidden.
Note: This parameter has no effect inside the file comparison tool.
KeyscopeStack - 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 - 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.
diffDitamap (File Comparison Tool parameter) - This parameter can be used to specify a DITA map for the right-side editor.
diff.dita.val.url (File Comparison Tool parameter) - This parameter can be used to specify the URL of a DITAVAL file for the right-side editor.
showDitaMapView - When set to true, the DITA Map view will automatically be displayed.
showTopicTitles - When set to true, topic titles are resolved and displayed when a DITA map is opened (the same as if the View Topic Titles mode is selected in the DITA map display mode drop-down).
inplaceReferenceEditingSupported - Can be set to true if the CMS connector is prepared to save user changes in files referenced from the open document. When this option is enabled, the Edit Topic Content mode becomes available when opening a DITA Map.

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/app/oxygen.html

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.

Note: Some of these parameters can be set as loading options from a JavaScript plugin.

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:

In Oxygen XML Editor/Author, edit a DITA Map WebHelp Responsive or DITA Map PDF transformation scenario and open the Parameters tab.
Set values for the following parameters:
- editlink.ditamap.edit.url - The custom OXY-URL of the DITA map used to publish your content. The easiest way to obtain the URL is to open the map in Web Author and copy the URL from the browser's address bar.
- editlink.additional.query.parameters - Optional query parameters to be appended to each generated edit link. Each parameter must start with & (for example: &tags-mode=no-tags).
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:

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.

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"/>

In Oxygen XML Editor/Author, edit a DITA Map PDF5 transformation scenario and open the Parameters tab.
Set values for the following parameters:
- editlink.ditamap.edit.url - The custom OXY-URL of the DITA map used to publish your content. The easiest way to obtain the URL is to open the map in Web Author and copy the URL from the browser's address bar.
- editlink.additional.query.parameters - Optional query parameters to be appended to each generated edit link. Each parameter must start with & (for example: &tags-mode=no-tags).
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.

Resources

For more information about how Web Author can be integrated within various stages of a documentation review workflow, see the following resources: