RealObjects Nimbudocs Editor 3.0.3929_Beta1

Namespace: options


options

The options object used in the NimbudocsEditor.create method.

Properties

actionMapString|Object

Specifies the action map. Either accepts an object, JSON string or a URL. If this is not set, the default action map is used.

It is generally recommended to use options.actionMapExtension instead.

Type:
  • String | Object
Guides:
actionMapExtensionString|Object|Array
Specifies extensions to the action map. Either accepts an object, a JSON string, a URL string or an array of any of these. Existing properties are overridden.
Type:
  • String | Object | Array
Default Value:
  • {}
Guides:
allowDefaultColorsBoolean
Whether to display the default colors in color dialogs.
Type:
  • Boolean
Default Value:
  • true
allowFreeColorsBoolean
Whether to display color pickers in color dialogs.
Type:
  • Boolean
Default Value:
  • true
allowPresetColorsBoolean
Whether to display preset colors in color dialogs.
Type:
  • Boolean
Default Value:
  • true
See:
apiKeyString
Set the API key to authenticate the client with the server.
Type:
  • String
authenticationCredentialsObject
An object to specify basic authentication credentials which are set on connections made from the Nimbudocs Editor server (e.g. to load documents or resources like images or CSS files).
Type:
  • Object
Properties:
Name Type Argument Description
username String optional
The user name
password String optional
The password
Default Value:
  • {}
Example:
authenticationCredentials: {
    username: "myuser",
    password: "mypassword"
}
autoCorrectObject
Enables and configures the auto correction functionality and behavior.
Type:
  • Object
Properties:
Name Type Argument Default Description
enabled Boolean optional
false Whether auto correction is enabled or not.
correctors Object optional
{}
Properties
Name Type Argument Default Description
autoHyperlinking Boolean optional
false Whether hyperlinks are automatically created.
sentenceStartUpperCase Boolean optional
false Whether to start a new sentence with an upper cased word. Can also be set to "latinOnly", so that the word is only corrected if it starts with a latin letter.
cellStartUpperCase Boolean optional
false Whether to start a cell with an upper cased word.
expressionReplacer Boolean optional
false Whether to enable the automatic replacement of expressions (see presetCorrections).
wordStartCapsLock Boolean optional
false Whether to correct two upper cased letters at the beginnings of words.
presetCorrections Object optional
{} An object containing expression replacements for various languages.
Default Value:
  • {}
Example:
var options = {
    autoCorrect: {
        enabled: true,
        correctors: {
            autoHyperlinking: true,
            sentenceStartUpperCase: true,
            cellStartUpperCase: true,
            expressionReplacer: true,
            wordStartCapsLock: true 
        },
        presetCorrections: {
            "": { // the empty string represents 
                  // language independent replacements
                "(r)": "\u00AE",
                "(c)": "\u00A9",
                "(tm)": "\u2122",
                ":-)": "\u263A",
                "-->": "\u2192",
                "<--": "\u2190",
                "<->": "\u2194"
            },
            "en-US": {
                "i.e.": "that is",
                "e.g.": "for example" 
            },
            "de-DE": {
                "d.h.": "das heißt",
                "evtl.": "eventuell" 
            },
            "fr-FR": {
                "s.o.": "sans objet",
                "n.a.": "non applicable",
                "p.": "page" 
            }
        }
    }
};
clipboardInteger
Clipboard configuration options
Type:
  • Integer
Properties:
Name Type Argument Description
maxSize Number optional
Maximum size (in bytes) a selection can have to be transfered to the client automatically.
Default Value:
  • {maxSize: 1000000}
collabIdString
Specifies the ID of an editor session in collaboration mode that will be joined. If the ID is set the boolean value false, the editor will ignore collab IDs that have been with a URL parameter.
Type:
  • String
collabPasswordString
Specifies the password of the collaboration session that will be joined.
Type:
  • String
Default Value:
  • null
collabUrlString
Specifies the URL to the collaboration page where users can join the current editing session for collaboration.
Type:
  • String
Default Value:
  • null
containerElementsArray.<String>
Declares the specified elements as container elements. Container elements behave differently from other block level elements in that they can contain other block level elements (such as "p") and are not split when pressing the enter key while the caret is inside the element. Instead, a default paragraph element is inserted within the element when the enter key is pressed. Some of the elements that behave as container elements by default in the editor are "div" and "form".
Type:
  • Array.<String>
Default Value:
  • []
Example:
var elementName = [
    "element1",
    "element2"
];
cookiesObject
An object containing key/value pairs of cookies to be set on connections made from the Nimbudocs Editor server (e.g. to load documents or resources like images or CSS files).
Type:
  • Object
