Realtime Netflux Frontend
Frontend support for Realtime Applications |
Type | XAR |
Category | API |
Developed by | |
Rating | |
License | GNU Lesser General Public License 2.1 |
Table of contents
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
- load the page assets
- infer the websocketURL, channel and encryption key from the page, page hash, or some api
- 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)
- integrate helper functions into main hooks
- onInit
- onReady
- onRemote
- onLocal
- onAbort
- define remaining configuration options
- transformFunction (optional)
- crypto module
- start realtime
- 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
- userData : an object which maps user IDs to user data like the userName
- 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
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:
- Log in the wiki with a user having Administration rights
- Go to the Administration page and select the Import category
- Follow the on-screen instructions to upload the downloaded XAR
- Click on the uploaded XAR and follow the instructions
- You'll also need to install all dependent Extensions that are not already installed in your wiki
Release Notes
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.8):