This documentation describes the configuration and deployment of the Congree Web Interface.

Contents

• Congree Web Interface Introduction
• Prerequisites
• Preface
• Integration
  • Loading CWI
  • Instantiating CWI
  • Further features
  • Full example Dynamic mode
  • Full example Fixed Mode
  • Required changes in Host
  • Option Documentation
  • Adjust cwi-integration.loader
  • Requirements
  • Using CWI as sliding overlay
• Verification
• Congree Web Interface Deployment

Legend

Congree Web Interface Introduction

Congree Web Interface (short: CWI) allows the integration of Congree functionality into third party websites and web applications ("the Host").

Prerequisites

CWI requires the Congree Bulk Check Service to function. If you are unsure what that is or if you have it installed and licensed, please consult with your Congree representative.

CWI requires HTTPS to be used. If you do not want to use HTTPS some manual configuration is required. Please consult with your Congree representative.

Congree Web Interface Deployment

To be able to understand the following steps, you need to know how Congree Deployment Assistant is used. Find the manual here: Congree Installations- und Platform-Guide resp. Congree Installation and Platform Guide.

Go to Server Configuration and add Congree Bulk Check Service to the Host:

For the Congree Web Interface to work, you need to install at least the following sub components :

• Language Check
• Terminology
• Congree Web Interface

Term Candidates has no effect on the Congree Web Interface since this feature is not supported but it might be used by other integrations using Congree Bulk Check Service.

Save your configuration and install on the Host.

Verification

After the installation via Congree Deployment Assistant has finished successfully, enter the following URLs in a browser where [hostname] is the Host.

https://[hostname]/CongreeWebInterface/cwi-integration.js

If you get some JavaScript Code or are asked to download a js file, this test has been successful

https://[hostname]/CongreeBulkCheckService/BulkCheckService.svc?singleWsdl

If you get some XML, this test has been successful.

If you get a security warning, there might be something wrong with your SSL certificates.

Please contact your administration in that case. Repeat this test from a client machine to verify it does not only work on the Host itself.

Integration

• Loading CWI
• Instantiating CWI
• Further features
• Full example Dynamic mode
• Full example Fixed Mode
• Required changes in Host
• Option Documentation
• Adjust cwi-integration.loader
• Requirements
• Using CWI as sliding overlay

Requirements

CWI can work in two different display modes:

1. Fixed mode: In this mode, the CWI sidebar is always visible. The host must provide CWI with a div element. This element must exist at the time of the sidebar initialization. The Host is responsible for styling the div, i.e. to give it the correct size and placement. CWI will not re-style it.
2. Dynamic Overlay mode: In this mode, the CWI sidebar will be shown in an overlay. The Host is not required to provide any elements, however, the Host is required to trigger the showing and hiding of the overlay.

To configure the display mode, you have to adjust the cwi-integration.loader.

The CWI supports an integrated working mode: CWI will connect to one or multiple editors in the Host. These editors needs to exist when the sidebar is being initialized.

Important:

When you update Congree, the adjusted files are set back to default. Please copy the adjusted files, store them in another location and put them back in their folder after a Congree update.

Adjust cwi-integration.loader

You can find the cwi-integration.loader in *C:\ProgramFiles (x86)\Congree Language Technologies GmbH\Congree Bulk Check Service\Congree Web Interface*. In this folder, you can find three files which can be adjusted.

If you are using the fixed display mode, you have to modify the file C:\Program Files (x86)\Congree Language Technologies GmbH\Congree Bulk Check Service\Congree Web Interface\cwi-integration.loader.sample-sidebar.js

For the dynamic display mode, modify the file C:\Program Files (x86)\Congree Language Technologies GmbH\Congree Bulk Check Service\Congree Web Interface\cwi-integration.loader.sample-overlay.js.

Rename the file to contain your host applications name, e.g. cwi-integration.loader.cms.js.

Open the desired file and change the body of the loadSidebar function to your needs.

By way of changing the body of the loadSidebar function,

• You define the field IDs of the
  containers whose content is to be checked by the Congree Web Interface.
• You define which document-specific rule set is used by default by the Congree Web Interface.
• You can adjust the back end URLs, if neccessary.
• You deliver the login information for the Congree Web Interface, like user name and password.

Important

Each instance of the Congree Web Interface needs its own user information. Multiplexing is not possible, see the Congree Bulk Check Service documentation:
The Bulk Check API

For more details, see Option Documentation.

Option Documentation

Congree.Sidebar

The following options are available when initializing the Congree Sidebar:

