COOL API Reference

COOL API

Initialization
General
Toolbar
Page oriented
Part oriented
Events
Object values
Uno commands

This reference reflects COOL master.

COOL

Initialization

Usage example


var map = L.map('map', {
    doc: 'file:///path/to/document',
    server: 'wss://localhost',
    documentContainer: 'document-container'
});

Creation

Factory	Description
`L.map( <HTMLElement\|String> id, <Map options> options? )`	Instantiates a map object given a div element (or its id) and optionally an object literal with map options described below.

Options

These are the options intended to be used for browser, using any additional options from Leaflet might cause some unexpected behaviour.

Option	Type	Default	Description
`doc`	`String`	`undefined`	Document URL, the server should be able to access the document.
`server`	`String`	`undefined`	The websocket server hosting coolwsd using the `ws:` protocol. Example: wss://localhost:9980
`webserver`	`String`	`undefined`	The webserver access to hosting coolwsd. Normally it is derived from 'server', but can be overridden with an own value in case of proxying. Example: http://localhost:9980
`permission`	`String`	`'view'`	The document's permission.
`timestamp`	`String`	`undefined`	A timestamp of the last modification to the document.
`documentContainer`	`String / DOM element`	`undefined`	An outer div, containing the map div, that is used internally for the creation of the toolbar.
`toolbarContainer`	`String / DOM element`	`undefined`	A div used by the default toolbar elements (bold, italic, search, etc.) in browser. If you implement your own toolbar and use controls that do not require a toolbar (like the dialog or scroll control) you can ignore this.
`renderingOptions`	`Object`	`undefined`	Enables the continuous, web view, of the document, see the UNO commands below for this parameter.
`print`	`Boolean`	`true`	Whether the print handler is active (for Chrome).
`autoFitWidth`	`Boolean`	`true`	Whether the document is automatically zoomed so that the width fits the viewing area when the window is resized. The document will not be zoomed in more than map.options.zoom.
`zoom`	`Number`	`10`	Default zoom level in which the document will be loaded.
`tileWidthTwips`	`Number`	`3840`	Default tile width in twips (how much of the document is covered horizontally in a 256x256 pixels tile). Unless you know what you are doing, this should not be modified; this means twips value for 256 pixels at 96dpi.
`tileHeightTwips`	`Number`	`3840`	Default tile height in twips (how much of the document is covered vertically in a 256x256 pixels tile). Unless you know what you are doing, this should not be modified; this means twips value for 256 pixels at 96dpi.
`defaultZoom`	`Number`	`10`	The zoom level at which the tile size in twips equals the default size (3840 x 3840). Unless you know what you are doing, this should not be modified.
`cursorURL`	`String`	`undefined`	The path (local to the server) where custom cursor files are stored.

General

General methods for document interaction.

Method	Returns	Description
`search( <String> phrase, <Boolean> backward? )`	`undefined`	Searches for the given phrase downward from the current top border of the viewing area. Or backwards if specified.
`highlightAll( <String> phrase,`	`undefined`	Highlights all the occurrences of the given phrase. Please note that this adds an extra layer for the highlights, so it is possible to see both all the highlighted phrase, and the current selection at the same time.
`setPermission( <DocumentPermissionValues> documenPermission)`	`undefined`	Sets the permission of the document.
`getDocSize()`	`Point`	Returns the document size.
`getDocType()`	`DocumentTypeValues`	Returns the document type.
`getPageSizes()`	`{twips: [Bounds], pixels: [Bounds]}`	Returns an object describing the size of each page in twips and pixels.
`scroll( <Number>x, <Number>y, <ScrollOptions>Options)`	`undefined`	Scroll right by 'x' and down by 'y' (or left and up if negative).
`scrollDown( <Number>y, <ScrollOptions>Options)`	`undefined`	Scroll down by 'y' (or up if negative).
`scrollRight( <Number>x, <ScrollOptions>Options)`	`undefined`	Scroll right by 'x' (or left if negative).
`scrollTop( <Number>y, <ScrollOptions>Options)`	`undefined`	Scroll to 'y' offset relative to the beginning of the document.
`scrollLeft( <Number>x, <ScrollOptions>Options)`	`undefined`	Scroll to 'x' offset relative to the beginning of the document.
`scrollOffset()`	`Point`	Returns the scroll offset relative to the beginning of the document.
`getPreview( <Object>id, <Number>index, <Number>maxWidth, <Number>maxHeight, <PreviewOptions>options?)`	`undefined`	Triggers the creation of a preview with the given id, of maximum maxWidth X maxHeight size, of the page / part with number 'index', keeping the original ratio.
`getCustomPreview( <Object>id, <Number>part, <Number>width, <Number>height, <Twips>tilePosX, <Twips>tilePosY, <Twips>tileWidth, <Twips>tileHeight, <PreviewOptions>options?)`	`undefined`	Triggers the creation of a preview with the given id, of width X height size, of the [(tilePosX,tilePosY), (tilePosX + tileWidth, tilePosY + tileHeight)] section of the document.
`removePreviewUpdate( <Object>id)`	`undefined`	Cancels the automatic update for the preview defined by 'id'.
`fitWidthZoom( <Number>maxZoom)`	`undefined`	Zooms in or out so that the document's width fits the viewing area. The document will not zoom in more than `maxZoom` if the parameter is provided.