Default Value:
  • {}
Example:
cookies: {
    "cookie1Name": "cookie1Value",
    "cookie2Name": "cookie2Value"
}
dateObject
Configures various date properties.
Type:
  • Object
Properties:
Name Type Argument Default Description
format String optional
null This string defines the pattern of dates that are shown in the editor. The pattern is based on the java class SimpleDateFormat (http://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html)
locale String optional
This language code is used for localized date formats, e.g. the code "en-US" would make the weekdays to appear in English. By default, the language is defined by the server and its environment.
timezone String optional
Displayed dates will be converted to this time zone. By default, the time zone is defined by the client's browser.
Default Value:
  • null
defaultBaseUrlString
Specifies a default base URL for any documents that is used if no document base URL is supplied.
Type:
  • String
defaultLengthUnitString
Configures the default length unit that is used to display certain values, e.g. when resizing an image. Supported units are cm, mm, in, pt and pc.
Type:
  • String
Default Value:
  • "cm"
disableDefaultFontsBoolean
Whether a set of default fonts should be usable in the document and displayed in the font drop down.
Type:
  • Boolean
Default Value:
  • false
documentString
Loads a document into the editor from an HTML string. This option saves the request which would be made when using the loadDocument API method after initializing the editor (only when the retriever is not enabled).
Type:
  • String
See:
documentUrlString
Loads a document into the editor from a URL. This option saves the request which would be made when using the loadDocumentFromUrl API method after initializing the editor (only when the retriever is not enabled).
Type:
  • String
See:
editorStyleSheetsArray.<Object>
Allows to set editor styles which will be loaded while initializing the editor. This option saves the request(s) which would be made when using the adEditorStyleSheet API method after initializing the editor (only when the retriever is not enabled).
Type:
  • Array.<Object>
Default Value:
  • []
formValidationString
The form validation mode. Can be "ontype", "oncaretelementchange" or "".
Type:
  • String
headerFooterEditorConfigurationObject
A Nimbudocs Editor configuration object which is set on the internal Header/Footer editor. Some configuration values in this object are overridden by default values: - The "pageMode" will always be set to "continuous" - The "collabId" is set to "false" - The "retriever" setting will be inherited from the "parent" editor configuration - The "onready" callback will only be called after an internal default "onready" callback
Type:
  • Object
Default Value:
  • undefined
heightString|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.
Type:
  • String | Number
Default Value:
  • null
See:
imageMaxSizeInteger
Maximum size (width and height) for images. Exceeding sizes will be scaled down when sending the image to the client. The image in the source document will not be modified.
Type:
  • Integer
Default Value:
  • 1000
imageMinSizeInteger
Minimum size (width and height) at which non-raster images (e.g. SVGs) will be rendered.
Type:
  • Integer
Default Value:
  • 100
imageScaleFactorInteger
Scale factor at which non-raster images (e.g. SVGs) are rendered.
Type:
  • Integer
Default Value:
  • 3
loadBalancerCookieObject
When using a load balancer, this specifies the name and value of the load balancer's cookie.
Type:
  • Object
Properties:
Name Type Argument Default Description
name String The name of the load balancer's cookie. This defaults to the cookie name of the Amazon Web Services Elastic Load Balancer.
value String optional
"" The value of the load balancer's cookie.
Default Value:
  • {name: "AWSELB"}
localeString|Array.<String>|Object
Set the locale of the editor. Use a string to force a specific locale. The array option sets an array of allowed locales. The detected browser locale is then matched against this array to determine the editors locale. Using the object configuration you can configure the above and additionally a fall back language which should be used if there is no localization for the current locale.
Type:
  • String | Array.<String> | Object
Properties:
Name Type Description
{String|String[]) [supportedLocales] The supported locale(s) as a String or String array. Same as the non-object configuration.
{String) [fallbackLanguage] The fall back language
Default Value:
  • ["en-US", "de-DE", "fr-FR"]
Example:
locale: {
    supportedLocales: ["en-US", "de-DE"],
    fallbackLanguage: "fr-FR"
} 
localeExtensionObject
Specifies extensions to a localization dictionary for a specific language.
Type:
  • Object
Properties:
Name Type Argument Default Description
localeCode String The language code for which the extension is applied.
strings String | Object | Array optional
{} Either an object consisting of pairs of locale codes and value strings or URL to a JSON of such an object or an array of any of these.
Default Value:
  • {}
Guides:
Example:
var localeExtension = {
    "en-US": {
        "MY_CODE": "my description"
    },
    "de-DE": {
        "MY_CODE": "meine Beschreibung"
    }
};
logLevelString
Configures the log level. Supported log levels are: SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST, ALL
Type:
  • String
Default Value:
  • "INFO"
objectFormatterObject
Type:
  • Object
Properties:
Name Type Argument Default Description
backgroundColor String optional
Sets the background color of the object rectangle as Hex color value. Defaults to #EBEAEA
borderColor String optional
Sets the border color of the object rectangle as Hex color value. Defaults to #222222.
borderWidth Integer optional
Sets the border width of the object rectangle integer value. Defaults to 1.
displayDefaultImage Boolean optional
true If set to true and the object element type is unknown/not configured, display a default image in the center of the object rectangle. Defaults to true.
defaultImageUrl String optional
The URL to the image which should be displayed as default image.
objectTypes Array.<Object> optional
[] Specifies an array of object types and their corresponding images to be displayed at the center of the object rectangle.
Default Value:
  • {}
Example:
var options = {
    objectFormatter: {
        backgroundColor: "#FF0000",
        borderColor: "#00FF00",
        borderWidth: 50,
        displayDefaultImage: true,
        defaultImageUrl: "http://host.com/mydefaultimage.png",
        objectTypes: [
            {
                type: "application/x-shockwave-flash",
                imageUrl: "http://host.com/flash.png"
            },
            {
                type: "audio/x-mpeg",
                imageUrl: "http://host.com/mp3.png"
            }
        ]
    }
}
offlineEnablerboolean
Use a local server for editing if available. Please note for IE: If the domain of the page integrating the editor is a FQDN (e.g. has a top level domain) while the Nimbudocs Editor server does not, Internet Explorer will not allow the CORS requests unless the integrating domain is added to its trusted sites.
Type:
  • boolean
Default Value:
  • false
overlayAndIndicatorObject
Configures the splash-screen behavior of Nimbudocs Editor. By default a cloud background and a loading indicator is displayed during startup of the editor. Set to false to disable background and indicator.
Type:
  • Object
Properties:
Name Type Argument Description
overlayAlwaysTransparent Boolean optional
Normally the overlay will be black with an opacity of 0.4. Set this to true so that the overlay will always be transparent.
alwaysHideIndicator Boolean optional
Set to true to never show the loading indicator.
overlayColor String optional
Set the color of the overlay (CSS color value e.g. #00000, rgb(0,0,0), ...)
overlayOpacity String optional
Set the opacity of the overlay (0-1)
Default Value:
  • {}
pageModeString
The page mode on editor start. Can be either "singlesided" or "continuous".
Type:
  • String
Default Value:
  • "singlesided"
presetColorsObject
An object containing key/value pairs of color names and their RGB value.
Type:
  • Object
Default Value:
  • {}
See:
Example:
var options = {
    presetColors: {
        Crimson: "#DC143C",
        "Dark olive green": "#556B2F",
        "F0FFF0": "#F0FFF0",
    }
};
requestHeadersObject
An object containing key/value pairs of request headers to be set on connections made from the Nimbudocs Editor server (e.g. to load documents or resources like images or CSS files).
Type:
  • Object
Default Value:
  • {}
Example:
requestHeaders: {
    "MyHeader": "MyHeaderValue",
    "MyHeader2": "MyHeaderValue"
}
retrieverObject
If resources are on an internal network and can not be accessed from the Nimbudocs Editor server, the retriever can be enabled. If enabled, resources are loaded by the client, who has access to them, and are then sent to the Nimbudocs Server.
Type:
  • Object
Properties:
Name Type Argument Description
enabled Boolean optional
Enables / disables the retriever.
timeout Number optional
Sets the time in seconds, that the client has to retrieve a resource. The higher the value, the longer the editor will wait for a resource, "blocking" the editor. If the value is too low on the other hand, a resource might not be loaded in time, meaning that it can not be used by the editor. If the value is zero or less, the default time (set on the server) is used, e.g. 30 seconds.
Default Value:
  • {enabled: false, timeout: 0}
selectionColorArray.<Number>
An RGBA-array defining the default color of the selection. The first three entries are numbers between 0 and 255 for red, green and blue. The last entry is a number between 0.0 and 1.0 for the alpha channel, where 0 is completely transparent.
Type:
  • Array.<Number>
Default Value:
  • [0, 128, 255, 0.2]
spellCheckerObject
Configuration for the spell checker.
Type:
  • Object
Properties:
Name Type Argument Default Description
autoCheck Boolean optional
false Whether auto spell check is enabled or not.
Default Value:
  • {autoCheck: false}
splashScreenBoolean|Object
Configures the splash-screen behavior of Nimbudocs Editor. By default a cloud background and a loading indicator is displayed during startup of the editor. Set to false to disable background and indicator.
Type:
  • Boolean | Object
Properties:
Name Type Argument Description
background Boolean | String optional
Set to false (Boolean) to disable the background or specify an URL (String) to a background image (resolved relative to the integration base).
indicator Boolean | String optional
Set to false (Boolean) to disable the indicator or specify an URL (String) to an indicator image (resolved relative to the integration base).
Default Value:
  • {}
tableConfigObject
An object defining configuration options specific to tables.
Type:
  • Object
Properties:
Name Type Argument Description
defaultWidthUnit String optional
The default with unit used when adjusting the table width.
defaultHeightUnit String optional
The default height unit used when adjusting the table width.
Default Value:
  • {defaultWidthUnit: "cm", defaultHeightUnit: "cm"}
themeObject
The theme options.
Type:
  • Object
Properties:
Name Type Argument Default Description
name String optional
"default" The name of the theme. Use one of the included themes: "default", "nimbudocs-classic", "nimbudocs-blue", "cupertino", "redmond", "flick", "ui-lightness". If you have added your own theme to the Nimbudocs WAR file (inside a folder in "client/nimbuDocs/themes/") use the name of the folder.
url String optional
The Url to a jQuery theme CSS file. The Url has priority over the name property.
iconRepositoryUrl String optional
The URL to the icon repository to be used for icons of the tool bar. If omitted, a default icon repository on the application server is used.
useSpriteIcons booelan optional
Wether to use "sprite icons" (all icons are combined into a single image, access through CSS background position) for the tool bar. This is enabled by default. If an icon Url is configured for a specific action this will take precedence over the sprite icon.
spriteIconCssUrl String optional
The Url to a custom CSS sprite icon map. You can create a CSS and the corresponding sprite icon image using the "spriteicontool/spriteicons.jar" from the "nimbudocs-integration-resources.zip" available for download on the integration overview page. Please have a look at the separate readme contained in the "spriteicontool/" folder for more information.
Default Value:
  • null
toolbarObject
Type:
  • Object
Properties:
Name Type Argument Description
hidePanelDescription Boolean optional
Whether to hide the tool bar panel description.
hideSingleTabs Boolean optional
Whether to hide the tab navigation bar of the tool bar when the UI only consists of one tab.
singleRow Object optional
Whether to display tool bar icons in a single row
Properties
Name Type Argument Description
enabled Boolean optional
Whether to enable the "single row" icon mode.
iconSize String optional
All icons will have the same size in single row mode. By default the size will be "mediumPanel". Can be one of "tinyPanel", "smallPanel", "mediumPanel" or "largePanel"
Default Value:
  • null
uiConfigString|Object

Specifies the UI config. Either accepts an object, a JSON string or a URL string.

If this is not set, the default uiconfig is used.

Type:
  • String | Object
userNameString
The user name.
Type:
  • String
userPreferencesObject
The user preferences.
Type:
  • Object
Properties:
Name Type Argument Description
loadurldialog String optional
The URL used in the "Load document from URL dialog".
autocorrect Object optional
The autocorrect preferences.
Properties
Name Type Argument Description
autoHyperlinking Boolean optional
Whether hyperlinks are automatically created.
sentenceStartUpperCase Boolean optional
Whether to start a new sentence with an upper cased word.
cellStartUpperCase Boolean optional
Whether to start a cell with an upper cased word.
expressionReplacer Boolean optional
Whether to enable the automatic replacement of expressions (see presetCorrections).
wordStartCapsLock Boolean optional
Whether to correct two upper cased letters at the beginnings of words.
customCorrections Array.<Object> optional
An array of custom correction objects.
Properties
Name Type Argument Description
expression String optional
The expression to replace.
language String optional
The language in which the expression should be replaced. Use "" for any language.
replacement String optional
The replacement value.
spellchecker-dictionary-personal Object optional
The personal dictionary for learned words.
Properties
Name Type Argument Description
$LANG_CODE Array.<String> optional
An array of words for the given language ($LANG_CODE could be e.g. "en-US").
Example:
var options = {
    "userpreferences": {
        "autocorrect": {
            "sentenceStartUpperCase":true,
            "cellStartUpperCase":true,
            "wordStartCapsLock":true,
            "autoHyperlinking":false,
            "expressionReplacer":true,
            "customCorrections": [
                {
                    "expression": "nd",
                    "language": "",
                    "replacement": "Nimbudocs Editor"
                },
                {
                    "expression": "pr",
                    "language": "",
                    "replacement": "PDFreactor"
                }
            ]
        },
        "spellchecker-dictionary-personal": {
            "en-US": ["Nimbudocs", "PDFreactor", "JSON"]
        },
        "loadurldialog": "http://www.nimbudocs.com"
    }
}
widgetsObject
The widgets used in the editor.
Type:
  • Object
See:
widthString|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.
Type:
  • String | Number
Default Value:
  • null
See:

Callbacks

oncaretdocumentboundary :function
The function called when the caret reaches the document start or end.
Type:
  • function
Passed Arguments:
Name Type Description
documentEnd Boolean Whether the event was triggered because the caret reached the end of the document.
Example:
var options = {
    oncaretdocumentboundary: function(documentEnd) {
        if(!documentEnd) {
             // Caret reached document start.
        } else {
             // Caret reached document end.
        }
    }
};
onconnectionstatechange :function
The function called when the connection state of the client changes.
Type:
  • function
Passed Arguments:
Name Type Description
stateObject Object The stateObject containing information about the connection state.
Properties
Name Type Description
connected Boolean Whether the client is connected or not.
status String Additional information about the state, can be "connected", "disconnected", "hibernate", "wakeup", "editor-session-server-hibernate" or "editor-session-server-resumed". The connected attribute is always true in case of "hibernate" and "wakeup".
This:
oncontentchange :function
The function called when the content of a document or the document itself changes.
Type:
  • function
Passed Arguments:
Name Type Description
changeObject Object An object containin information about the change
Properties
Name Type Description
documentLoaded Boolean Whether the change was caused by loading a (new) document.
contentChanged Boolean Whether there was a change in content.
See:
This:
ondocumentloaded :function
The function called when a document is loaded.
Type:
  • function
This:
onerror :function
The function called when an error occurs in the editor.
Type:
  • function
Passed Arguments:
Name Type Description
errorObject Object The errorObject containing information about the error.
Properties
Name Type Description
location String The location where the error occurred.
responseText String The error message.
statusCode String The status code.
statusText String The status message.
This:
Example:
var options = {
    onerror: function(errorObject) {
        console.log("Error at: " + errorObject.location);
        console.log("Message: " + errorObject.responseText);
        console.log("Code " + errorObject.statusCode + ": " + errorObject.statusText);
    }
};
onleave :function
The function called before the editor is left.
Type:
  • function
This:
onnotsupported :function
The function called if the browser is not supported and the editor could not be created.
Type:
  • function
onprepareservershutdown :function
The function called when the server is prepared to shutdown. Use this to save the content of the editor and notify the user.
Type:
  • function
This:
onready :function
The function called when the editor has finished initializing.
Type:
  • function
Passed Arguments:
Name Type Description
editor NimbudocsEditor The editor API object.
This:
Example:
var options = {
    onready: function(editor) {
        window.editor = editor;
        
        editor.addEditorStyleSheet({url: "styleTemplates.css"});
    }
};
onrecover :function
The function called when an internal server problem occurred which was handled by the server side recovery mechanism.
Type:
  • function
Passed Arguments:
Name Type Description
recoverObject Object The recoverObject containing information about the problem and what .
Properties
Name Type Description
undoStepText String A description of which action was undone to recover the editor.
errorMessage String A descriptive message of the error causing the recovery mechanism to step in.
stacktrace String The stack trace of the error.
This:
Example:
var options = {
    onrecover: function(recoverObject) {
        console.log("Error Message: " + recoverObject.errorMessage);
        console.log("Undo of: " + recoverObject.undoStepText);
    }
};
onselectionchange :function
The function called when the selection has been changed.
Type:
  • function
Passed Arguments:
Name Type Description
selectionText String The plain text of the current selection.
Example:
var options = {
    onselectionchange: function(selectedText) {
        
    }
};
onserveroffline :function
The function called when the server is not available.
Type:
  • function
This:
onsessionlimitreached :function
The function called when the concurrent editor session limit was reached.
Type:
  • function
Passed Arguments:
Name Type Description
sessionLimitObject Object The sessionLimitObject.
Properties
Name Type Description
message String A message containing a description.
retry Function A function to retry starting the editor.
This:
Example:
var options = {
    onsessionlimitreached: function(sessionLimitObject) {
        console.log("Message: " + sessionLimitObject.message);
        // Retry to start the editor
        sessionLimitObject.retry();
    }
};
onuserpreferenceschange :function
The function called when the user preferences change.
Type:
  • function
Passed Arguments:
Name Type Description
up Object The userpreferences as JSON
This: