CIB webRec technical documentation
Site: | CIB eLearning |
Course: | CIB webRec |
Book: | CIB webRec technical documentation |
Printed by: | Guest user |
Date: | Thursday, 26 December 2024, 11:38 PM |
CIB webRec GET parameters
These parameters are controlled by query string passed to CIB webRec instance when it is opened, e.g.
editor.html?reducePageSpace=true&initialFontSize=14
All values passed must be URI and then JSON-encoded, e.g. string example value must be passed as "example%20value", while number 42 is still 42.
If a key is passed that doesn’t exist, or a value’s type is not correct nor can be parsed, it is ignored and a warning is shown in browser console.
You could configure these parameters at back-end too using webrec.json file.
Property |
Value |
Type |
|
Controls if open and save options exist on toolbar and in context menu. If disabled, documents cannot be opened or saved by CIB webRec itself. default: true |
Boolean |
|
Controls if header (containing document name) is visible. Disabling header will reduce screen space used, but will make it impossible for user to rename document. default: true |
Boolean |
|
Reduces page margins and minimum space between pages to 2-4 pixels to reduce screen space used. default: false |
Boolean |
|
Controls how many pages at most can be positioned horizontally. Actual positioning depends on CIB webRec frame size and zoom level set in editor. default: 3 |
Number (must be integral and greater than 0) |
|
Forces CIB webRec to show a dialog when window is closed or file is opened with unsaved changes. default: false |
Boolean |
|
If set, includes CSS from provided link into the editor (see CIB webRec CSS customization). default: "" |
String |
|
If set, provided callback name will be run when editor loading is done (see CIB webRec JS API). default: "" |
String |
|
If set, provided callback name will be run when document loading is done. default: "" |
String |
|
If set, provided callback name will be run when an action is done. default: "" |
String |
|
If set, provided callback name will be run when the document is changed, reverted or saved. default: "" |
String |
|
If true, CIB fields will be filtered from editor when RTF document is loaded. default: false |
Boolean |
|
If true, fields will be toggled from result state to code state when RTF document is loaded. default: false |
Boolean |
|
If true, the last pilcrow will be removed. This parameter is used for snippet editing. default: false |
Boolean |
initialPageSize.width |
Sets default page size and orientation for new document created in webRec. Also these values are used for all snippets saved with webRec when snippet mode is enabled. default: initialPageSize.width = 8.27 inches initialPageSize.height = 11.69 inches initialPageSize.isLandscape = true |
|
|
Sets default page maergins for new document created in webRec. Also these values are used for all snippets saved with webRec when snippet mode is enabled. default: initialPageMargins.left = 1.18 inches initialPageMargins.right = 0.59 inches initialPageMargins.top = 0.79 inches initialPageMargins.bottom = 0.79 inches |
Numbers |
|
If set, specifies initial font name of the paragraph for the new document being created in CIB webRec. default: 'Times New Roman' |
String |
|
If set, specifies initial font size of the paragraph for the new document being created in CIB webRec. default: 11 |
Number |
|
If set to true, the cursor will be visible, elsewhere cursor position will not be visible. Selected content will be highlighted in all cases regardless this option. default: true |
Boolean |
|
Activates or disables cursor visibility on lost/gain input focus in the webRec frame. default: false |
Boolean |
|
If set, the cursor will blink. default: true |
Boolean |
|
If set, specifies webRec UI will not allow edit opened document. Also there will be disabled document save possibility. default: false |
Boolean |
|
If set, starts webRec with blocked UI. To unblock it integrator should call webRec.blockUI(false) default: false |
Boolean |
|
Could be set only inside webrec.base.json and/or inside webrec.json configuration files. If set, specifies font name and character for first 3 bullet levels. default: "bullets": [
|
JSON |
|
Indicates whether snippet mode (borderless layout) is switched on or off. In snippet mode you will not be able to setup page size, the document will be displayed without distribution on pages, and new documents will contain A4 page definition by default. default: false |
Boolean |
|
Enables page border line in disaplying of the document. When enableSnippetMode() is called, this parameter by default is set to false. default: true |
Boolean |
|
When set, the page will be resized to fit actual size of the webRec frame, on any zoom in/out operations. When enableSnippetMode() is called, this parameter by default is set to true. default: false |
Boolean |
|
When set, the page will be resized to fit actual size of the webRec frame. When enableSnippetMode() is called, this parameter by default is set to true. default: false |
Boolean |
|
Sets background color (for example “#c1c1c1”) of the page for displaying purpose only. If empty, color specified inside the document will be used for page background. default: "" |
String |
|
Disables editing possibility for font and font size combo boxes on webRec toolbar and insde Font properties dialog. default: false |
Boolean |
|
Sets page margins for opened snippet in snippet mode. This value is never saved into the final RTF document and used only for displaying purpose. default: snippetModeMargins.left
= 0.1 (inches) |
Object |
|
Sets grey offsets around document page for opened snippet in snippet mode. This value is never saved into the final RTF document and used only for displaying purpose. default: snippetModeViewOffsets.leftOffset
= 0 (pixels) |
Object |
|
Sets grey offsets around document pages and between pages for opened document not in the snippet mode. This value is never saved into the final RTF document and used only for displaying purpose. default: pageViewOffsets.leftOffset
= 50 (pixels) |
Object |
CIB webRec integration
CIB webRec could be integrated in different ways using or not specific libraries (pleasejs, jQuery). All those ways are already built in as samples into webRec:
- changeIconsExample.html
- disableFunctionalityExample.html
- frame-editor.html
- frame-editor-web-component.html
- frame-editor-web-component-pleasejs.html
- frame-editor-with-pleasejs-jquery.html
- leftTopToolbarExample.html
- placeToolbarExample.html
- randomToolbarExample.html
- removeFunctionalityExample.html
- webedit.html
Integration using web component (modern way)
CIB webRec iframe can be controlled by commands from enclosing page. For this, library called webrec-component.js is used.
Examples in this section assume that some initialization is run. Here we assume that CIB webRec frame is available by id #webRec
//grab a handle to call methods on
var webRec = document.getElementById('webRec')
Methods are called:
webRec.blockUI(true)
All message passing to iframe is asynchronous. WebRecComponent uses promises for it, so that a result should be processed using .then handler:
webRec.saveRTF().then(function (rtfString) {
console.log('We have saved RTF of length ' + rtfString.length)
})
When an API method is said to return a value, it means that you will be given a promise which resolves to that value when the method is done. It is also not safe to call methods one after another without using .then and return
// WRONG!
webRec.blockUI(true) webRec.insertRTF(someRTF) // was the UI blocked? It might be not
webRec.blockUI(false) // was the RTF inserted? It might be not Page 8 of 15
// RIGHT!
webRec.blockUI(true)
.then(function() {
return webRec.insertRTF(someRTF) // UI was blocked
}).then(function() {
return
})
Additional information on promises is available at its API documentation page: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
Integration using pleasejs and jquery (deprecated)
CIB webRec iframe can be controlled by commands from enclosing page. For this, library called please.js is used.
The library is available on GitHub (https://github.com/wingify/please.js) and is MIT-licensed. It also requires jQuery to be present.
Examples in this section assume that some initialization is run. Here we assume that CIB webRec frame is available by id #webRec
// initialize library in your frame
please.init(window) // grab a handle to call methods on
var frame = document.getElementById('webRec').contentWindow
Methods are called using please.call function:
please(frame).call('webRec.blockUI', true)
If you’re using only one CIB webRec frame, it might be more convenient to set it as default target, so to omit an argument to please function:
please.defaults({targetWindow: frame}) // just once
Allowing you to call a method this way:
please.call('webRec.blockUI', true)
This shorthand will be used in examples later.
All message passing to iframe is asynchronous. Please uses jQuery promises for it, so that a result should be processed using .then handler:
please.call('webRec.saveRTF').then(function (rtfString) {
console.log('We have saved RTF of length ' + rtfString.length)
})
When an API method is said to return a value, calling it with please means that you will be given a promise which resolves to that value when the method is done. It is also not safe to call methods one after another without using .then and return
// WRONG!
please.call('webRec.blockUI', true)
please.call('webRec.insertRTF', someRTF) // was the UI blocked? It might be not
please.call('webRec.blockUI', false) // was the RTF inserted? It might be not Page 8 of 15
// RIGHT!
please.call('webRec.blockUI', true
).then(function() {
return please.call('webRec.insertRTF', someRTF) // UI was blocked
}).then(function() {
return })
Additional information on jQuery promises is available at its API documentation page: http://api.jquery.com/category/deferred-object/
Open document for editing
Using file open command from toolbar you could specify the document for editing.
From the integrator side you could make a call
- webRec.setIDS() – set document from JSON string
- webRec.setRTF() – set document from RTF stream
- webRec.loadFromStorage() – set document from remote document storage
API
Complete list of methods you could check directly from the deployed CIB webRec instance by opening webRec webcomponent:
https://www.example.com/webrec/1.6.0/components/cib-webrec/webrec-component.js
Methods
Document APIToolbars API
Context menu API
Controls on webRec dialogs API
Shortcuts API
Cursor API
Document displaying API
Document API
webRec.newDoc()
Reset webRec editor to new (empty) document
Arguments:
1. [title=''] (string): Title to be set in title bar
Returns:
Nothing
webRec.getRTF()
Returns RTF representation of current document
Returns:
the promise object resolving to RTF content
webRec.setRTF(content, [title=”], [options={}])
Replaces current document with one represented by RTF
Arguments:
2. content (string): RTF document (snippet or file content)
3. [title=''] (string): Title to be set in title bar
4. [options={}] (object): Additional parsing options to be sent to server
- [options.filterCIBFields] (boolean): controls if CIB fields will be removed by server when the document is opened (default is taken from GET parameters)
- [options.toggleFieldCode] (boolean): controls if fields will be displayed in code mode (default is taken from GET parameters)
Returns:
Nothing
webRec.insertRTF(content, [options={}])
Pastes provided RTF content into current caret position.
Arguments:
1. content (string): RTF document (snippet or file content)
2. [options={}] (object): Additional parsing options to be sent to server.
3. [options.filterCIBFields] (boolean): controls if CIB fields will be removed by server when the document is opened (default is taken from GET parameters)
4. [options.toggleFieldCode] (boolean): controls if fields will be displayed in code mode (default is taken from GET parameters)
Returns:
Nothing
webRec.blockUI(state)
Causes editor frame to display spinner and block all interactions with user if state is true. If state is false, cancels previous block. Does not cancel internal blocks that editor does e.g. when opening files.
You could specify to open
initially webRec with blocked UI using initialBlockUI=true GET
parameter.
Arguments:
1. state (boolean): The state of block to be set in the frame
Returns:
Nothing
webRec.onlyPresetFontOptions(state)
Disables editing possibility for font and font size combo boxes on webRec toolbar and insde Font properties dialog.
Arguments:
1. state (boolean): true - disables editing possibility, false - enables editing possibility
Returns:
Nothing
Toolbars API
webRec.setIntegrationPanelState(state)
Changes the configuration of panel with custom buttons. See Integration panel for the details.
Arguments:
1. state (array): Array of button configurations
Returns:
Nothing
webRec.setIDS(ids, title)
Loads existing internal document structure into editor
Arguments:
1. ids: the document structure to load
2. title: title to display in UI
Returns:
Nothing
webRec.loadFromStorage(storageJson, cfg)
Loads document from remote document storage through webRec back-end
Arguments:
1. storageJson: json object with an information about storage to be used, plus document id of the document to be loaded
Sample:
'{ "class": "de.cib.webrec.backend.service.document.MockStorageConnector", "documentId": 121001}'
2. cfg: additional options to send into server
Returns:
the promise object
webRec.saveToStorage(storageJson)
Saves document to remote document storage through webRec back-end
Arguments:
1. storageJson: json object with an information about storage to be used, plus document id of the document being saved
Sample:
'{ "class": "de.cib.webrec.backend.service.document.MockStorageConnector",
"documentId": 121001}'
Returns:
webRec.setUiLanguage(lang)
Sets language for webrec UI
Arguments:
1. lang: de_DE, en_US & ru_RU
Returns:
Nothing
webRec.focusDocumentInput()
Sets input focus into the document editing area
Arguments:
Nothing
Returns:
Nothing
webRec.createToolbar(id, position, isEmpty)
Creates toolbar at the specified place
Arguments:
1. id: Id which will be assigned to the toolbar
2. isEmpty: Indicates if toolbar should be empty (without controls)
3. position: left, right, top, bottom. Top by default
Returns:
Nothing
webRec.removeToolbar(id)
Removes toolbar by provided id
Arguments:
1. Id
Returns:
Nothing
webRec.removeToolbarControls(toolbarId)
Removes all controls from the toolbar
Arguments:
1. toolbarId
Returns:
Nothing
webRec.restoreToolbarControls(toolbarId)
Restores the default toolbar configuration
Arguments:
1. toolbarId
Returns:
Nothing
webRec.addStandardElements(ids, toolbarId, index)
Adds standard elements on the toolbar in the specified order. Both groups and controls can be added. List of the standard id's for each group/control can be found in Toolbar.tsx
Arguments:
1. ids: List of standard names. Elements with these names will be added on the toolbar in the given order. For example: ['fileOptions', 'bold', 'italic']
2. toolbarId
3. index: Place where to add the elements. By default they will be added to the end.
Returns:
Nothing
webRec.addCustomElement(id, descriptor, toolbarId, index)
Adds custom element on the toolbar in the specified place. Either group or control can be added (depends on the second parameter)
Arguments:
1. id: id of the element to add
2. descriptor: declarative description of custom element
3. toolbarId: id of the toolbar to add
4. index: place where to add
Returns:
Nothing
Example
Adding 4 new custom buttons:
var integrationPanelState = [ { id: 'prev', title: 'Previous snippet', shortcut: 'Ctrl+1', callback: 'webRecCallbacks.prevBtn', icon: 'icon-chevron_double_left', disabled: true, hidden: false }, { id: 'next', title: 'Next snippet', shortcut: 'Ctrl+2', callback: 'webRecCallbacks.nextBtn', icon: 'icon-chevron_double_right', disabled: false, hidden: false }, { id: 'commit', title: 'Save changes', shortcut: 'Ctrl+3', callback: 'webRecCallbacks.commitBtn', icon: 'icon-check', className: 'commit', disabled: false, hidden: false }, { id: 'close', title: 'Close editor', shortcut: 'Ctrl+4', callback: 'webRecCallbacks.closeBtn', icon: 'icon-close', className: 'close', disabled: false, hidden: false } ];
please(frame.contentWindow).call(
'webRec.addCustomElement',
'integrationPanel', // name of the new toobar group
integrationPanelState, // list of buttons for the new group 'top',
0);
webRec.removeElements(ids)
Removes elements by theirs unique identifiers
Arguments:
1. ids: Names of the elements to remove
Returns:
Nothing
webRec.updateControl(id, descriptor)
Updates control according to the given configuration
Arguments:
1. descriptor, see example in addCustomElement() method description.
Returns:
Nothing
webRec.updateGroup(id, descriptor)
Updates group according to the given configuration
Arguments:
1. id: Group id
2. descriptor: New configuration, e.g. {layout: 'vertical'}
Returns:
Nothing
webRec.listStandardGroupNames()
list standard group's names (see Toolbar.tsx)
Returns:
array of names of standard groups
webRec.listStandardControlNames()
list standard control's names (see Toolbar.tsx)
Returns:
array of names of standard controls
webRec.insertStandardControlIntoGroup(groupId, controlId, index)
Returns:
Nothing
webRec.insertCustomControlIntoGroup(groupId, json, index)
Returns:
Nothing
webRec.placeToolbar(id, direction)
Returns:
Nothing
Context menu API
webRec.removeControlsInContextMenu(ids)
Removes menu entries from context menu
Arguments:
1. ids array of names of controls to remove. The complete list of available by default entries could be retrieved using listControlsInContextMenu() call.
Returns:
Nothing
webRec.addControlsInContextMenu(ids)
Returns previously removed entries in context menu
Arguments:
1. ids array of names of controls to be added. The complete list of available by default entries could be retrieved using listControlsInContextMenu() call.
Returns:
Nothing
webRec.disableControlsInContextMenu(ids)
Makes context menu entries gray and inaccessible
Arguments:
1. ids array of names of controls to disable. The complete list of available by default entries could be retrieved using listControlsInContextMenu() call.
Returns:
Nothing
webRec.enableControlsInContextMenu(ids)
Enables previously disabled menu entries
Arguments:
1. ids array of names of controls to enable. The complete list of available by default entries could be retrieved using listControlsInContextMenu() call.
Returns:
Nothing
webRec.listControlsInContextMenu()
Lists entries available by default inside context menu.
Returns:
In webRec 1.6 this method returns:
['open', 'save', 'undo', 'redo', 'increaseIndent', 'decreaseIndent', 'restartNumbering', 'continueNumbering', 'font', 'paragraph', 'page', 'insertRowAbove', 'insertRowBelow', 'insertColumnLeft', 'insertColumnRight', 'deleteRows', 'deleteColumns', 'tableProperties', 'license']
webRec.listRemovedControlsInContextMenu()
Returns:
Array of ids for removed controls from context menu.
webRec.listDisabledControlsInContextMenu()
Returns:
Array of ids for disabled controls inside context menu.
Controls on webRec dialogs API
webRec.removeControlsInDialogs(ids)
Removes specific controls from dialogs
Arguments:
1. ids array of names of controls to remove. The complete list of available entries could be retrieved using listControlsInDialogs() call.
Returns:
Nothing
webRec.addControlsInDialogs(ids)
Returns previously removed controls in dialogs
Arguments:
1. ids ids array of names of controls to be returned. The complete list of available controls could be retrieved using listControlsInDialogs() call.
Returns:
Nothing
webRec.disableControlsInDialogs(ids)
Disables specific controls on dialogs
Arguments:
1. ids array of names of controls to disable. The complete list of available entries could be retrieved using listControlsInDialogs() call.
Returns:
Nothing
webRec.enableControlsInDialogs(ids)
Returns previously disabled controls in dialogs
Arguments:
1. ids array of names of controls to be enabled. The complete list of available controls could be retrieved using listControlsInDialogs() call. To get a list of already disabled controls use listDisabledControlsInDialogs() call.
Returns:
Nothing
webRec.listControlsInDialogs(ids)
Returns list of available controls on dialogs
Arguments:
Nothing.
Returns:
Returns list of available controls on dialogs
In CIB webRec 1.6.2 this method returns:
["row.height", "row.break", "row.header", "row.leftPadding",
"row.rightPadding", "row.topPadding", "row.bottomPadding", "cell.vertAlignment",
"cell.leftPadding", "cell.rightPadding", "cell.topPadding", "cell.bottomPadding",
"page.size", "page.orientation", "page.margins", "font.fontName", "font.fontSize", "font.fontStyle",
"font.underline", "font.superscript", "font.allCaps", "font.hidden",
"font.strikethrough", "font.subscript", "font.smallCaps", "paragraph.alignment",
"paragraph.language", "paragraph.doNotHyphenate", "paragraph.leftIndent", "paragraph.rightIndent",
"paragraph.specialIndent", "paragraph.spaceBefore", "paragraph.spaceAfter", "paragraph.lineSpacing",
"paragraph.noSpaceSameStyle", "paragraph.pageBreakBefore", "paragraph.widowControl", "paragraph.keepWithNext",
"paragraph.keepLinesTogether", "paragraph.borders"].
webRec.listRemovedControlsInDialogs(ids)
Returns list of ids of removed controls from dialogs
Arguments:
Nothing
Returns:
Returns list of ids of removed controls from dialogs
webRec.listDisabledControlsInDialogs(ids)
Returns list of ids of disabled controls from dialogs
Arguments:
Nothing
Returns:
Returns list of ids of disabled controls from dialogsShortcuts API
webRec.listShortcuts()
Returns all available shortcuts
Arguments: none
Returns:
Array of available shortcuts
webRec.blockShortcut(key)
Disables shortcut
Arguments:
1. key Shortcut to disable. For example, 'Ctrl+Shift+F'
Returns:
Nothing
webRec.blockShortcuts(keys)
Disables several shortcuts
Arguments:
1. keys Array of shortcuts to disable. For example, ['Ctrl+Shift+F', ‘Enter’]
Returns:
Nothing
webRec.unblockShortcut(key)
Enables shortcut
Arguments:
1. Key
Returns:
Nothing
webRec.listBlockedShortcuts()
Returns:
Array of blocked shortcuts. For example, ['Ctrl+Shift+F', ‘Enter’].
webRec.setShortcu(id, key)
Adds/removes a new shortcut for some specific toolbar button
Arguments:
1. id - id of the toolbar button, for example 'insertTable'. A list of available ids you could take using listStandardControlNames() method
2. key shortcut to add. For example, 'Ctrl+Shift+F'. If the key is null or empty string, the existing shortcut for this control will be removed.
Returns:
Nothing
Cursor API
webRec.showCursor(visibility)
Shows or hides cursor. Could used together with enableReadOnlyMode() / disableReadOnlyMode() call. Selected content will be highlighted in all cases regardless this option.
Arguments:
1. visibility true: show cursor or false – hide cursor.
Returns: Nothing
webRec.enableCursorBlinking()
Enables cursor blinking at caret position. By default cursor blinking is enabled.
Arguments: none
Returns: Nothing
webRec.disableCursorBlinking()
Disables cursor blinking at caret position. By default cursor blinking is enabled.
Arguments: none
Returns: Nothing
webRec.hideCursorOnLostFocus()
Activates or disables cursor visibility on lost/gain input focus in the webRec frame.
Arguments: hide – true if activate this fuctionality
Returns: Nothing
webRec.disableReadOnlyMode()
Enables all editing functions for opened document and resets page background color override (see, webRec.overridePageColor). Could be used together with blockUI(false) call.
Arguments: none
Returns: Nothing
Document displaying API
webRec.overridePageColor(pageColor = ‘’)
Sets background color of the page for displaying purpose only. Method is used together with read-only mode: enableReadOnlyMode(), disableReadOnlyMode().
Arguments:
1. pageColor color to be used, for example “#c1c1c1”, '' - to use color specified inside the document.
Returns: Nothing
webRec.enableSnippetMode(options | null)
Sets snippet mode for displaying of the document.
Arguments: none or options objects:
{
enablePageBorderLines: boolean - enable page border lines
resizeCanvasOnZoom: boolean - resize canvas on zoom
resizeCanvasOnWindowResize: boolean - resize canvas on window resize
offsets: {
leftOffset: number - left offset (grey area) in pixels
rightOffset: number - right offset in pixels
topOffset: number - top offset in pixels
pageOffset: number - page offset in pixels
}
pageMargins: {
top: number - top page margin (white area) in inches
bottom: number - bottom page margin in inches
left: number - left page margin in inches
right: number - right page margin in inches
}
}
- enablePageBorderLines Enables page border line in disaplying of the document. When omitted this parameter by default is set to false.
- resizeCanvasOnZoom When set to true, the page will be resized to fit actual size of the webRec frame, on any zoom in/out operations. When omitted this parameter by default is set to true.
- resizeCanvasOnWindowResize When set to true, the page will be resized to fit actual size of the webRec frame. When omitted this parameter by default is set to true.
You could also open snippet mode using GET parameters:
- http://localhost:8080/editor.html?snippetMode=true - open snippet mode using default properties
- http://localhost:8080/editor.html?snippetMode=true&enablePageBorderLines=false&resizeCanvasOnZoom=true&
resizeCanvasOnWindowResize=true&snippetModeViewOffsets.leftOffset=10&snippetModeViewOffsets.rightOffset=10&
snippetModeViewOffsets.topOffset=10&snippetModeViewOffsets.pageOffset=10&snippetModeMargins.top=0.3&snippetModeMargins.
bottom=0.3&snippetModeMargins.left=0.3&snippetModeMargins.right=0.3 - open snippet mode with overriding all default properties
Returns: Nothing
webRec.disableSnippetMode()
Returns back displaying of the document in page layout mode. The document will be saved with page definition specified inside Page dialog.
Note: When you have switched
on snippet mode, then have resized the document, and switched back page layout
mode, page definition inside the document will be set to webRec default values
(A4, portrait).
Arguments: none
Returns: Nothing
Attributes
Available attributes:
- src
- width
- height
Integration panel
To push custom controls into CIB webRec, there exists a special panel with buttons which can be configured during runtime. This panel is shown near (or instead of) open and save buttons. These buttons will make CIB webRec perform a function call in enclosing window using the same mechanism.
To configure this panel, you would provide an array of objects into webRec.setIntegrationPanelState. Objects must have following fields:
{ key: string, // Unique ID for this particular button
title: string, // Text that will be shown when button is hovered
shortcut: string, // Shortcut for the button. Optional parameter.
callback: string, // Path to function to be called when
// button is clicked
icon: string, // icon name
disabled: boolean, // True makes the button greyed out
// and not clickable
display: boolean // False hides the button completely
}
Supported icons are that of FontAwesome (http://fontawesome.io/icons/). Icon name is the CSS class without fa- prefix (fa-cog becomes just cog)
callback should contain a complete path to a function to be called. Functions will be called with no arguments.
window.blockForever = function () {
please.call('webRec.blockUI', true)
}
window.webRecCallbacks = {
reloadWebRec: function () {
please.call('location.reload')
}
}
please.call('webRec.setIntegrationPanelState', [
{
key: 'process',
title: 'Process document',
callback: 'my_processing_implementation',
icon: 'icon-check',
disabled: false,
display: true
},
{
key: 'reload',
title: 'Reload editor tab',
callback: 'webRecCallbacks.reloadWebRec',
icon: 'icon-refresh',
disabled: false,
display: true
}
])
Providing a GET parameter onEditorOpen is the best place for CIB webRec initialization, including integration panel. It obeys the same rules as callback property in integration button (a path to zero-argument function).
CIB webRec and remote document storage
CIB webRec could work with documents loaded and saved directly from/to remote document storage. In this case an access to remote storage is configured on the server side using connector class and therefore is hidden at front-end. At front-end you could work with documents using your own tokens or session id which corresponds to appropriate document.
For proper work you need:
- Implement your own connector class
- Configure connector inside webrec.properties file
- Configure JSON object to call webRec.loadFromStorage()
Connector
How to write an implementation:
- Create a maven project
- Reference de.cib.webrec.cib-webrec-backend with scope provided (see pom.xml)
- Create an implementation of your own connector
- Define own fields needed
- Implement fetchContent and storeContent
Your connector should extend following base class:
package de.cib.webrec.backend.service.document;
import com.fasterxml.jackson.annotation.JsonTypeInfo;
@JsonTypeInfo(use = JsonTypeInfo.Id.CLASS, include = JsonTypeInfo.As.PROPERTY, property = "class")
public interface StorageConnector {
byte[] fetchContent();
void storeContent(byte[] content);
}
Example
package de.cib.webrec.backend.service.document;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
public class MockStorageConnector implements StorageConnector {
private Logger LOGGER = LoggerFactory.getLogger(DocumentProcessingService.class);
public String documentId;
public byte[] fetchContent() {
LOGGER.debug("Retrieve document by documentId=" + this.documentId + " from remote database");
String rtf = "{\\rtf documentId=" + this.documentId + ".\\par Created by de.cib.crowdsource.rest.CrowdsourceDocumentRequest.\\par}";
return rtf.getBytes();
}
public void storeContent(byte[] content) {
LOGGER.debug("Store document by documentId=" + this.documentId + " into remote database");
}
}
Pom.xml
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>webrec</groupId>
<artifactId>integration</artifactId>
<version>0.0.1-SNAPSHOT</version>
<properties>
<java.version>1.8</java.version>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
<dependencies>
<dependency>
<groupId>de.cib.webrec</groupId>
<artifactId>cib-webrec-backend</artifactId>
<version>1.6.1</version>
<type>jar</type>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-web</artifactId>
<version>4.1.4.RELEASE</version>
<scope>provided</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<source>${java.version}</source>
<target>${java.version}</target>
</configuration>
</plugin>
</plugins>
</build>
</project>
webrec.properties file
In the webrec.properties file you could specify default values for any parameter which will be used inside your connector. All these paramters later could be overwritten with values provided from JSON object during webRec.loadFromStorage() request.
Sample:
ConnectorName={"class": "de.cib.webrec.backend.service.document.MockStorageConnector",
"param1": "Connector2param1", "param2": "Connector2param2"}
webRec.loadFromStorage() call
Call webrec with a json representation of the Class with the full qualified name as 'class' parameter or the name of the connector in the webrec configuration as 'connector' parameter:
Specifying connector using class name:
function loadDocument() { webRec().loadFromStorage('{ "class": "de.cib.webrec.backend.service.document.MockStorageConnector", "documentId": 121003}') .then(function () { console.log('Document is loaded'); }).catch(function(error) { console.log('Failed to load document, Reason: ' + error.message) webRec().newDoc(''); }); }
Here is a sample to open document:
function loadDocument() { webRec().loadFromStorage('{ "connector": "ConnectorName", "documentId": 121003}') .then(function () { console.log('Document is loaded'); }).catch(function(error) { console.log('Failed to load document, Reason: ' + error.message) webRec().newDoc(''); }); }
Example 1: Button to insert RTF provided by a custom dialog
Assuming custom dialog exists with ID #picker and can trigger event named rtf_selected.
1. Initialize please as shown before
2. Provide necessary functions for editor in your JS
window.rec = {
init: function () {
please.call('webRec.setIntegrationPanelState', [{
key: 'custom-insert-rtf',
title: 'Insert RTF here',
shortcut: 'Ctrl+Shift+I',
callback: 'rec.showRTFDialog',
icon: 'plus-square',
disabled: false,
display: true
}])
},
showRTFDialog: function () {
please.call('webRec.blockUI', true).then(function () {
$('#picker').show()
})
}
}
3. Handle selection in your JS code:
$('#picker').on('rtf_selected', function (event) {
var rtfString = event.data
if (rtfString) {
$('#picker').hide()
please.call('webRec.insertRTF', rtfString).then(function () {
please.call('webRec.blockUI', false)
})
}
})
4. Embed webRec with parameters:
<iframe src='editor.html?onEditorOpen="rec.init"&onDocumentLoad="onDocumentLoaded"& enableHeader=false&enableFileButtons=false&reducePageSpace=true&mpinitialFont="Arial" &initialFontSize=11'>
See, “CIB
webRec GET parameters” section for list of available GET parameters.
Example 2: Open webRec in snippet mode using GET parameters
Next links show how you could open snippet mode using GET parameters:
- http://localhost:8080/editor.html?snippetMode=true - open snippet mode using default properties
- http://localhost:8080/editor.html?snippetMode=true&enablePageBorderLines=false&resizeCanvasOnZoom=true&
resizeCanvasOnWindowResize=true&snippetModeViewOffsets.leftOffset=10&snippetModeViewOffsets.
rightOffset=10&snippetModeViewOffsets.topOffset=10&snippetModeViewOffsets.pageOffset=10&
snippetModeMargins.top=0.3&snippetModeMargins.bottom=0.3&snippetModeMargins.left=0.3&snippetModeMargins.right=0.3 - open snippet mode with overriding all default properties
Note: when you switched to snippet mode with custom properties, they will be remembered and when you switched on snippet mode once again they will be restored, so you do not need to provide them twice (for the same instance of the webRec).
CIB webRec CSS customization
General information
CIB webRec allows insertion of custom CSS so that it is possible to adjust look and feel of editor controls. It is possible to use CSS to hide unnecessary options from toolbar and it might be useful for very small widgets. However, CSS is also used for layout options (e.g. to position scrollbar correctly). This includes:
- Scrollbar position and size
- Canvases position
- Display property on any object (except setting it to none)
Overriding such options may result in glitches and is not supported.
To control the appearance of elements specifically within some container.
Customization
To add your own style definition, you could use “css” configuration parameter, wchich you could set:
- In webrec frame URL (example editor.html?css="https://example.com/webrec-theme/integration-theme.css")
- In webrec.json config file (example "css": "/webrec-theme/integration-theme.css")
Components
Header
- input.doctitle
- div.logo
Toolbar (div.toolbar)
Toolbar controls are grouped by meaning in elements to keep related elements together. All toolbar is contained in div.toolset element for layout reasons.
Groups
div.integrationPanel:
Contains custom buttons created via JS API.
div.fileOptions:
Contains buttons for opening and save. Can be disabled by GET parameter.
div.fontStyleOptions:
Contains basic text formatting buttons (bold, italic, color, etc.).
div.fontFaceOptions:
Contains comboboxes for choosing font family and font face.
div.paragraphOptions:
Contains buttons for changing left indent of the paragraph, alignment buttons and line spacing combobox, paragraph properties, tab stops and paragraph color.
div.breakingSymbolOptions:
Contains buttons for inserting line and page breaks.
div.undoRedoOptions:
Contains undo and redo buttons.
div.sectionOptions:
Contains buttons for page background colors and page properties.
div.miscOptions:
Contains buttons for showing formatting characters, toggling spellchecking and hyphenation and changing interface language and metric system used.
Controls
- All buttons have class .button. Buttons that appear pressed have .pressed class as well.
- Comboboxes are made of two parts each: div.controls, which is what is shown at the toolbar, and ul.items, which is hidden list that appears when arrow is clicked.
- .controls contains input within div.input-wrapper and arrow that shows the rest of the elements as div.items-toggle.
- .items contains li elements with available options.
For example, you could make all input control in toolbar not editable by applying “readonly” CSS parameter in your custom CSS file:
.toolbar-input-fontName { readonly: true; }
.toolbar-input-fontSize { readonly: true; }
.toolbar-input-lineSpacing { readonly: true; }
Editor area (div.canvasHolder)
There is not much to control in the editor area, because its content is simply <canvas> element display. The background color can be changed by using area class. The position of the canvases is controlled by the code and NOT intended to be changed.
Status panel (div.status-panel)
- Paragraph language: select.paragraph-language
- Zoom out button: div.button.zoom-out
- Zoom level text: span.zoom-level-indicator
- Zoom in button: div.button.zoom-in
- Cursor position info: span.pos-info
NOTE: CIB webRec uses cascading to distinguish between toolbar .buttons and ones in the status panel (i.e. .toolbar .button and .status-panel .button)
Scrollbar (div.scroll-drag-area)
Same styling is applied for both vertical and horizontal scrollbars. When the scrollbar is inactive, class .scroll-fading is added to scrollbar area. Scrollbar area transitions are background .3s linear, opacity .3s linear;. This is used for effects when disappearing and on mouse hover.
- Draggable notch: div.scroll-drag
Dialogs (div.dialog)
Dialogs are put into div.dialog-container which covers whole area to provide modality. Dialog contents consist of three parts:
- div.dialog-header with title in h3 and cross in a.button-close
- div.dialog-body with dialog contents
- div.dialog-footer containing button.button-ok and button.button-cancel
Body of a
dialog typically consists of a fieldset with legend in it and a set of labels inside
div.form-style, containing input and select controls. All text is kept in
span elements.
Configuration
application.properties
application.properties file contains all default properties for back-end. This flie is build-in inside webrec.war file. To customize values inside it, please use webrec.properties file which you could place in the /lib/ folder of the Tomcat.
Sample:
#Path for dict spellcheck.rootdir = /dict/ #Path for hunspell-libs spellcheck.libdir = /hunspell-libs/ spellcheck.dictionaries = en_US,de_DE,ru_RU #Path for fonts fonts.dir = /fonts/ # 1) First font to be loaded at webRec front-end before to show the new/loaded document # 2) When "initialFont" is empty "fonts.defaultFontName" is taken as default font inside new document created by webRec fonts.defaultFontName = Times New Roman #Usage: Arial Unicode MS,Arial excludeFontNames= # Properties of connectors for Remote Document DB wopiConnector={"class": "de.cib.webrec.backend.service.document.WopiConnector", "url": "http://localhost:8080/webedit/wopi"} undConnector={"class": "de.cib.webrec.backend.service.document.UNDConnector", "owner": "webrec", "url": "http://localhost:8080/und-service"} Connector1={"class": "de.cib.webrec.backend.service.document.MockStorageConnector", "param1": "Connector1param1", "param2": "Connector1param2"} Connector2={"class": "de.cib.webrec.backend.service.document.MockStorageConnector", "param1": "Connector2param1", "param2": "Connector2param2"}
This property specifies a font name which will be used on following 3 scenarios:
1. Specifies a font which will be used by default when you create a new document with webRec (start webRec without loading of any document).
2. Specifies first font which will be loaded before showing webRec document. When this font is loaded, webRec will be shown and empty document will be rendered with this font only. Then in background all other fonts (see fonts.dir property in application.properties file) will be downloaded and used inside the document. You could see this with https://localhost/webrec/examples/fullScreenDemo.html
3. Specifies font which should be used for all used fonts in the document that are not available at server (see fonts.dir property in application.properties file)
webrec.properties
webrec.properties file allows you to specify your own setup for back-end.
webrec.base.json
webrec.base.json file contains all default properties for front-end. This flie is build-in inside webrec.war file. To customize values inside it, please use webrec.json file which you could place in the /lib/ folder of the Tomcat.
This file contains all properties available for setup, see CIB webRec GET parameters section.
Sample:
{ "onEditorOpen": "", "onDocumentLoad": "", "onActionExec": "", "onDataDirty": "", "filterCIBFields": false, "showHidden": false, "toggleFieldCode": false, "reducePageSpace": false, "maxPagesInRow": 3, "toolbarMinWidth": 75, "enableFileButtons": true, "enableHeader": true, "enableStatus": true, "enableCloseConfirmation": false, "cursorVisibility": true, "hideCursorOnLostFocus": false, "cursorBlinking": true, "readOnlyMode": false, "initialBlockUI": false, "onlyPresetFontOptions": false, "pageDownMovementPercent": 0.5, "css": "", "snippetMode": false, "enablePageBorderLines": true, "resizeCanvasOnZoom": false, "resizeCanvasOnWindowResize": false, "snippetModeMargins": { "left": 0.1, "right": 0.2, "top": 0.1, "bottom": 0 }, "pageViewOffsets": { "leftOffset": 50, "rightOffset": 50, "topOffset": 50, "pageOffset": 50 }, "snippetModeViewOffsets": { "leftOffset": 0, "rightOffset": 0, "topOffset": 0, "pageOffset": 0 }, "drawGridLines": true, "overridePageColor": "", "disabledFonts": "", "initialFont": "", "initialFontSize": 11, "initialPageMargins": { "top": 0.79, "bottom": 0.79, "left": 1.18, "right": 0.59 }, "initialPageSize": { "width": 8.27, "height": 11.69, "isLandscape": false }, "resetLastParagraph": false, "bullets": [ { "fontName": "Symbol", "character": "\uF0B7" }, { "fontName": "Courier New", "character": "\u006F" }, { "fontName": "Wingdings", "character": "\uF0A7" } ] }
webrec.json
webrec.json file allows you to specify your own setup for front-end.
Logging
Log4j2 library is used. Config path WEB-INF/classes/log4j2.xml
<?xml version="1.0" encoding="UTF-8"?>
<Configuration>
<Properties>
<Property name="defaultFormat">%5p %d{dd.MM.yy HH:mm:ss} [%t] [%c{1}:%L] %m%n</Property>
<Property name="logDir">${sys:catalina.base}/logs</Property>
</Properties>
<Appenders>
<Console name="console" target="SYSTEM_OUT">
<PatternLayout pattern="${defaultFormat}" />
</Console>
<File name="webrec" fileName="${logDir}/webrec.${date:yyyy-MM-dd}.log">
<PatternLayout pattern="${defaultFormat}" />
</File>
<File name="webrec-trace" fileName="${logDir}/webrec-trace.${date:yyyy-MM-dd}.log">
<PatternLayout pattern="${defaultFormat}" />
</File>
</Appenders>
<Loggers>
<Root level="ERROR">
<AppenderRef ref="console" />
</Root>
<Logger name="de.cib.webrec" level="WARN" additivity="false">
<AppenderRef ref="console" />
<AppenderRef ref="webrec" />
</Logger>
<Logger name="de.cib.webrec.backend" level="INFO" additivity="false">
<AppenderRef ref="webrec" />
</Logger>
</Loggers>
</Configuration>