Realtime Netflux Frontend

Version 12.3 by Yann Flory on 2016/07/25 18:04

cogFrontend support for Realtime Applications
TypeXAR
CategoryAPI
Developed by

Yann Flory, Aaron MacSween

Rating
0 Votes
LicenseGNU Lesser General Public License 2.1

Description

https://raw.githubusercontent.com/xwiki-labs/xwiki-labs-logo/master/projects/xwikilabs/xwikilabsproject.png

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

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

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.

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

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.5):

Get Connected