RealObjects Nimbudocs Editor 5.0.6986_Beta8

Class: NimbudocsEditor


NimbudocsEditor

The NimbudocsEditor API object. Use NimbudocsEditor.create to create a new instance. The NimbudocsEditor.create and NimbudocsEditor.when are static methods that have to be called on the Class itself. All other methods have to be called on the instance returned in the NimbudocsEditor.onready callback
Guides:
  • Tutorial: Quick Integration

Classes

Action
EditorProperties
Event
EventListener
StyleSheet

Namespaces

spellChecker

Methods

create(appContainer, server, options)Booleanstatic
Creates a NimbudocsEditor instance object and inserts the editor into the DOM. Use an onready event handler to get the created editor object.
Parameters:
Name Type Argument Description
appContainer String | Element | jQuery The element which will contain the editor. This can either be the ID of the element, a DOM element or a jQuery object.
server String The URL of the Nimbudocs Editor application on the backend server.
options Object optional
 See options for detailed information about all options.
Guides:
  • Tutorial: Quick Integration
Returns:
  • Boolean
Whether the creation process has started. Returns false if browser is not supported.
when(promise)Promisestatic
Creates and returns a new Promise which is resolved once all of the argument Promises are resolved. This method is safe for undefined arguments or arguments of a different type. If all supplied arguments are non-Promises (e.g. undefined, string, number, etc.), the "then" handler is called immediately with all the supplied arguments.
Parameters:
Name Type Argument Description
promise Promise repeatable
 One or more Promises.
Returns:
  • Promise
A new Promise. This promise is resolved with same values of the argument Promises in the same order as the arguments.
Example:
var p1 = editor.fetchNumberOfParagraphs();
var p2 = editor.fetchNumberOfWords();
var p1 = editor.fetchNumberOfCharacters();

NimbudocsEditor.when(p1, p2, p3).then(function(paras, words, chars) {
    doSomething(paras, words, chars);
});
addAuthorStyleSheet(styleSheet)async
Adds an author style sheet to the document. Author style sheets are only applied to the document currently in the document. They are removed when a new document is loaded.
Parameters:
Name Type Description
styleSheet Object A representation of a style sheet as an object.
Properties
Name Type Argument Default Description
content String optional
 The content of the author style sheet to be added.
title String optional
 The title of the author style sheet to be added. The title can be used to manipulate this style sheet through other methods. If no title is set, the style sheet will be given an unique identifier as title.
url String optional
 The URL this style sheet will be loaded from. If both the content and url parameters are set, the url is set as the base URL for the style sheet.
overwrite Boolean optional
 false Determines behavior when a style sheet with the specified title already exists in the document. Set to true to overwrite and replace the existing style sheet. Set to false to merge the new styles into the existing style sheet with the same name.
See:
Example:
editor.addAuthorStyleSheet({ content: "p { color: red; } span.emphasis { font-style: italic; font-weight: bold }", title: "colorAndEmphasis"});
addDocumentStyleSheet(styleSheet)async
Adds a style sheet to the <style> element in the <head> section of the document.
Parameters:
Name Type Description
styleSheet Object A representation of a style sheet as an object.
Properties
Name Type Argument Default Description
content String optional
 The content of the editor style sheet to be added.
title String optional
 The title of the document style sheet to be added. The title can be used to manipulate this style sheet through other methods. If no title is set, the style sheet will be given an unique identifier as title.
url String optional
 The URL this style sheet will be loaded from. If both the content and url parameters are set, url is ignored.
overwrite Boolean optional
 false Determines behavior when a style sheet with the specified title already exists in the document. Set to true to overwrite and replace the existing style sheet. Set to false to merge the new styles into the existing style sheet with the same name.
See:
Example:
editor.addDocumentStyleSheet({ content: "p { color: red; } span.emphasis { font-style: italic; font-weight: bold }", title: "colorAndEmphasis"});
addEditorStyleSheet(styleSheet)async
Adds an editor style sheet to the document. Editor style sheets persist when a new document is loaded. It is recommended to use this method to load styles that influence the behavior of the editor, such as Style Templates.

Editor style sheets are persistent, i.e. they are not removed when loading a new document or creating a new document to the editor. The only way to remove editor styles is by using the NimbudocsEditor#clearEditorStyleSheets and NimbudocsEditor#removeEditorStyleSheet methods.

Using editor style sheets is recommended when you want to ensure certain styles are always present in the document, regardless of the document that is loaded. This can be especially useful for Style Templates.

Parameters:
Name Type Description
styleSheet Object A representation of a style sheet as an object.
Properties
Name Type Argument Default Description
content String optional
 The content of the editor style sheet to be added.
title String optional
 The title of the editor style sheet to be added. The title can be used to manipulate this style sheet through other methods. If no title is set, the style sheet will be given an unique identifier as title.
url String optional
 The URL this style sheet will be loaded from. If both the content and url parameters are set, the url is set as the base URL for the style sheet.
overwrite Boolean optional
 false Determines behavior when a style sheet with the specified title already exists in the document. Set to true to overwrite and replace the existing style sheet. Set to false to merge the new styles into the existing style sheet with the same name.
See:
Example:
editor.addEditorStyleSheet({ content: "p { color: red; } span.emphasis { font-style: italic; font-weight: bold }", title: "colorAndEmphasis"});
addEventListener(selector, type, handler)NimbudocsEditor.EventListener

Adds an event listener for the specified event on all elements that match the specified CSS selector or for the action that matches the specified action ID.

Please note that adding an excess amount of event listeners may negatively impact performance