ScrollOptions

property	type	description
`update`	`Boolean`	Whether the update-scroll-offset event is fired.

PreviewOptions

property	type	description
`autoUpdate`	`Boolean`	Whether a new preview is generated automatically when it becomes invalid.
`broadcast`	`Boolean`	Whether new preview should be broadcasted to other clients of same document.

Toolbar methods.

Method	Returns	Description
`getToolbarCommandValues( <ToolbarCommandValues> unoCommand)`	`Object`	Returns a JSON mapping of the possible values.
`toggleCommandState( <CommandValues> unoCommand)`	`undefined`	Toggles the state for the given UNO command.
`saveAs( <String>url, <String>format?, <String>options?)`	`undefined`	Save the document as "format" at the given URL by applying the filter options.
`downloadAs( <String>name, <String>format?, <String>options?)`	`undefined`	Download the document as "format" with the name "name" by applying the filter options.
`print()`	`undefined`	Opens the browser's print dialog or prompts the user to download a PDF version of the document.
`cellEnterString( <String>formula)`	`undefined`	Enters a string of text in the selected cell.
`insertFile( <File>file)`	`undefined`	Insert a file (graphic) in the document.
`applyFont( <String>fontName)`	`undefined`	Applies a font.
`applyFontSize( <Number>fontSize)`	`undefined`	Applies a font size.
`applyStyle( <String>style, <String>styleFamily)`	`undefined`	Applies a style from a style family.
`renderFont( <String>fontName)`	`undefined`	Renders the given font in the smallest rectangle it can fit in.
`sendUnoCommand( <String> unoCommand, <Object> param)`	`undefined`	Sends a uno command with the given parameter to LOKit.

Page oriented

Methods for page oriented documents.

Method	Returns	Description
`getCurrentPageNumber()`	`Number`	Number of the current page.
`getNumberOfPages()`	`Number`	Total number of pages.
`goToPage( <Number>pageNumber)`	`undefined`	Scrolls to the beginning of the given page.

Part oriented

Methods for page oriented documents.

Method	Returns	Description
`getCurrentPartNumber()`	`Number`	Number of the current part.
`getNumberOfParts()`	`Number`	Total number of parts.
`setPart( <Number>partNumber)`	`undefined`	Select a specific part.

Events

You can subscribe to the following events using these methods.

