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

enableFileButtons

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

enableHeader

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

reducePageSpace

Reduces page margins and minimum space between pages to 2-4 pixels to reduce screen space used.

default: false

Boolean

maxPagesInRow

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)

enableCloseConfirmation

Forces CIB webRec to show a dialog when window is closed or file is opened with unsaved changes.

default: false

Boolean

css

If set, includes CSS from provided link into the editor (see CIB webRec CSS customization).

default: ""

String

onEditorOpen

If set, provided callback name will be run when editor loading is done (see CIB webRec JS API).

default: ""

String

onDocumentLoad

If set, provided callback name will be run when document loading is done.

default: ""

String

onActionExec

If set, provided callback name will be run when an action is done.

default: ""

String

onDataDirty

If set, provided callback name will be run when the document is changed, reverted or saved.

default: ""

String

filterCIBFields

If true, CIB fields will be filtered from editor when RTF document is loaded.

default: false

Boolean

toggleFieldCode

If true, fields will be toggled from result state to code state when RTF document is loaded.

default: false

Boolean

resetLastParagraph

If true, the last pilcrow will be removed. This parameter is used for snippet editing.

default: false

Boolean

initialPageSize.width
initialPageSize.height
initialPageSize.isLandscape

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

 

initialPageMargins

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

initialFont

If set, specifies initial font name of the paragraph for the new document being created in CIB webRec.

default: 'Times New Roman'

String

initialFontSize

If set, specifies initial font size of the paragraph for the new document being created in CIB webRec.

default: 11

Number

cursorVisibility

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

hideCursorOnLostFocus

Activates or disables cursor visibility on lost/gain input focus in the webRec frame.

default: false

Boolean

cursorBlinking

If set, the cursor will blink.

default: true

Boolean

readOnlyMode

If set, specifies webRec UI will not allow edit opened document. Also there will be disabled document save possibility.

default: false

Boolean

initialBlockUI

If set, starts webRec with blocked UI. To unblock it integrator should call webRec.blockUI(false)

default: false

Boolean

bullets

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": [
    {
      "fontName": "Symbol",
      "character": "\uF0B7"
    },
    {
      "fontName": "Courier New",
      "character": "\u006F"
    },
    {
      "fontName": "Wingdings",
      "character": "\uF0A7"
    }
  ]

JSON

snippetMode

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

enablePageBorderLines

Enables page border line in disaplying of the document. When enableSnippetMode() is called, this parameter by default is set to false.

default: true

Boolean

resizeCanvasOnZoom

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

resizeCanvasOnWindowResize

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

overridePageColor

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

onlyPresetFontOptions

Disables editing possibility for font and font size combo boxes on webRec toolbar and insde Font properties dialog.

default: false

Boolean

snippetModeMargins

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)
snippetModeMargins.right = 0.2 (inches)
snippetModeMargins.top = 0.1 (inches)
snippetModeMargins.bottom = 0 (inches)

Object

snippetModeViewOffsets

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)
snippetModeViewOffsets.rightOffset = 0 (pixels)
snippetModeViewOffsets.topOffset = 0 (pixels)

Object

pageViewOffsets

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)
pageViewOffsets.rightOffset = 50 (pixels)
pageViewOffsets.topOffset = 50 (pixels)
pageViewOffsets.pageOffset = 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 API
Toolbars 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:

the promise object


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 dialogs

Shortcuts 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:

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"&amp;onDocumentLoad="onDocumentLoaded"&amp;
enableHeader=false&amp;enableFileButtons=false&amp;reducePageSpace=true&mpinitialFont="Arial"
&amp;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:

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"}

 

Fonts.defaultFontName

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>