Edit online

FAQ for Customizations

This topic contains some frequently asked questions about Web Author customizations.

How can I prevent consecutive spaces from being inserted in documents?

  1. Create a plugin that implements the AuthorDocumentFilter class. It filters consecutive spaces from being inserted in the document. The filter should override all methods from AuthorDocumentFilter that intercept content changes.
  2. Install the custom filter on all documents by implementing a WebappEditingSessionLifecycleListener that can be installed via a WorkspaceAccessPluginExtension (WorkspaceAccess extension in the plugin.xml file):
    public class CustomFilterInstaller implements WorkspaceAccessPluginExtension {
  @Override
  public void applicationStarted(StandalonePluginWorkspace pluginWorkspaceAccess) {
    WebappPluginWorkspace pluginWorkspace = (WebappPluginWorkspace)PluginWorkspaceProvider.getPluginWorkspace();
      pluginWorkspace.addEditingSessionLifecycleListener(new WebappEditingSessionLifecycleListener() {
        @Override
        public void editingSessionStarted(String sessionId, AuthorDocumentModel documentModel) {
          documentModel.getAuthorDocumentController().setDocumentFilter(new CustomAuthorDocumentFilter(documentModel));
        }
      });
Note:
When instantiating the AuthorDocumentFilter, the AuthorDocumentModel object is passed because the filter needs it to check for duplicate spaces.

How can I customize the inserted table fragment for a DITA framework extension?

See the dita-extension-replace-insert-table-action sample project that uses a Framework Extension Script (EXF) to extend the built-in DITA framework to replace the default Insert Table action with another action that uses an InsertFragmentOperation to insert a CALS table element that has @frame, @colsep, and @rowsep attributes already set.

How can I target a specific font size in CSS, using a custom framework?

Suppose you want to modify a custom framework so that when a user selects a specific font size (small, medium, large) in Preferences, the font size selected is applied to the document.

To achieve this, it is recommended to use em units (instead of px, for example). This causes the font size to be adjusted according to the option chosen by the user in Preferences.

How can I obtain a URL parameter from a file open in Web Author?

The URL parameters are forwarded to the sync.api.Workspace.LoadingOptions object. As a side-note, plugins can contribute or intercept a sync.api.Workspace.LoadingOptions object by listening on the sync.api.Workspace.EventType.BEFORE_EDITOR_LOADED event. The LoadingOptions objects (client-side) are forwarded to the server where they end up in ro.sync.ecss.extensions.api.access.EditingSessionContext. Thus, you can access the URL parameters from the EditingSessionContext object (server-side), which can be obtained like this:
EditingSessionContext editingSessionContext = 
  authorDocumentModel.getAuthorAccess().getEditorAccess().getEditingContext();

How can I view whitespaces in Author mode?

You can create a custom font and combine it with the default font for any element:
@font-face {
    font-family: Arial_spacedot;
    src: url(Arial_spacedot.ttf);
    unicode-range: U+1780-17FF, U+200B-200C, U+25CC;
  }
  * { font-family: Arial_spacedot,Arial; }

How can I localize custom actions implemented in JavaScript?

To localize action messages, you must use the Translation JavaScript API:

  1. Register your messages via sync.Translation.addTranslations, like this:
    let myMsgs={
	YES_KEY_ : {
		"en_US" : "Yes",
		"de_DE" : "Ja",
		"fr_FR" : "Oui",
		"ja_JP" : "はい",
		"nl_NL" : "Ja",
		"zh_CN" : "是的"
	}
};
sync.Translation.addTranslations(myMsgs);
  2. Use the message key instead of the hard-coded "Yes" string:
    tr(msgs["YES_KEY_"])
Notice:
This only allows adding new messages for the default languages. You cannot add a new language.

How can I define a document template with a dynamic relative path?

Suppose you want to generate files from a document template that contains a link to a specific document. In the generated files, the link should be relative to the location where the template is created and the location of the link target. When the files are created in different directories, the relative path should be automatically and accurately calculated.

To make this happen, in your newly created template, you must use the ${makeRelative(base, location)} and ${currentFileURL} Editor Variables.

For example, in a WebDav server, your template may look like this:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="newfile">
  <title>New File</title>
  <body>
    <p>This is a new file.</p>
    <p>Link to a specific document:
      <xref
        href="${makeRelative(${currentFileURL}, 
webdav-https://your-web-dav-server/path/to/your/target-document.dita)}"
        format="dita"
        scope="external"
      />
    </p>
  </body>
</topic>
Note:
Make sure that you use the absolute OXY-URL in the location parameter of the ${makeRelative(base, location)} editor variable.
Depending on where you create the new file from the template, the relative path to the target document will be properly computed. It may look like this:
<xref href="../../target-document.dita" format="dita" scope="external" />
or like this (and so on):
<xref href="../target-document.dita" format="dita" scope="external"/>

How can I add a custom action on the DITA Map side-view?

You can extend the standard DITA Map side-view and add a custom action in the side-view's toolbar (next to the Configure DITA Context action) by overriding its sync.view.ViewRenderer.getToolbarDescriptor and sync.view.ViewRenderer.getToolbarActionsMap methods.

For example, if you want to add an action to reload the view, you can do this from a plugin with the following script:
class RefreshMapAction extends sync.actions.Action {
  constructor() {
    super({displayName: "Refresh"});
  }

  /**
   * @override
   */
  actionPerformed(callback) {
    let ditaContext = workspace.getEditingContextManager().getDitaContext();
    workspace.getEditingContextManager().updateDitaContext(new sync.api.DitaContext());
    workspace.getEditingContextManager().updateDitaContext(ditaContext);
    callback();
  }
}

class CustomDitaMapView extends sync.api.dita.DitaMapView {
  /**
   * @override
   */
  getToolbarActionsMap() {
    let toolbarActionsMap = super.getToolbarActionsMap();
    toolbarActionsMap["DMM/Refresh"] = new RefreshMapAction();
    return toolbarActionsMap;
  }

  /**
   * @override
   */
  getToolbarDescriptor() {
    let toolbarDescriptor = super.getToolbarDescriptor();
    toolbarDescriptor.children.push({
      id: "DMM/Refresh",
      type: "action"
    });
    return toolbarDescriptor;
  }
}

workspace.listenOnce(sync.api.Workspace.EventType.EDITOR_LOADED, e => {
  let customView = new CustomDitaMapView();
  workspace.viewManager.addView('dita-map-view');
  workspace.viewManager.installView('dita-map-view', customView, {
    side: 'left',
    initiallyClosed: false
  });
});
Notice:
When installing the view, you have to use "dita-map-view" to override the view that is installed by the framework.
Note:
To enable the refresh action, you can do this by implementing the isEnabled method in RefreshMapAction and return true or false. When enabling status changes, you have to call workspace.getViewManager().getActionsManager('dita-map-view').refreshActionsStatus() to update the UI.

How to list files in a directory on the server?

To list the server-side files in a directory, you must open a connection with java.net.URL.openConnection() then cast the java.net.URLConnection object to ro.sync.net.protocol.FileBrowsingConnection. Then, use the ro.sync.net.protocol.FileBrowsingConnection.listFolder() method.