Event	Data	Description
`cellformula`	`CellFormulaEvent`	Fired when the content of the selected cell changes.
`commandresult`	`CommandResultEvent`	Fired when a dispatched uno command or the 'saveas' command has finished.
`commandstatechanged`	`CommandStateChangedEvent`	Fired when the state of a command such as .uno:Bold changes.
`locontextmenu`	`LOContextMenuEvent`	Fired when the user's action invoked a context menu (via a right-click). It contains the structure of the menu.
`docsize`	`DocumentSizeEvent`	Fired when the document size changes.
`error`	`ErrorEvent`	Fired on server or client error.
`hyperlinkclicked`	`HyperlinkClickedEvent`	Fired when the user clicks a hyperlink in the document.
`pagenumberchanged`	`PageNumberChangedEvent`	Fired when the number of pages changes.
`print`	`PrintEvent`	Fired when the URL for the PDF export is ready.
`renderfont`	`RenderFontEvent`	Fired when the font rendering is ready.
`search`	`SearchEvent`	Fired when the search result is ready.
`scrollby`	`ScrollByEvent`	Fired when the document is panned with the keyboard.
`scrollto`	`ScrollToEvent`	Fired when the cursor goes out of the viewing area.
`statusindicator`	`StatusIndicator`	Fired when leaflet is initialized, during document loading or on reconnection.
`tilepreview`	`TilePreviewEvent`	Fired when the rendering of a requested preview is ready.
`updateparts`	`UpdatePartsEvent`	Fired when a new part has been selected.
`updatepermission`	`PermissionEvent`	Fired when the document permission changes.
`updatescrolloffset`	`UpdateScrollOffsetEvent`	Fired when the document is panned and the scrollbars should be moved along with the document.
`updatetoolbarcommandvalues`	`UpdateToolbarCommandValuesEvent`	Fired when the document is loaded and contains the available command values for Font, FontSize, Style, etc.

CellFormulaEvent

property	type	description
`formula`	`String`	The formula from the selected cell.

CommandResult

property	type	description
`commandName`	`CommandStateChangedValues`	UNO command or 'saveas'.
`success`	`Boolean or undefined`	Returns the status code of the command execution, or undefined if the result is not provided, and the command only indicates that the operation has finished.

CommandStateChangedEvent

property	type	description
`commandName`	`CommandStateChangedValues`	UNO command.
`state`	`CommandStateValues`	UNO command state.

LOContextMenuEvent

property	type	description
`menu`	`String`	List of the menu entries. The structure looks like: `{ "text": "label text1", "type": "command", "command": ".uno:Something1", "enabled": "true" }, { "text": "label text2", "type": "command", "command": ".uno:Something2", "enabled": "false" }, { "type": "separator" }, { "text": "label text2", "type": "menu", "menu": [ { ... }, { ... }, ... ] }, ...`

DocumentSizeEvent

property	type	description
`x`	`Number`	Document width in pixels.
`y`	`Number`	Document height in pixels.

ErrorEvent

property	type	description
`id`	`Number`	Identificator of the error that can be used as indication of error message to present to the user.
`msg`	`String`	If present, the error message.
`cmd`	`String`	If present, the server command that caused the error.
`kind`	`String`	If present, the kind of error associated with the command.

The id property of ErrorEvent can have the following values:

value	description
`1`	Internal error. Things still may work to some extent, but the session becomes unreliable.
`2`	Document couldn't be loaded.
`3`	Socket connection error.
`4`	Socket connection was closed.
`5`	Document couldn't be saved.

HyperlinkClickedEvent

property	type	description
`url`	`String`	Target URL of the hyperlink that the user clicked in the document.

PageNumberChangedEvent

property	type	description
`currentPage`	`Number`	The current page in the document.
`pages`	`Number`	The number of pages.
`docType`	`DocumentTypeValues`	The document type.

PrintEvent

property	type	description
`url`	`String`	An URL for the PDF exported document.

RenderFontEvent

property	type	description
`font`	`String`	Font name.
`img`	`String`	The image data URL.

SearchEvent

property	type	description
`originalPhrase`	`String`	The phrase that has been searched for
`count`	`Number`	Number of search results
`results`	`SearchResult[]`	An array representing the selections of the search results in the document.

ScrollByEvent

property	type	description
`x`	`Number`	Scroll right by x pixels, or left if negative.
`y`	`Number`	Scroll down by y pixels, or up if negative.

ScrollToEvent

property	type	description
`x`	`Number`	View's left border position in pixels.
`y`	`Number`	View's top border position in pixels.

StatusIndicatorEvent

property	type	description
`statusType`	`StatusIndicatorValues`	Status type.
`value`	`Number`	If present, a number for 0 to 100 representing the loading status.

TilePreviewEvent

property	type	description
`tile`	`Image`	The actual preview.
`id`	`Object`	Preview id.
`width`	`Number`	Image width.
`height`	`Number`	Image height.
`docType`	`DocumentTypeValues`	The document type.
`part`	`Number`	If the preview is for a whole part.