Option		Description	Values
serverAddress		This is the address at which the Congree Bulk Check Service is available.
authentication		This is the authentication configuration. It is an object whose structure is described below.	see table Authentication configuration object
initialLanguage		The two letter iso code of the language that the user interface should be shown in.	"de" "en"
editors		(Optional, but strongly recommended) This is an array of editor adapters for the editor elements that CWI should work with. If it is not specified, CWI shows its own editor. An editor adapter is a class that specifies how CWI needs to interact with the editor. Congree currently provides adapters for the following editors: see "values" Usage is like this: Congree.AdapterFor.<editor name>(<CSS Selector>, <editor name>) The CSS selector that is passed as the argument is a specification for which editors CWI should connect to. For example, you could have a configuration like so: ..., editors: [Congree.AdapterFor.TextInput('textarea')], ... This would connect CWI to all textarea elements on the page - no matter when they appear. As soon as a new textarea element is added to the page, CWI will connect to it. The second parameter "editor name" is optional. It will be used as the name of the editor when transmitting the text to the Congree backend. It can be used to provide context to the checked text. This context can in turn be used to configure different rules for different editors. As this name will be used directly in XML, it needs to be a valid as an XML tag name. So, basically only alphanumerical characters, where the first character must not be a number.	"TextInput": This is used for normal text input controls like <input type="text"> and <textarea>. "TinyMce3": This is used for TinyMCE editors of version 3. Confluence currently uses this version of the TinyMCE editor "TinyMce4": This is used for TinyMCE editors of version 4. "CKEditor4": This is used for CKEditor editors of version 4.
requestValidTerms		This option triggers to display valid terms or not. Possible values are true or false.
editorElementIds		This option is outdated, please do not use it anymore This is an array of the IDs of the editor elements that CWI works with. Optional. If not specified, CWI shows its own editor.
initialRuleSetName		This is the rule set that should be displayed by default.
bulkCheckServicePath		This lets you specify a different URL for the Bulk Check Service (CongreeBulkCheckService/BulkCheckService.svc) if you cannot use the default one. Contact Congree before using this.

Authentication configuration object

Option	Description
loginType	Specifies how the user is logged in. Possible values are: "cms" "usernamePassword"
servicePath (Optional)	Specifies the path to the authentication service. If loginType is "usernamePassword" this should be the same as bulkCheckServicePath. If loginType is "cms" this should point to the authentication service of the Congree Bulk Check Service. If this is not specified, it will default to: loginType = "cms": CongreeBulkCheckService/BulkCheckAuthenticationService.svc loginType = "usernamePassword": CongreeBulkCheckService/BulkCheckService.svc
userName	The username to log in
password	This is the password for the Congree user. Only for loginType = "usernamePassword"
thirdPartySystemsIdentifier	The identifier of the system. Default: "CWI". Only for loginType = "cms"
accessTokenURL	The URL of the Congree Identity Server. Here the CWI gets the token for REST API requests.

Congree.Sidebar.show

This method is only relevant in the Fixed display mode.

The show function on the sidebar object requires one parameter: The ID of the div element that will contain the Congree Sidebar.

Congree.Sidebar.asOverlay

This method is only relevant in the Overlay display mode.

The following options are available when calling asOverlay on the sidebar object:

Option	Description
overlayPosition	The position of the overlay. Can be "right" or "left"

Congree.Sidebar.logout

This JS function can be used to logout the current user programmatically.

Required changes in Host

Include the cwi-integration Javascript file:

<script src="https://[hostname]/CongreeWebInterface/cwi-integration.js"</script>

Create a Javascript function that initializes and shows the Congree Sidebar:

Example 1: Authentication with Username and Password

<script type="text/javascript">

var congree = window.Congree || {};
window.Congree = congree;

congree.loadSidebar = function (username, password) {
    congree.sidebar = new Congree.Sidebar({
        serverAddress: "[hostname]",
        authentication: {
            userName: "[username]",
            password: "[password]",
			accessTokenURL: "[Congree Identity Server URL]",
            loginType: "usernamePassword"
        },
        initialRuleSetName: "[ruleset]”,
        editors: [
            Congree.AdapterFor.TextInput('textarea:not(.cke_source)'),
            Congree.AdapterFor.TextInput('input[type="text"]'),
            Congree.AdapterFor.TinyMce4('.tinymce4', 'tinymce'),
            Congree.AdapterFor.CKEditor4('.ckeditor4')
        ]
    });
    congree.sidebar.show("congreeSidebar");
};

</script>

Include the CWI loader javascript file:

 <script src="https://[hostname]/CongreeWebInterface/cwi-integration.loader.sample-sidebar.js"</script>

Example 2: Authentication via Trust CMS

<script type="text/javascript">

var congree = window.Congree || {};
window.Congree = congree;

congree.loadSidebar = function (username, password) {
    congree.sidebar = new Congree.Sidebar({
        serverAddress: "[hostname]",
        authentication: {
            userName: "SamWon",
            password: "[REST API secret]",
            loginType: "cms",
			accessTokenURL: "[Congree Identity Server URL]",
            thirdPartySystemsIdentifier: "Confluence"
        },
        initialRuleSetName: "[ruleset]”,
        editors: [
            Congree.AdapterFor.TextInput('textarea:not(.cke_source)'),
            Congree.AdapterFor.TextInput('input[type="text"]'),
            Congree.AdapterFor.TinyMce4('.tinymce4', 'tinymce'),
            Congree.AdapterFor.CKEditor4('.ckeditor4')
        ]
    });
    congree.sidebar.show("congreeSidebar");
};