Parameters:
Name Type Description
selector String The CSS selector for document elements or the ID of the action, or the document keyword.
type String The event type.
handler Function The handler to be called when the event is triggered.
Guides:
  • Tutorial: Event Handling
See:
Listens to Events:
Returns:
Returns an instance of this object when a new event listener is added. You can pass this object to NimbudocsEditor#removeEventListener to remove the event listener again, or to modify the callback method that should be called.
Example:
// add a listener to every paragraph of the document
editor.addEventListener("p", "mouseup", function(e) {
    //...
});

// add a listener to the editor's "bold" action
editor.addEventListener("bold", "actioninvoke", function(e) {
    //...
});

// add a listener to the dictionary
editor.addEventListener("document", "dictionaryChange", function(e) {
    //...
});
clearAuthorStyleSheets()async
Removes all author style sheets that were added through NimbudocsEditor#addAuthorStyleSheet .
See:
Example:
editor.clearAuthorStyleSheets();
clearDocumentStyleSheets()async
Removes all style elements embedded in the document <head> element.
See:
Example:
editor.clearDocumentStyleSheets();
clearEditorStyleSheets()async
Removes all editor style sheets that were added through NimbudocsEditor#addEditorStyleSheet.
See:
Example:
editor.clearEditorStyleSheets();
endComparison(boolean)async

Ends the comparison mode by accepting all changes. Set optional argument to true to reject and end instead.

Parameters:
Name Type Description
boolean rejectAll Set to true if the changes should be rejected instead of accepted
fetchAnnotationCount()Integerasync
Returns the number of annotations in the document.
Returns:
  • Integer
fetchAuthorStyleSheets()Array.<StyleSheet>async
Returns all author style sheets as an array of NimbudocsEditor.StyleSheet objects.
See:
Returns:
  • Array.<StyleSheet>
fetchBlockElementAttributes()Objectasync
Returns the attributes of the block element at the caret position as an object. The attributes are stored as key/value pairs in this object.
See:
Returns:
  • Object
Example:
editor.fetchBlockElementAttributes().then(function(val) {
    var obj = val;
});
fetchBodyFragment()Stringasync
Returns the content of the document's <body> element.
See:
Returns:
  • String
Example:
fetchBodyFragment().then(function(val) {
    var strContent = val;
});
fetchBookmarkList()Array.<String>async
Returns a list of bookmarks of the document.
Returns:
  • Array.<String>
fetchCaretPosition()Array.<String>async
Returns the caret position as an XPath expression.
Returns:
  • Array.<String>
Array containing the XPath expression for the caret position or expressions for the beginning and the end of the selection.
fetchChangesCount()Integerasync
Returns the number of tracked changes in the document (The "Track Change" mode must be enabled).
Returns:
  • Integer
fetchCurrentElement()Stringasync
Returns the element at the caret position as an HTML string.
Returns:
  • String
fetchCurrentElementContent()Stringasync
Returns the content of the element at the caret position as an HTML string.
Returns:
  • String
fetchCurrentTableColumnCellAttributes()Objectasync
Returns the attributes of all cells in the table column at the caret position as a nested object.
See:
Returns:
  • Object
Example:
editor.fetchCurrentTableColumnCellAttributes().then(function(val) {
    var columnCellAttributes = val;
});
// Example contents of columnCellAttributes:
// columnCellAttributes = [
//    { 
//        "attribute1": "value1",
//        "attribute2": "value2", 
//        ...
//    },
//    {
//        ...
//    }
// }
fetchCurrentTableRowCellAttributes()Objectasync
Returns the attributes of all cells in the table row at the caret position as a nested object.
See:
Returns:
  • Object
Example:
editor.fetchCurrentTableRowCellAttributes().then(function(val) {
    var rowCellAttributes = val;
});

// Example content of rowCellAttributes:
// rowCellAttributes = [
//    { 
//        "attribute1": "value1",
//        "attribute2": "value2", 
//        ...
//    },
//    {
//        ...
//    }
// }
fetchDocument(prettyPrint)Stringasync
Returns the document as an HTML string.
Parameters:
Name Type Argument Default Description
prettyPrint Boolean optional
 false Whether to pretty print the HTML string.
Returns:
  • String
Example:
editor.fetchDocument().then(function(val) {
    var strDocument = val;
});
fetchDocumentBaseUrl()Stringasync
Returns the base URL of the document.
See:
Returns:
  • String
fetchDocumentLanguage()Stringasync
Returns the language of the document or null if no language is set.
Returns:
  • String
fetchDocumentName()Stringasync
Returns the name of the document.
See:
Returns:
  • String
fetchDocumentStyleSheets()Array.<StyleSheet>async
Returns all document style sheets as an array of NimbudocsEditor.StyleSheet objects.
See:
Returns:
  • Array.<StyleSheet>
fetchDocumentTextDirection()Stringasync
Returns the base text direction of the document or null if no direction is set.
Returns:
  • String
fetchEditorStyleSheets()Array.<StyleSheet>async
Returns all editor style sheets as an array of NimbudocsEditor.StyleSheet objects.
See:
Returns:
  • Array.<StyleSheet>
fetchElementAttributes()Objectasync
Returns the attributes of the element at the caret position as an object. The attributes are stored as key/value pairs in this object.
Returns:
  • Object
Example:
editor.fetchElementAttributes().then(function(val) {
    var obj = val;
});
fetchElementListAttributes(expression, global)Array.<Object>async

Returns an array representing the attributes of the elements matching the specified XPath expression. The elements are retrieved in DOM order.

Parameters:
Name Type Argument Default Description
expression String The XPath specifying the list of elements to retrieve the attributes off.
global Boolean optional
 false Whether to apply the XPath expression to the entire document instead of restricting it to the current selection.
Returns:
  • Array.<Object>
An array of objects each containing the attributes of an element as key/value pairs. Each entry matches one of the elements specified by the XPath expression in DOM order.
Example:
var expression = "//p";
 
editor.fetchElementListAttributes(expression).then(function(val) {
    var attributeArray = val;
});
 
// Example contents of attributeArray:
// 
// attributeArray = [
//     { "style": "color: red" },
//     { "class": "paragraph" },
//     { null },
//     { "style": "color: red", "class": "paragraph" }
// ];
fetchElementListStyles(expression, global)Array.<Object>async

Returns an array representing the styles of the elements matching the specified XPath expression. The elements are retrieved in DOM order.

Parameters:
Name Type Argument Default Description
expression String The XPath specifying the list of elements to retrieve the attributes off.
global Boolean optional
 false Whether to apply the XPath expression to the entire document instead of restricting it to the current selection.
Returns:
  • Array.<Object>
An array of objects each containing the styles of an element as key/value pairs. Each entry matches one of the elements specified by the XPath expression in DOM order.
Example:
var expression = "//p";
 
editor.fetchElementListStyles(expression).then(function(val) {
    var styleArray = val;
});
 
// Example contents of styleArray:
// 
// styleArray = [
//     { "color": "red" },
//     { "font-size": "12pt" },
//     { null },
//     { "color": "red", "font-size": "12pt" }
// ];
fetchFinalDocument(prettyPrint)Stringasync
Returns the final document with all changes performed in track changes mode as an HTML string.
Parameters:
Name Type Argument Default Description
prettyPrint Boolean optional
 false Whether to pretty print the HTML string.
Returns:
  • String
The final document.
fetchFragmentDirection()Stringasync
Returns the direction of the fragment at the caret position or null if no direction is set.
Returns:
  • String
Example:
editor.fetchFragmentDirection().then(function(val) {
    var lang = val;
});
fetchFragmentLanguage()Stringasync
Returns the language of the fragment at the caret position.
Returns:
  • String
Example:
editor.fetchFragmentLanguage().then(function(val) {
    var lang = val;
});
fetchHeadElementContent()Stringasync
Returns the content of the <head> element as an HTML string.
See:
Returns:
  • String
Example:
editor.fetchHeadElementContent().then(function(val) {
    var strHeadElement = val;
});
fetchNumberOfCharacters(countSpaces)Integerasync
Returns the number of characters in the text of the document. The argument determines whether spaces are counted or not.
Parameters:
Name Type Description
countSpaces Boolean Determines if spaces are counted
Returns:
  • Integer
Example:
editor.fetchNumberOfCharacters(true).then(function(val) {
    var chars = val;
});
fetchNumberOfImages()Integerasync
Returns the numbers of images in the document.
Returns:
  • Integer
Example:
editor.fetchNumberOfImages().then(function(val) {
    var images = val;
});
fetchNumberOfPages()Integerasync
Returns the number of pages of the document. Returns 0 if the editor is not in paged mode.
Returns:
  • Integer
fetchNumberOfParagraphs()Integerasync
Returns the numbers of paragraphs in the document.
Returns:
  • Integer
Example:
editor.fetchNumberOfParagraphs().then(function(val) {
   var paragraphs = val;
});
fetchNumberOfWords()Integerasync
Returns the number of words in the text of the document.
Returns:
  • Integer
Example:
editor.fetchNumberOfWords().then(function(val) {
   var words = val;
});
fetchOriginalDocument(prettyPrint)Stringasync
Returns the original document without any changes performed in track changes mode as an HTML string.
Parameters:
Name Type Argument Default Description
prettyPrint Boolean optional
 false Whether to pretty print the HTML string.
Returns:
  • String
The original document.
fetchPageProperties()Objectasync

Returns the page properties as object.

Returns:
  • Object
.
Example:
editor.fetchPageProperties().then(function(properties) {
    var pageProperties = properties;
});
fetchParentElementByName(ancestorName)Stringasync
Returns the nearest ancestor of the element at the caret position with the node name ancestorName as HTML string.
Parameters:
Name Type Description
ancestorName String The name of the ancestor.
Returns:
  • String
Example:
editor.fetchParentElementByName("table").then(function(val) {
    var strParentElement = val;
});
fetchParentElementByNameAttributes(ancestorName)Objectasync
Returns the attributes of the nearest ancestor of the element at the caret position with the node name ancestorName as an object.
Parameters:
Name Type Description
ancestorName String The name of the ancestor
Returns:
  • Object
Example:
editor.fetchParentElementByNameAttributes("div").then(function(val) {
    var strParentElementAttrs = val;
});
fetchParentElementByNameContent(ancestorName)Stringasync
Returns the content of the nearest ancestor of the element at the caret position with the node name ancestorName as HTML string.
Parameters:
Name Type Description
ancestorName String The name of the ancestor
Returns:
  • String
Example:
editor.fetchParentElementByNameContent("div").then(function(val) {
    var strContent = val;
});
fetchPlainText()Stringasync
Returns the editor's content as plain text
Returns:
  • String
Example:
editor.fetchPlainText().then(function(val) {
    var strContent = val;
});
fetchSelectedColumnsCellAttributes()Objectasync
Returns the attributes of all cells in the currently selected columns as a nested object. The object contains the selected columns on the first level. Each column in turn contains its cells, which contain their attribute names and values as key/value pairs.
See:
Returns:
  • Object
