HCL Docs JavaScript API

In order to integrate HCL Docs with third-party systems, a solution has been implemented to enable browser-side integration by releasing one HCL Docs JavaScript SDK and making some public JavaScript APIs available.

You can develop an external HTML application, create an inline frame, and open an HCL Docs page within the inline frame. You must include the HCL Docs JavaScript SDK in your application. In the beginning, you must call a public API to register the window of external application to HCL Docs, and then two-way communication can be established between the external application and the HCL Docs page in the inline frame. By leveraging these public APIs, you can programmatically access HCL Docs content. The APIs can get HCL Docs content, change HCL Docs content, and change the selection to move to the next or previous object in HCL Docs. Also the APIs can be notified of any selection change in HCL Docs after the listener for the IDOCS.EVENT.selectionChange event has been added.

Note: You can download SDK code for reference.

By default, the external application that has same origin as HCL Docs can work without any configuration. If it is across origins, HCL Docs server admin needs to add this origin into one white list, then external application can communicate with HCL Docs page.

Note: Only the Documents editor and Spreadsheets editor have supported public APIs.

Prerequisites

Change the configuration to enable your domain to be a supported domain, for example, https://xyz.com. There are two ways to update the configuration:

Change concord-config.json by adding your domain into WhiteDomainList as follows, and then restart Docs server.
```
"WhiteDomainList": ["https://app.box.com","https://xyz.com"]
```
Note: WhiteDomainList is the value in ${WAS_INSTALL_ROOT}/profiles/AppSrv1/config/cells/{cell}/IBMDocs-config/concord-config.json.
Get domain_list_mgr.py from the HCL Docs installation package and copy it to ${WAS_INSTALL_ROOT}/profiles/AppSrv1/bin.
Note: Extract the HCL Docs 2.0.1 installation package and then you can find domain_list_mgr.py in the root folder.
Execute the Python command at run time to update the configuration:
On one of the Docs application servers, go to the folder ${WAS_INSTALL_ROOT}/profiles/AppSrv1/bin and run the following command:
- Linux: ./wsadmin.sh -lang jython -username xx -password xx -f domain_list_mgr.py -action add -domain http://*.ibm.com
- Windows: wsadmin.bat -lang jython -username xx -password xx -f domain_list_mgr.py -action add -domain http://*.ibm.com

The following section describes the supported methods in DocumentApp and SpreadsheetApp class.

Class DocumentApp and Class SpreadsheetApp

Methods:

registerIDocsWindow (window): window is the window of external application.; Register the window information to HCL Docs, then HCL Docs can establish communication with external application. Calling this API is the first step in order to communicate with HCL Docs.
getDocType (callback): callback is user defined function that will be called after receiving the response from HCL Docs.; Return string "sheet" or "text" depending on the inline-framed document type.
addListener (eventName, callback): eventName is the supported event name, which can be IDOCS.EVENT.selectionChange and IDOCS.EVENT.contentReady. Note that the event name is case sensitive. The first event will be sent whenever there is a selection change in HCL Docs. The second event is sent after HCL Docs content is loaded successfully.; callback is user defined function that will be called after receiving the specified event.; Return one event id.; Add one listener to the broadcast list of the specified event, the associated callback will be invoked after receiving the event. The event id can be used later to remove the listener from the broadcast list
removeListener(eventId) - optional: eventId a string id.; Remove the listener from the broadcast list
execCommand(command, cmdArgs, callback): command is the supported command, for example, getSelectedTextInScope, selectTextInScope, and setTextInScope. Note that the command name is case sensitive. They are used to get either sentences or paragraphs from HCL Docs, change selection to either next or previous sentence or paragraph in HCL Docs, and respectively replace the selected sentence or paragraph with new ones in HCL Docs. If the inline framed document is a spreadsheet, they are used to get cell content from focused cell in HCL Docs, move focus to either previous or next non-empty cells in HCL Docs, and replace current cell content with the new one in HCL Docs.; cmdArgs is the command arguments in array. The arguments for command getSelectedTextInScope, selectTextInScope, and setTextInScope are [scope], [scope, direction], [value, scope] respectively. The supported scope can be either sentence or paragraph in document and cell in spreadsheet. The supported direction isself ornextSibling. Note that they are case sensitive as well.; callback is user defined function that will be called after HCL Docs executes the command and responses. It can be optional.; Ask HCL Docs to execute the command with specified arguments if there is any.

Response format

When the external application calls these APIs, HCL Docs responds to the external application with a JavaScript object like the following one:

{"data": {"status":
    ["error"|"success"]}, {"detail": [string|boolean|one object]}}

If an error happens, the status is displayed as the error and the detail part as the error message. Typically an error message is a function timeout when the external application fails to get a response from the HCL Docs side.

Note: You can download JavaScript sample code for reference.