</script>

Include the CWI loader javascript file.

<script src="https://[hostname]/CongreeWebInterface/cwi-integration.loader.cms.js"</script>

Call Congree.loadSidebar() at a time when the specified elements are created.

If the username and password for Congree depend on a login of the host application, they can be supplied as parameters to that function.

The

Info:

You can configure the REST API Secret in %\Program Files\Congree Language Technologies GmbH\Congree Identity Server\appsettings.json% under:

    "TrustCMSSecret": ""

The REST API Secret must be encoded in Base64.

Only relevant for dynamic display mode:

Call Congree.SidebarOverlay.show(), when the Congree Overlay should be shown, e.g. in the focus event of your editor elements.

Call Congree.SidebarOverlay.hide(), when the Congree Overlay should be hidden, e.g. in the blur event of your editor elements.

Full example Fixed Mode

<!DOCTYPE html>
 <html lang="en">
 <head>
     <meta charset="UTF-8">
     <title>3rd Party App</title>
     <style>
         html {
             box-sizing: border-box;
         }
 
         *, *:before, *:after {
             box-sizing: inherit;
         }
 
         * {
             margin: 0;
             padding: 0;
         }
 
         body {
             font: 14px/1.1 Helvetica, Sans-Serif;
             position: absolute;
             left: 0;
             right: 0;
             top: 0;
             bottom: 0;
             height: 100%;
             width: 100%;
         }
 
         #congreeSidebar {
             width: 350px;
             height: 100%;
             border-left: 2px solid grey;
             border-top: 0;
             border-bottom: 0;
             border-right: 0;
             position: absolute;
             top: 0;
             right: 0;
         }
 
         #body-container {
             width: calc(100% - 350px);
         }
 
         #editor1 {
             width: 90%;
             height: 500px;
             margin-bottom: 15px
         }
 
         #editor2 {
             width: 90%;
             margin-bottom: 15px
         }
 
         #editor3 {
             width: 90%;
             height: 500px;
             margin-bottom: 15px
         }
     </style>
 </head>
 <body onload="Congree.loadSidebar()">
 <div id="congreeSidebar"></div>
 <div id="body-container">
     <h1>Some UI from the host application</h1>
     <textarea id="editor1">Das ist ein Txt mi Feler</textarea>
     <input type="text" id="editor2" value="Das snd Headphones."/>
     <textarea id="editor3">Hier sind mine Kopfhrer.</textarea>
 </div>
 <script type="text/javascript" src="https://[hostname]/CongreeWebInterface/cwi-integration.js"></script>
 <script type="text/javascript" src="https://[hostname]/CongreeWebInterface/cwi-integration.loader.sample-sidebar.js"></script>
 </body>
 </html>

Full example Dynamic Mode

<!DOCTYPE html>
 <html lang="en">
 <head>
     <meta charset="UTF-8">
     <title>3rd Party App</title>
     <style>
         html {
             box-sizing: border-box;
         }
 
         *, *:before, *:after {
             box-sizing: inherit;
         }
 
         * {
             margin: 0;
             padding: 0;
         }
 
         body {
             font: 14px/1.1 Helvetica, Sans-Serif;
             position: absolute;
             left: 0;
             right: 0;
             top: 0;
             bottom: 0;
             height: 100%;
             width: 100%;
         }
 
         #body-container {
             width: calc(100% - 350px);
         }
 
         #editor1 {
             width: 90%;
             height: 500px;
             margin-bottom: 15px
         }
 
         #editor2 {
             width: 90%;
             margin-bottom: 15px
         }
 
         #editor3 {
             width: 90%;
             height: 500px;
             margin-bottom: 15px
         }
     </style>
 </head>
 <body onload="Congree.loadSidebar()">
 <div id="body-container">
     <h1>Some UI from the host application</h1>
     <textarea id="editor1" onfocus="show()" onblur="hide()">Das ist ein Txt mi Feler</textarea>
     <input type="text" id="editor2" value="Das snd Headphones." onfocus="show()" onblur="hide()"/>
     <textarea id="editor3" onfocus="show()" onblur="hide()">Hier sind mine Kopfhrer.</textarea>
 </div>
 <script type="text/javascript" src="https://[hostname]/CongreeWebInterface/cwi-integration.js"></script>
 <script type="text/javascript" src="https://[hostname]/CongreeWebInterface/cwi-integration.loader.sample-overlay.js"></script>
 <script type="text/javascript">
     function show() {
         Congree.SidebarOverlay.show();
     }
     function hide() {
         Congree.SidebarOverlay.hide();
     }
 </script>
 </body>
 </html>

Troubleshooting