The attributes as an object.
Example:
editor.fetchSelectedColumnsCellAttributes().then(function(val) {
    var obj = val;
});
fetchSelectedRowsCellAttributes()Objectasync
Returns the attributes of all cells in the currently selected rows as a nested object. The object contains the selected rows on the first level. Each row in turn contains its cells, which contain their attribute names and values as key/value pairs.
See:
Returns:
  • Object
The attributes as an object.
Example:
editor.fetchSelectedRowsCellAttributes().then(function(val) {
    var obj = val;
});
fetchSelectionContent()Stringasync
Returns the content of the current selection as an HTML string.
Returns:
  • String
Example:
editor.fetchSelectionContent().then(function(val) {
    var strContent = val;
});
fetchSelectionPlainText()Stringasync
Returns the content of the current selection as plain text.
Returns:
  • String
Example:
editor.fetchSelectionPlainText().then(function(val) {
    var strContent = val;
});
getAction(actionId)Action
Returns the action with the ID actionId as an NimbudocsEditor.Action object.
Parameters:
Name Type Description
actionId String The ID of the action.
Guides:
  • Tutorial: Action Reference
Returns:
  • Action
The action. Returns null if the action does not exist.
getCollabUrl()String
Returns the collaboration URL including the required GET parameters. Through this URL guests can join a collaboration session of this editor.
Returns:
  • String
getCollabUserlist()Object
Returns the collaboration user list
Returns:
  • Object
getCurrentPageNumber()Integer
Returns the number of the page which contains the caret.
Returns:
  • Integer
getDocumentId()String
Returns the document ID of the editor session.
Returns:
  • String
getEditorProperties()NimbudocsEditor.EditorProperties
Returns a map of relevant editor properties
Returns:
The editor properties.
getId()String
Returns the ID of the editor. This is also the ID of the HTML element which contains the editor instance.
Returns:
  • String
getPdfUrl(options)String
Returns a URL that allows retrieving the document as a PDF as long as it is opened in the editor.
Parameters:
Name Type Description
options Object An object containing a number of configuration options for the request made to the PDFreactor service.
Properties
Name Type Argument Description
userId Boolean optional
 Whether to add the user ID as a get paremeter. Set this to true when URL is to be used from a user agent that does not have the session cookie of this editor.
comments String optional
 Specifies the type of comments to include in the PDF, if any. Set to "pdf" to embed comments as PDF comments.
Returns:
  • String
The URL to retrieve the PDF from.
getUIConfig()Object
Returns the current uiconfig as JSONObject
Returns:
  • Object
The uiconfig.
getUserId()String
Returns the user ID of the editor session.
Returns:
  • String
getUserName()String
Returns the user name.
Returns:
  • String
hasTrackedChanges()Booleanasync
Returns whether the documents contains changes tracked by Track Changes feature.
Returns:
  • Boolean
Example:
editor.hasTrackedChanges().then(function(val) {
    var hasChanges = val;
});
hibernateEditor(removeFromMemory)Stringasync
Hibernates the editor (either in memory or disc). Returns a promise that will be resolved as soon as the server is hibernated. The promise will be rejected when calling hibernateEditor() while the editor is already hibernated or the editor is restoring from hibernation. It is not required to use the promise, as API calls invoked directly after "hibernateEditor()" (programmatically or by user interaction), will be queued to execute after hibernation has completed. Nevertheless it is recommended and good practice to use the promise, as instantly calling an API method will lead to the situation that the editor is restored as soon as the promise is resolved due to the queued API call.
Parameters:
Name Type Description
removeFromMemory Boolean Whether the editor should be removed from memory after hibernating, so that it only exists in an auto-save state on disc.
Returns:
  • String
hideStatusMessage()
Hides the status message widget.
importLegacyDocument(content, baseUrl)async

Imports a document and applies preprocessing to ensure it can properly be loaded and edited by the editor. Use this method if you need to import legacy content or content created using Microsoft Office products.

Parameters:
Name Type Argument Description
content String The document as an HTML string.
baseUrl String optional
 The base URL for the document.
See:
Example:
doc = "<html><head><title></title></head>";
doc += "<body><p><o:p></o:p>test</p></body></html>";
editor.importLegacyDocument(doc);
importLegacyDocumentFromUrl(url, baseUrl)async

Imports a document from an URL and applies preprocessing to ensure it can properly be loaded and edited by the editor. Use this method if you need to import legacy content or content created using Microsoft Office products.

Parameters:
Name Type Argument Description
url String The URL to load.
baseUrl String optional
 The base URL for the document.
See:
insertContent(content, applyInlineFormats, silent)async
Inserts HTML content at the caret position.
Parameters:
Name Type Description
content String The content to be inserted
applyInlineFormats String Whether or not to apply the inline formats at the caret position to the imported content.
silent Boolean If set to true, no overlay and no busy indicator will be displayed. This should only be enabled if small and simple content snippets are inserted.
Example:
editor.insertContent("<p>Some content</p>");
insertContentFromUrl(url, applyInlineFormats)async

Inserts HTML retrieved from a URL at the caret position.

Only document fragments should be inserted using this method. Use either NimbudocsEditor#loadDocument or NimbudocsEditor#loadDocumentFromUrl to load entire documents.

Parameters:
Name Type Description
url String The URL to insert
applyInlineFormats String Whether or not to apply the inline formats at the caret position to the imported content.
Example:
editor.insertContentFromUrl("http://www.myserver.com/index.html");
invokeAction(actionId, argument, event)async
Invokes the action with the ID actionId and the argument argument. For details about possible argument for any given action, please see the Action Reference guide.
Parameters:
Name Type Argument Description
actionId String The ID of the action.
argument String optional
 The argument for the action.
event Event optional
 An optional HTML DOM Event object.
