Frontend support for Realtime Applications

Description

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)

Methods

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

onInit

• 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).

onReady

• 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

onLocal

• 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

onRemote

• 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

onAbort

• 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

Toolbar

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

How to use

Toolbar.TOOLBAR_CLS

• 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
  • "<style>"+TOOLBAR_CLS+" { color: #666; }</style>"

Interface

Interface.setLocalStorageDisallow(LOCALSTORAGE_DISALLOW)

• 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

Interface.setAutosaveHiddenState(state)

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

Interface.realtimeAllowed(state)

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

Interface.realtimeAllowed()

• Get the value of "LOCALSTORAGE_DISALLOW"

TextPatcher

Documentation on Github

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

v1.22

This new version brings compatibility with XWiki 11.2+'s new features for conflict and merge.
It removes the internal conflict checking which brought an issue when adding a image to the page, which is better handled by XWiki's new core feature.

RTWYSIWYG-84 Realtime incompatibility with new version of CKEditor
RTWYSIWYG-83 Compatibility of Realtime with new conflict and merge features in XWiki 11.2+
RTWYSIWYG-81 Deactivate conflict protection in realtime module

v1.21

Fix a save&view error in wiki edit mode

v1.20

Fix parse errors with the latest version of XWiki
Fix conflicts with RTWiki and RTForm (experimental)

v1.19

Fix 404 error when trying to keep the remote changes after a merge conflict
Fix an error with the version not updating in realtime after a save and view
Fix UI issues with warning messages half hidden in fullscreen mode

v1.18

Add more checks to make sure the document can't be saved with outdated content

v1.17

Fix a JavaScript error with Internet Explorer

v1.16

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.

v1.15

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

v1.14

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

v1.13

RTWYSIWYG-73 Incompatibility between 9.8.1 and Realtime package 

v1.12

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

v1.11

Fix issue with translated documents
Added French Translations

v1.10

Updated chainpad and netflux-chainpad to fix realtime bugs

v1.9

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

v1.8

Enable the user avatars by default in the realtime applications
Fix RTWYSIWYG-62

v1.7

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

v1.6

Prevent users from saving a document multiple times at once.

v1.5

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

v1.4

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.

v1.3

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

v1.2

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

Dependencies

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

• org.xwiki.contrib:xwiki-contrib-netflux 1.5