IBM Docs JavaScript API

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

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

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 IBM Docs installation package and copy it to ${WAS_INSTALL_ROOT}/profiles/AppSrv1/bin.
  Note: Extract the IBM Docs 2.0 CR3 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

Methods:

registerIDocsWindow (window)

window is the window of external application.

Register the window information to IBM Docs, then IBM Docs can establish communication with external application. Calling this API is the first step in order to communicate with IBM Docs.

getDocType (callback)

callback is user defined function that will be called after receiving the response from IBM 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 IBM Docs. The second event is sent after IBM 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 IBM Docs, change selection to either next or previous sentence or paragraph in IBM Docs, and respectively replace the selected sentence or paragraph with new ones in IBM Docs. If the inline framed document is a spreadsheet, they are used to get cell content from focused cell in IBM Docs, move focus to either previous or next non-empty cells in IBM Docs, and replace current cell content with the new one in IBM 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 IBM Docs executes the command and responses. It can be optional.

Ask IBM Docs to execute the command with specified arguments if there is any.