Guides:
  • Tutorial: Action Reference
Example:
editor.invokeAction("align", "center");
editor.invokeAction("bold");
isActionEnabled(actionID)Booleanasync

Returns whether the action with the ID actionId is enabled in the context at the caret position.

For example, if the caret is placed in a read-only section, some actions may become unavailable. Others may not be available due to restrictions imposed on them.

Parameters:
Name Type Description
actionID Object
Returns:
  • Boolean
Example:
editor.isActionEnabled("bold").then(function(val) {
    var actionEnabled = val;
});
leave()
Leaves the editor.
loadDocument(content, baseUrl)async

Loads a document into the editor from an HTML string.

Parameters:
Name Type Argument Description
content String The document to load.
baseUrl String optional
 The base URL for the document.
See:
Example:
var document = "<html><head><title>Sample Document</title></head>";
document +=    "<body><p>Sammple Content</p></body></html>";
editor.loadDocument(document);
editor.loadDocument(document, "http://resources");
loadDocumentFromUrl(url, baseUrl)async

Loads a document into the editor from the given URL.

Parameters:
Name Type Argument Description
url String The URL to load
baseUrl String optional
 The base URL for the document.
See:
Example:
editor.loadDocumentFromUrl("http://www.realobjects.com");
editor.loadDocumentFromUrl("http://pageserver", "http://resources");
loadDocumentXsltFromContent(document, xsltStyleSheets, baseUrl)async

Loads a XML document from an String and applies an XSL transformation. If a XSL style sheet is referenced within the document, it is applied. Additional XSL style sheet can be loaded via the xsltStyleSheets parameter.

Parameters:
Name Type Argument Description
document String The document to load
xsltStyleSheets Array.<String> optional
 An array of URLs of XSLT style sheets that should be applied.
baseUrl String optional
 The base URL relative resources are resolved again.
See:
loadDocumentXsltFromUrl(url, xsltStyleSheets, baseUrl)async

Loads a XML document from an URL and applies an XSL transformation. If a XSL style sheet is referenced within the document, it is applied. Additional XSL style sheet can be loaded via the xsltStyleSheets parameter.

Parameters:
Name Type Argument Description
url String The URL to load
xsltStyleSheets Array.<String> optional
 An array of URLs of XSLT style sheets that should be applied.
baseUrl String optional
 The base URL relative resources are resolved again. (sUrl is used instead if sBaseUrl is empty or null).
See:
Example:
editor.loadXsltDocumentFromUrl("http://www.realobjects.com");
editor.loadXsltDocumentFromUrl("http://pageserver", "http://resources");
localize(localeCode)String
Resolves the given locale code in the editor's language.
Parameters:
Name Type Description
localeCode String The locale code to resolve.
Returns:
  • String
The localized string.
lock(overlayType, loadingIndicatorType)async

Locks the user interface of the editor. When locked, no interactivity with the editor is possible.

This enables the integration of custom modal dialogs.

Additionally a loading indicator can be shown (optional).

Parameters:
Name Type Argument Description
overlayType String optional
 The type of the overlay. Can be "opaque" or "transparent". Defaults to "opaque" if ommited.
loadingIndicatorType String optional
 The type of the loading indicator to show. Can be "none" (default, if ommited), "progress" for a progress bar, "busy" for a busy indicator (displayed as a specific mouse cursor type) or "progress-busy" for a combination of progress and busy indicator.
Example:
editor.lock();
editor.lock("transparent", "busy");
editor.lock("opaque", "progress-busy");
moveCaret(expression, end, global)Booleanasync

Moves the caret to the first element (in DOM order) matching the specified XPath expression.

Parameters:
Name Type Argument Default Description
expression String The XPath expression.
end Boolean optional
 Whether to place the caret at the end of the element instead of at the start.
global Boolean optional
 false Whether to apply the XPath expression to the entire document instead of restricting it to the current selection.
Returns:
  • Boolean
Whether one or more matching elements have been found.
Example:
editor.moveCaret("//p");
moveCaretToDocumentEnd()async
Moves the caret to the end of the document.
Example:
editor.moveCaretToDocumentEnd();
moveCaretToDocumentStart()async
Moves the caret to the start of the document.
Example:
editor.moveCaretToDocumentStart();
moveCaretToNextBlock()async
Moves the caret to the next block
Example:
editor.moveCaretToNextBlock();
moveCaretToNextPage()async
Moves the caret to the next page
Example:
editor.moveCaretToNextPage();
moveCaretToPreviousBlock()async
Moves the caret to the previous block
Example:
editor.moveCaretToPreviousBlock();
moveCaretToPreviousPage()async
Moves the caret to the previous page
Example:
editor.moveCaretToPreviousPage();
moveToBookmark()async
Selects the bookmark with the specified name.
Example:
editor.moveToBookmark("chapter1");
moveToNextBookmark()async
Selects the next bookmark.
Example:
editor.moveToNextBookmark();
moveToPreviousBookmark()async
Selects the previous bookmark.
Example:
editor.moveToPreviousBookmark();
promoteUser(identifier, level, {Boolean])async
Promotes an user in an existing collaboration session. By default users have the "Reader" permission. "Reviewers" can insert annotations. The "Author" has control over the document, only one author at any given time possible. Also allows to change the "Organizer" role. Only the organizer can promote users, only one user can be organizer.
Parameters:
Name Type Description
identifier String The "identifier" (user name) of the user, which should be promoted.
level Integer The level the user should be promoted to (0 = Reader, 2 = Author)
{Boolean] organizer If the user should be promoted as new organizer.
remove(expression, global)Booleanasync

