From version < 59.2 >
edited by Yann Flory
on 2019/02/12 14:47
To version < 60.1 >
edited by Yann Flory
on 2019/02/12 14:48
< >
Change comment: There is no comment for this version



Last version
... ... @@ -1,1 +1,1 @@
1 -1.16
1 +1.17
Installable with Extension Manager
... ... @@ -1,1 +1,1 @@
1 -No
1 +Yes
Dependency version constraint
... ... @@ -1,0 +1,1 @@
1 +1.4
Extension version
... ... @@ -1,0 +1,1 @@
1 +1.17
Dependency id
... ... @@ -1,0 +1,1 @@
1 +org.xwiki.contrib:xwiki-contrib-netflux
Download URL
... ... @@ -1,0 +1,1 @@
1 +attach:realtime-frontend-1.17.xar
Release Notes
... ... @@ -1,0 +1,1 @@
1 +Fix a JavaScript error with Internet Explorer
... ... @@ -1,0 +1,1 @@
1 +1.17
cogFrontend support for Realtime Applications
Developed by

Yann Flory, Aaron MacSween

Active Installs79
1 Votes
LicenseGNU Lesser General Public License 2.1

Installable with the Extension Manager


Frontend API to easily build realtime applications using the Netflux Backend server.

This application introduces RequireJS modules that you can import to make your application realtime. These modules are :

  • RTFrontend_realtime_input : Main module which creates the realtime instance
  • RTFrontend_toolbar : Create a Toolbar which displays the lag and the user list of your application
  • RTFrontend_interface : Create elements in the UI related to the realtime engine, like the checkbox to allow realtime collaboration
  • RTFrontend_saver : Can be used to add an autosaver in your application (using the XWiki save engine) and can be used to merge the "content" of wiki pages
  • RTFrontend_json_ot : Provide a transform function that you can pass to the realtime_input module
  • RTFrontend_text_patcher : Provide diff tools for string
  • RTFrontend_diffDOM : Provide a diff for DOM elements
  • RTFrontend_errorbox : Can display various messages in popup

Module "RTFrontend_realtime_input" (realtime-input.js)


  • Realtime.start(config) : Start the realtime engine

Configuration values

  websocketURL: "",
  userName: "",
  channel: "",
  cryptKey: "",
  crypto: {},
  onInit: function(info),
  onReady: function(info),
  onLocal: function(), 
  onRemote: function(info),
  onAbort: function(info),
  transformFunction: function (text, toTransform, transformBy)

Crypto object

{ encrypt : function(msg, key) -> return encrypted "msg", decrypt : function(msg, key) -> return decrypted "msg", parseKey : function(key) --> return an object containing a cryptkey {cryptKey : ''} }

Configuration functions (optional but recommended)


  • Called when the user is connected to the channel.
  • Parameter info :
    • realtime : the Chainpad "realtime" object
    • network : the Netflux network which allows you to join other channels
    • channel : the server-side channel ID
    • getLag : function, getLag() returns the lag in milliseconds
    • myID : the server-side user ID, used in all channels
    • userList : an object to pass to the toolbar if you want to use it

Recommendation : If you want a toolbar, you can create it in onInit with Toolbar.create (Cf toolbar documentation).


  • Called when the Chainpad session is fully synced
  • Parameter info :
    • realtime : the Chainpad "realtime" object
    • network : the Netflux network which allows you to join other channels, used in the auto-saver
    • userList : an object to pass to the toolbar if you want to create it with onReady


  • You should use the TextPatcher plugin here and call onLocal when change are made in realtime application
  • Called by RTFrontend when you receive a patch from another user and before passing it to Chainpad. It is called here to make sure Chainpad use your latest content when trying to apply the patch.
  • No parameter


  • Called when a patch is applied to Chainpad. Is should be used to apply the new content to your realtime application
  • Parameter info :
    • realtime : the Chainpad object


  • Called when the user is disconnected from the Backend server
  • Parameter info :
    • reason : reason of the connection failure

Typical usage

  1. load the page assets
  2. infer the websocketURL, channel and encryption key from the page, page hash, or some api
  3. define helper functions
    • locking/unlocking the user interface while disconnected or while the chain is syncing
    • reading the user's interface and updating the realtime document to match
    • integrating changes from the realtime document into the user's interface (without disrupting usage)
  4. integrate helper functions into main hooks
    • onInit
    • onReady
    • onRemote
    • onLocal
    • onAbort
  5. define remaining configuration options
    • transformFunction (optional)
    • crypto module
  6. start realtime
  7. bind to user interface events and fire onLocal to propogate changes into the realtime document