UpdatePartsEvent

property	type	description
`selectedPart`	`Number`	The currently selected part.
`parts`	`Number`	The number of parts in the document.
`docType`	`DocumentTypeValues`	The document type.
`partNames`	`String[]`	If present, an array containing slides' / spreadsheets' names.

PermissionEvent

property	type	description
`perm`	`DocumentPermission`	Document permission.

UpdateScrollOffsetEvent

property	type	description
`x`	`Number`	Difference in pixels between the document's left border and view's left border.
`y`	`Number`	Difference in pixels between the document's top border and view's top border.

UpdateToolbarCommandValuesEvent

property	type	description
`commandName`	`ToolbarCommandValues`	UNO command.
`commandValues`	`Object`	JSON mapping of the possible values.

Object values

A list of possible values for different event object properties.

SearchResult

property	type	description
`part`	`Number`	The part in which the selection lies.
`rectangles`	`Bounds[]`	Selection bounds in pixels.

DocumentPermissionValues

value	type	description
`'edit'`	`String`	The document can be edited, dragging is disabled and mouse selection is active.
`'view'`	`String`	The document is in viewing mode, dragging is enabled by default and by clicking in it, editing mode is entered.
`'readonly'`	`String`	The document is in read-only mode, dragging is enabled by default.

CommandStateChangedValues

value	type	description
`'.uno:Bold'`	`String`	Bold.
`'.uno:Italic'`	`String`	Italic.
`'.uno:Underline'`	`String`	Underline.
`'.uno:Strikeout'`	`String`	Strikeout.
`'.uno:LeftPara'`	`String`	Align left.
`'.uno:CenterPara'`	`String`	Center horizontally.
`'.uno:RightPara'`	`String`	Align right.
`'.uno:JustifyPara'`	`String`	Justified.
`'.uno:IncrementIndent'`	`String`	Increment indent.
`'.uno:DecrementIndent'`	`String`	Decrement indent.
`'.uno:StyleApply'`	`String`	Style related uno command.
`'.uno:CharFontName'`	`String`	Font related uno command.
`'.uno:FontHeight'`	`String`	Font size related uno command.
`'.uno:ModifiedStatus'`	`String`	If the document is now marked as modified. The value is 'true' when the document is marked as modified, and 'false' the user e.g. undoes all the changes or saves the document.

CommandStateValues

value	type	description
`'true'`	`String`	For '.uno:Bold', '.uno:Italic', etc.
`'false'`	`String`	For '.uno:Bold', '.uno:Italic', etc.
`styleName`	`String`	For '.uno:StyleApply'.
`fontName`	`String`	For '.uno:CharFontName'.
`fontSize`	`String`	For '.uno:FontHeight'.

DocumentTypeValues

value	type	description
`'text'`	`String`	Text document, usually handled by Writer.
`'presentation'`	`String`	Text document, usually handled by Impress.
`'spreadsheet'`	`String`	Text document, usually handled by Calc.
`'drawing'`	`String`	Text document, usually handled by Draw.
`'other'`	`String`	Other document type.

StatusIndicatorValues

value	type	description
`'start'`	`String`	Fired when the progress broadcast is being started.
`'setvalue'`	`String`	Set a value between 0 and 100.
`'finish'`	`String`	The progress is at 100%.
`'coolloaded'`	`String`	Fired when the code has been initialized.
`'alltilesloaded'`	`String`	Fired when all empty tiles have been loaded (fired several times).
`'initializationcomplete'`	`String`	Fired when everything that is needed for operating on the document is ready: this._docLayer is defined, statusindicatorfinish was received, .uno:StyleApply was received, .uno:CharFontName was received, and updatepermission was received.

ToolbarCommandValues

value	type	description
`'.uno:StyleApply'`	`String`	Style related uno command.
`'.uno:CharFontName'`	`String`	Font related uno command.

Uno command

A list of common uno commands with their additional parameters.

map.sendUnoCommand('.uno:Bold')

map.sendUnoCommand('.uno:Color',
{
  "Color": {
    "type": "long",
    "value": 16750848
  }
})

command	parameter	description