Remove the element(s) matching the specified XPath expression.

Parameters:
Name Type Argument Default Description
expression String The XPath expression.
global Boolean optional
 false Whether to apply the XPath expression to the entire document instead of restricting it to the current selection.
Returns:
  • Boolean
Whether one or more matching elements have been removed.
Example:
editor.select("//p");
removeAuthorStyleSheet(title)async
Removes the author style sheet with the specified title.
Parameters:
Name Type Description
title String The title of the author style sheet to remove.
See:
Example:
editor.removeAuthorStyleSheet("headings");
removeCurrentTableColumnCellAttributes()async
Removes all attributes of all cells of the table column at the caret position.
Example:
editor.removeCurrentTableColumnCellAttributes()
removeCurrentTableRowCellAttributes()async
Removes all attributes of all cells of the table row at the caret position.
Example:
editor.removeCurrentTableRowCellAttributes();
removeDocumentStyleSheet(title)async
Removes the document style sheet with the specified title.
Parameters:
Name Type Description
title String The title of the document style sheet to remove.
See:
Example:
editor.removeDocumentStyleSheet("headings");
removeEditorStyleSheet(title)async
Removes the editor style sheet with the specified title.
Parameters:
Name Type Description
title String The title of the editor style sheet to remove.
See:
Example:
editor.removeEditorStyleSheet("headings");
removeEventListener(The)

Removes the specified event listener.

Parameters:
Name Type Description
The NimbudocsEditor.EventListener event listener to remove..
See:
Example:
// add a listener to every paragraph of the document
var paraListener = editor.addEventListener("p", "mouseup", function(e) {
    //...
});

// Remove the listener we just added
editor.removeEventListener(paraListener);
removeParentElementByNameAttributes(ancestorName)async
Removes all attributes of the first parent element with the name ancestorName found starting from the caret position.
Parameters:
Name Type Description
ancestorName String The name of the ancestor to be processed.
Example:
editor.removeParentElementByNameAttributes("div");
requestFocus()async

Requests focus on the editor.

select(expression, global)Booleanasync

Selects first element matching the specified XPath expression.

Parameters:
Name Type Argument Default Description
expression String The XPath expression.
global Boolean optional
 false Whether to apply the XPath expression to the entire document instead of restricting it to the current selection.
Returns:
  • Boolean
Whether one or more matching elements have been found.
Example:
editor.select("//p");
setBlockElementAttributes(attributes)async
Sets the attributes of the block level element at the caret position (e.g. "<p>" or "<div>").
Parameters:
Name Type Description
attributes Object An object containing key/value pairs of the attribute names and values.
See:
Example:
// Adding an attribute or changing the value of an existing attribute
attr = { "style": "color: red;" };
editor.setBlockElementAttributes(attr);
// Removing an attribute
attr = { "style": null };
editor.setBlockElementAttributes(attr);
setBodyFragment(content)async
Sets the content of the <body> element.
Parameters:
Name Type Description
content String The content to be set.
See:
Example:
editor.setBodyFragment("<p>Some content</p>");
setContentChanged()async
Sets the contentChanged property of the editor. Set this to false when a the document is saved so you can verify whether the document was modified since the last time it was saved.
See:
Example:
editor.setContentChanged(false);
setCurrentElementContent(content)async
Sets the content of the element at the caret position.
Parameters:
Name Type Description
content String The content to be set
Example:
editor.setCurrentElementContent("Some content");
setCurrentTableColumnCellAttributes(attributes)async
Sets the attributes of all cells in the table column at the caret position. All cells in the column must be represented in the object passed to the editor.
Parameters:
Name Type Description
attributes Object The attributes object
See:
Example:
//Define the attributes and attribute values as key / value pairs.

var redCell = {"bgcolor": "red", "width": "600"};
var greenCell = {"bgcolor": "green", "width": "600"};
var noChange = null; 

// Create an array of cells, each of the elements in the array represents
// a single cell and consists of an object containing the attributes and 
// attribute values to set for this cell as key/value pairs.

var cells = [ redCell, greenCell, noChange ];

// Set the attributes for the cells in the table column at the caret position.
editor.setCurrentTableColumnCellAttributes(cells);
setCurrentTableRowCellAttributes(attributes)async
Sets the attributes of all cells in the table row at the caret position. All cells in the row must be represented in the object passed to the editor.
Parameters:
Name Type Description
attributes Object The attributes object
See:
Example:
// Define the attributes and attribute values as key / value pairs.

var redCell = {"bgcolor": "red", "width": "600"};
var greenCell = {"bgcolor": "green", "width": "600"};
var noChange = null; 
var removeColor = {"bgcolor": null};

// Create an array of cells, each of the elements in the array represents
// a single cell and consists of an object containing the attributes and 
// attribute values to set for this cell as key/value pairs.

var cells = [ redCell, greenCell, noChange, removeColor ];

// Set the attributes for the cells in the table row at the caret position.

