CIB webRec technical documentation

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.

  "bullets": [
    {
      "fontName":  "Symbol",
      "character": "\uF0B7"
    },
    {
      "fontName": "Courier New",
      "character": "\u006F"
    },
    {
      "fontName":  "Wingdings",
      "character":  "\uF0A7"
    }
  ]

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

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

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:

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:

• 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"&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:

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

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>