Dialob Client Embedding

Dialob client UI is designed to be simply embeddable to any website regardless of UI framework used.

Minimum setup

Here is a minimum HTML boilerplate needed to get a dialob session embedded

<DOCTYPE !html>
<html>
<head>
  <title>Dialob</title>
  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"/>
  <meta charset="UTF-8"/>
  <script type="text/javascript" src="https://unpkg.com/react@15.4.2/dist/react.js"></script>
  <script type="text/javascript" src="https://unpkg.com/react-dom@15.4.2/dist/react-dom.js"></script>
  <script type="text/javascript" src="https://unpkg.com/dialob-fill-ui@latest/dist/javascript/dialob.js"></script>
  <link type="text/css" rel="stylesheet" href="https://unpkg.com/dialob-fill-ui@latest/dist/css/dialob.min.css"/>
  <link type="text/css" rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.6.3/css/font-awesome.min.css"/>
</head>
<body>
  <div id="dialob-app-content"></div>
</body>
<script>
  var options = {
    url: 'http://localhost:8080/session/socket/df1c54ea81c5d3c8cfe400db3d012d17',
  };
  window.Dialob.renderDialob(document.getElementById('dialob-app-content'), options);
</script>
</html>
  • React and Dialob libraries are fetched from CDN.
  • <div id="dialob-app-content></div> is a DOM node where Dialob is rendered.
  • window.Dialob is Dialob's global object, it has method renderDialob(DOMNode, options).
  • Hosting multiple instances of dialob clients in different DOM nodes is supported.

Configuration options

Full set of configuration options

{
  url: 'http://localhost:8080/session/socket/df1c54ea81c5d3c8cfe400db3d012d17',
  restUrl: 'http://localhost:8080/session/dialob/df1c54ea81c5d3c8cfe400db3d012d17',
  reviewUrl: 'http://localhost:8080/review/df1c54ea81c5d3c8cfe400db3d012d17',
  connectionMode: 'websocket',
  submitCallback: submitCallbackFunction,
  customComponentCreator: componentCreatorFunction,
  csrf: {
    headerName: 'x-csrf-token',
    token: '8d594121-4b27-4665-b22c-c2d12a64c247'
  }
}

Attributes

  • url WebSocket URL to Dialob session, used if connectionMode is websocket.
  • restUrl REST URL to Dialob session, used if connectionMode is rest.
  • reviewUrl If set, Dialob shows this link to user when session is completed.
  • connectionMode Connection mode: websocket (Default) or rest
  • submitCallback (Optional) An user-supplied javascript function that takes one argument (context) that is called when session is completed. (See below)
  • customComponentCreatpr (Optional) An user-supplied javascript function that can override and extend question item rendering. (See below)
  • csrf (Optional) Cross-Site Request Forgery prevention token. headerName HTTP header is populated with token value for every HTTP request to Dialob back-end

Completion callback function

Example setup:


  function customSubmitCallback(context) {
    console.log('This session has been completed :', context.questionnaireId);
  }

  var options = {
    url: 'http://localhost:8080/session/socket/df1c54ea81c5d3c8cfe400db3d012d17',
    submitCallback: customSubmitCallback
  };
  window.Dialob.renderDialob(document.getElementById('dialob-app-content'), options);

If Dialob session gets completed successfully (approved by server), customSubmitCallback function is called with a context object. Context object attributes:

  • questionnaireId Dialob session identifier that was completed

Custom components

User can override or extend the rendering of built-in question components by provinding a custom component creator function. This function should return a React component in case desired conditions are met.

Example:

  function myComponentCreator(item, delegate) {
    if (!item) {
      return delegate(item);
    }
    let id = item[0];
    var jsItem = item[1].toJS();
    if (jsItem.type === 'text' && jsItem.className && jsItem.className.includes('my-text-field')) {
      return <MyTextField key={id} question={item}/>;
    }
    return delegate(item);
  }

  var options = {
    url: 'http://localhost:8080/session/socket/df1c54ea81c5d3c8cfe400db3d012d17',
    customComponentCreator: myComponentCreator
  };
  window.Dialob.renderDialob(document.getElementById('dialob-app-content'), options);

This function gets two paramters, item - Immutable.js structure for item definition, and delegate - original component creator function. Call this delegate in default conditions to include original set of components provided by Dialob. See Question type documentation to learn about possible attributes for an item.

This example renders <MyTextField> React component in case item type is text and it has style class my-text-field set, otherwise it uses original components.

Code for a complete example is here.

results matching ""

    No results matching ""