editor.setCurrentTableRowCellAttributes(cells);
setDocumentBaseUrl(baseUrl)async
Sets the base URL for the current document.
Parameters:
Name Type Description
baseUrl String The base URL to be set.
See:
setDocumentName(documentName)async
Sets the document name for the current document.
Parameters:
Name Type Description
documentName String The document name to be set.
See:
setElementAttributes(attributes)async
Sets the attributes of the element at the caret position. If the value of an attribute is set to null or if it is omitted from the attributes object, it is removed from the element. It is recommended to call NimbudocsEditor#fetchElementAttributes and to modify the returned object before passing it to NimbudocsEditor#setElementAttributes.
Parameters:
Name Type Description
attributes Object The attributes to be set
Example:
// Adding an attribute or changing the value of an existing attribute
attr = { "style": "color: red;" };
editor.setElementAttributes(attr);
// Removing an attribute
attr = { "style": null }; // or attr = {};
editor.setElementAttributes(attr);
setElementListAttributes(expression, attributes)async
Sets the attributes of all elements matching the specified XPath expression. The elements are retrieved in DOM order. Ommitting attributes will remove them from the elements that previously had those attributes. It is recommended to use NimbudocsEditor#fetchElementListAttributes and manipulate the attributes in the resulting object array.
Parameters:
Name Type Description
expression String The XPath expression selecting the elements to modify.
attributes Array.<Object> | Object If an Array is passed as argument: an array of objects containing key / value pairs representing the attributes and and attribute values of each element matching the expression. If an Object is passed as argument: an object containing key / value pairs representing the attributes and attributes values for all elements matching the expression. Attributes ommitted, will be removed if present on the matched elements.
Examples:
var attributeObject = [
    { "style": "color: red" },
    { "class": "paragraph" },
    null,
    { "style": "color: red", "class": "paragraph" }
];
 
var expression = "//p";

// Add or modify the "style" attribute of the first matching "p" element,
// add or modify the "class" attribute of the second matching element, 
// do not modify the third matching element, 
// and set the "style" and "class" attribute for the fourth matching element. 
editor.setElementListAttributes(expression, attributeObject);
var attributeObject = { "class": "paragraph" };
var expression = "//p";

// Set the "class" attribute with value "paragraph" for all matching elements.
editor.setElementListAttributes(expression, attributeObject);
setElementListStyles(expression, styles)async
Sets the styles of all elements matching the specified XPath expression. The elements are retrieved in DOM order.
Parameters:
Name Type Description
expression String The XPath expression selecting the elements to modify.
styles Array.<Object> | Object If an Array is passed as argument: an array of objects containing key / value pairs representing the style properties and values of each element matching the expression. If an Object is passed as argument: an object containing key / value pairs representing the style properties and values for all elements matching the expression.
Examples:
var styleObject = [
    { "color": "red" },
    { "font-size": "12pt" },
    null,
    { "color": "red", "font-size": "12pt" }
];
 
var expression = "//p";
 
// Apply "color: red" to the first "p" element found, "font-size: 12pt" to the second
// one, do not modify the third one and apply "color: red" and "font-size: 12pt" to the 
// fourth.  
editor.setElementListStyles(expression, styleObject);
var styleObject = { "color": "red" };
var expression = "//p";

// Apply "color: red" to all "p" elements
editor.setElementListStyles(expression, styleObject);
setHeadElementContent(content)async
Sets the content of the <head> element of the document. This overwrites any existing content of this element.
Parameters:
Name Type Description
content String The content
See:
Example:
editor.setHeadElementContent("<title>New Document Title</title>");
setHeight(height)async
Sets the height of the editor.
Parameters:
Name Type Description
height String | Number The height either as a string including a unit or as a number. If set as a number, the value will be applied in pixels.
See:
setHideOverlayFlag()async

Sets a flag which causes the overlay/loading indicator to be removed on the next update from the server.