It is highly recommended to create the toolbar in the onInit step, since it contains the required parameters values.

How to use


  • The CSS class of the toolbar element. You can use it to personalize the toolbar so that it fits with your UI

Toolbar.create($container, info.myID, info.realtime, info.getLag, info.userList, config, toolbar_style)

  • $container : the jQuery element that will contain the toolbar (the toolbar will be at the top)
  • myID, realtime, getLag, userList : Cf onInit documentation
  • config : an object used to contain user data
    • userData : an object which maps user IDs to user data like the userName
      • { "userId-1" : { name : "Administrator" }, "userId-2" : { name : "Other User" } }
      • It has to be used if you want to display the user names in the toolbar, otherwise leave it empty
  • toolbar_style : HTML text element that will be inserted in the toolbar and can be used to changed its style
    • ""



  • LOCALSTORAGE_DISALLOW : If you want the users to be able to disallow the realtime engine, you have to specify here a key which will store the state of the engine in the Local Storage

Interface.createAllowRealtimeCheckbox(allowRealtimeCbId, checked, label)

  • Creates a checkbox to disable realtime in that wiki page
  • allowRealtimeCbId : the ID of the checkbox
  • checked : the initial state
  • Label : the label of the ckeckbox


  • Show or Hide the "autosave" input created by XWiki. It should be hidden if you intend to use the Saver module


  • Set the value of "LOCALSTORAGE_DISALLOW"
  • state : boolean


  • Get the value of "LOCALSTORAGE_DISALLOW"


Documentation on Github

This extension is used by RtWiki (versions > 1.18) and RtWysiwyg (versions > 1.16).

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager). Note that installing Extensions when being offline is currently not supported and you'd need to use some complex manual method.

You can also use the following manual method, which is useful if this extension cannot be installed with the Extension Manager or if you're using an old version of XWiki that doesn't have the Extension Manager:

  1. Log in the wiki with a user having Administration rights
  2. Go to the Administration page and select the Import category
  3. Follow the on-screen instructions to upload the downloaded XAR
  4. Click on the uploaded XAR and follow the instructions
  5. You'll also need to install all dependent Extensions that are not already installed in your wiki

Release Notes



Fix a JavaScript error with Internet Explorer


Make the warnings and errors visible in fullscreen mode.
Auto-accept a realtime request after 30s if the user doesn't answer.
Display an error when a user is trying to save while someone else has made changes to the document.


Fix cache issues (cache busting)
Fix an issue with a warning displayed when leaving a page in edit mode (Firefox)


RTWYSIWYG-77 Realtime editing shreds articles during save if only a section of the page is edited
RTWYSIWYG-76 Display a warning message in case of concurrent offline editing
RTWYSIWYG-75 Request a realtime session when a document is locked


RTWYSIWYG-73 Incompatibility between 9.8.1 and Realtime package 


RTWYSIWYG-71 Avoid issue with tomcat7, xwiki 9.x and response.getOutputStream 


Fix issue with translated documents
Added French Translations


Updated chainpad and netflux-chainpad to fix realtime bugs


Add some debugging data when an error occurs.
Ability to disable content merges when the realtime documents are saved


Enable the user avatars by default in the realtime applications


Use reconnecting-websocket to re-enable editing when reconnecting after a connection failure (client-side or server-side)


Prevent users from saving a document multiple times at once.


Fix save & merge issues
Ability to use the classic XWiki save when "Allow Realtime Collaboration" is unchecked


Fix an issue where realtime applications were not able to initialize if the toolbar could not be displayed.
Use dependencies shared with Cryptpad instead of duplicated code.

This version introduces save/merge issues fixed in version 1.5. It is recommended to upgrade


Update the toolbar style
Make the event handler more generic when clickable usernames in the toolbar are available


Fix an invalid image displayed when a user was using the default avatar.


Dependencies for this extension (yannflory:realtime-netflux-frontend 1.16):

Dependencies for this extension (yannflory:realtime-netflux-frontend 1.17):

Get Connected