setIgnoreReadOnly(ignoreReadOnly)async
Toggles whether or not API methods can be used in sections or elements that are not editable (i.e. that have "-ro-editable: false" or "-ro-editable-inside: false".
Parameters:
Name Type Description
ignoreReadOnly Boolean If set to true, API methods can be used within sections and elements that are not elements.
setPageProperties(properties)async
Parameters:
Name Type Description
properties Object The properties object.
See:
Example:
editor.fetchPageProperties().then(function(properties) {
    //manipulate properties as needed
    editor.setPageProperties(properties);
});

// Example contents of pageProperties:
// 
// pageProperties = {
//     "default-page-properties": {
//         "width": "21",
//         "height":"29.7"
//         "page-size-unit": "cm",
//         "margin-left": "2.5",
//         "margin-left-unit": "cm",
//         "margin-top": "2.5",
//         "margin-top-unit": "cm",
//         "margin-bottom": "2.5",
//         "margin-bottom-unit": "cm",
//         "margin-right": "2.5",
//         "margin-right-unit": "cm"
//     },
//     "first-page-properties": {
//         ... (see above)
//     },
//     "default-page-hf-properties": {
//         "top-center":{
//             "xhtml-content": "..."
//         },
//         "bottom-center":{
//             "xhtml-content": "..."
//         },
//     },
//     "first-page-hf-properties": {
//         ... (see above)
//     },
//     "left-page-hf-properties": {
//         ... (see above)
//     },
//     "right-page-hf-properties": {
//         ... (see above)
//     },
//     "mirror": false
// }

To remove "first-page-properties", "default-page-hf-properties", "first-page-hf-properties", 
"left-page-hf-properties", "right-page-hf-properties" or a specific "top-center"/"bottom-center" set it's value to "null" (String).
setParentElementByNameAttributes(ancestorName, attributes)async
Sets the attributes of the nearest ancestor of the element at the caret position with the node name ancestorName.
Parameters:
Name Type Description
ancestorName String The node name of the ancestor element
attributes Object The attribute names and values to set as key/value pairs.
Example:
// Adding an attribute or changing the value of an existing attribute
attr = { "style": "color: red;" };
editor.setParentElementByNameAttributes("div", attr);
// Removing an attribute
attr = { "style": null };
editor.setParentElementByNameAttributes("div", attr);
setParentElementByNameContent(ancestorName, content)async
Sets the HTML content of the nearest ancestor of the element at the caret position with the node name ancestorName.
Parameters:
Name Type Description
ancestorName String The name of the ancestor element.
content String The HTML content to set.
Example:
editor.setParentElementByNameContent("div", "<p>new content</p>");
setPasteHandler(pasteHandler)async
Sets a paste handler that receives the pasted content as a String before it is passed to the editor. The function passed to setPasteHandler() must return a String.
Parameters:
Name Type Description
pasteHandler Function The function that will receive the pasted content as a {String}.
setSelectedColumnsCellAttributes(attributes)async

Sets the attributes of all cells in the currently selected columns as a nested object. The object contains the selected columns on the first level. Each column in turn contains its cells, which contain its attributes and and attribute values as key/value pairs.

To easily obtain such an object that can be manipulated and passed to this method as an argument, it is recommended to use NimbudocsEditor#fetchSelectedColumnsCellAttributes.

Parameters:
Name Type Description
attributes Object The attributes object.
See:
Example:
editor.fetchSelectedColumnsCellAttributes().then(function(attributes) {
    // manipulate attributes as needed
    editor.setSelectedColumnsCellAttributes(attributes);
});
setSelectedRowsCellAttributes(attributes)async

Sets the attributes of all cells in the currently selected rows as a nested object. The object contains the selected columns on the first level. Each row in turn contains its cells, which contain its attributes and and attribute values as key/value pairs.

To easily obtain such an object that can be manipulated and passed to this method as an argument, it is recommended to use NimbudocsEditor#fetchSelectedRowsCellAttributes.

Parameters:
Name Type Description
attributes Object The attributes object.
See:
Example:
editor.fetchSelectedRowsCellAttributes().then(function(attributes) {
    //manipulate obj as needed
    editor.setSelectedRowsCellAttributes(attributes);
});
setSelectionColor(red, green, blue, alpha)Booleanasync
Sets the RGBA color of the selection overlay. The default color is rgba(0,128,255,0.2).
Parameters:
Name Type Description
red Integer An integer value between 0 and 255
green Integer An integer value between 0 and 255
blue Integer An integer value between 0 and 255
alpha Float A float value between 0.0 (invisible) and 1.0 (no transparency)
Returns:
  • Boolean
true if the values of the new color were valid.
Example:
editor.setSelectionColor(0,64,192,0.15);
setWidth(width)async
Sets the width of the editor.
Parameters:
Name Type Description
width String | Number The width either as a string including a unit or as a number. If set as a number, the value will be applied in pixels.
See:
showInfoBox(title, content, callback, hideButtons)
Shows a modal info box. If the hideButtons option is false or omitted the callback specified will be called with a boolean argument depending which button was clicked (OK -> true, Cancel -> false). If the hideButtons option is true the callback will be called without argument, when clicking the close icon in the upper right corner.
Parameters:
Name Type Description
title String The title of the info box
content content The content of the info box
callback Function A function which is called when closing the info box
hideButtons Boolean Whether the "Cancel" and "OK" buttons will be displayed
showStatusMessage(args)
Shows a message in the status message widget.
Parameters:
Name Type Description
args String | Object Either a string with the status message to display (using the default settings: autoHide: false, timeout: 5000, closeonclick: true, type: default), or an object containing the text and additional configuration parameters.
Properties
Name Type Argument Description
text String optional
 The text to display.
autoHide Boolean optional
 Whether the message widget should be hidden automatically.
timeout Number optional
 The timeout after which the message widget should be hidden.
closeonclick Boolean optional
 Whether the message widget should be hidden on click.
type String optional
 The type of the message, can be one of "default", "warn" or "error".
toggleFullscreen()async
Toggles the fullscreen mode. This mode uses the HTML5 fullscreen API, if available in the browser.
toggleMaximize()async
Toggles the maximize mode. In this mode the editor occupies the entire browser window.
toggleSidebar()async
Toggles the sidebar.
transferSession(identifier)Stringasync
Starts transferring of a session to a new editor instance in another window/tab. If no identifier is specified, the session is transferred to the first client "joining" the session. Returns the ID to use as options.collabId in the new window/tab.
Parameters:
Name Type Description
identifier String The "identifier" of the new client the session should be transfered to (set by the option options.userName in the new window/tab)
Returns:
  • String
unlock()async

Unlocks the user interface of the editor by removing the overlay and optional loading indicator

Example:
editor.unlock();
updateUIConfig(uiconfig)async
Updates the uiconfig and refreshes the tool bar.
Parameters:
Name Type Description
uiconfig Object The new uiconfig content as a {String}.

Events

actioninvoke
This event is fired each time when an action is invoked.
Listeners of This Event:
caretPageChange
This event is fired when the caret is placed on a different page.

Use the document keyword as selector for this event.

Listeners of This Event:
dictionaryChange
This event is fired when a dictionary was changed e.g. by adding a new word.

Use the document keyword as selector for this event.

Listeners of This Event:
mousedown
The JavaScript "mousedown" event.
Listeners of This Event:
mouseenter
The jQuery "mouseenter" event.
Listeners of This Event:
mouseleave
The jQuery "mouseleave" event.
Listeners of This Event:
mousemove

The JavaScript "mousemove" event.

Please note that this event is fired with a significantly higher frequency than any of the other events, which means that complex logic in event listeners for this event may negatively impact performance.

Listeners of This Event:
mouseout
The JavaScript "mouseout" event.
Listeners of This Event:
mouseover
The JavaScript "mouseover" event.
Listeners of This Event:
mouseup
The JavaScript "mouseup" event.
Listeners of This Event:
pageCountChange
This event is fired when the number of pages of a document changes.

Use the document keyword as selector for this event.

Listeners of This Event: