Web Viewers (and Editors)

Last modified by cjd on 2015/03/03 12:17

A WebViewer is a standardized HTML5/Javascript gadget which allows you to view or edit files.

The problem it solves

Lets imagine you just invented the greatest in-browser video editor ever. In order for people to use it, you're going to make it play nice with Wordpress, Drupal, Django, XWiki and all of the other frameworks out there. Not only do you have to make it work in each webapp, you have to manually hunt down all of the places where interesting content might be available and add edit buttons.

Now imagine you're developing a webapp. You want users to be able to view and edit rich content in your application. Sure there are plenty of editors but each one is designed by different people with different ideas about how they should get their data and how to save it.

WebViewers approaches this problem by standardizing the way gadgets advertise what they can do and how they accept content to view and edit.

How WebViewers Work

WebViewer gadgets are bundled into .zip archives containing a manifest file which describes the WebViewer to the webapp. When the administrator installs a WebViewer in his or her server, the webapp registers the new WebViewer. Anywhere in the webapp where there is content which can be edited or viewed, the webapp can consult it's registered list of WebViewers to see if there is one appropriate for the content at hand.

If one is found then the webapp may directly activate the WebViewer or add an edit/view button to the webpage to give the option to the user. Once started, a WebViewer gives the webapp information about what type of content it uses, either HTML5 Blobs or plain text content. Then when the webapp puts the content into the WebViewer by calling a setContent() function.

When the user is ready to save the content, they click the save button which is part of the webapp and the webapp does the rest. It asks the WebViewer for it's content by calling the getContent() function, it saves the content and then it closes the WebViewer.


The embedded WebViewer lifecycle diagram above is being displayed by an actual WebViewer. You can see more demonstrations here Demo although note that without registering, you will be limited to viewing of the content, not editing.

WebViewer Internals

WebViewers are based on the Renderjs HTML5 gadget system which allows simple gadget development using only HTML and basic javascript. The following is an example of a simple WebViewer:

   <title>Simple Text Editor WebViewer</title>
   <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />

   <!-- A bootloader which loads the required scripts -->
   <script src="renderjs-stub.js" type="text/javascript"></script>

   <!-- This is how the WebViewer tells it's container webapp how to communicate with it -->
   <!-- This interface is effectively promise that certain methods will be declared -->
   <link rel="http://www.renderjs.org/rel/interface"
         href="http://www.renderjs.org/interface/text-editor" />

   <script type="text/javascript">
      rJS(window).ready(function() {

       // When declared, these methods become available outside of the iframe.
       // cross-iframe traffic is handled transparently by Renderjs.
       rJS(window).declareMethod('setContent', function (value) {
         return document.getElementByTagName('textarea-a').value = value;

        }).declareMethod('getContent', function () {
         return document.getElementByTagName('textarea-a').value;

   <!-- Width and height are set to 100% because -->
   <!-- the webapp is responsible for determining the size of the WebViewer -->
   <textarea id="textarea-a" cols="1" rows="1" style="width:100%;height:100%"></textarea>

This WebViewer would be defined in a file called index.html or similar. It could be hosted on an external website or packaged in the WebViewer content. If it is packaged then it must either carry all of it's dependencies or use a CDN.

The Manifest

After creating your main HTML file, now you need to create your webviewer.json file. This is the manifest which will be read on the server side and used to determine when a WebViewer should be used and what capabilities are available. You can describe your WebViewer in as much or as little detail as you want but you must implement the following values:

  • modelVersion This tells the reader the version of the manifest format, the only version currently is 0.1.
  • actions This is a set of actions which can be done and the types of files which they can be done on. As you can see in the example, this WebViewer claims to be able to edit or view files ending in txt, c, or java.

In addition, you *may* implement the following values which will be used to inform the WebViewer container about your WebViewer.

  • name: the name of the viewer.
  • author: the author of the webviewer.
  • description: Brief description of the webviewer.
  • version: The version of the webviewer.
  • releaseStatus: One of "planned", "alpha", "beta", "released".
  • actions: The webviewer actions and file types.
  • sourceURL: A URL for the repository where the webviewer source code is available.
  • license: The license of the WebViewers wrapper.
  • type: One of "drawing", "business", "office", or "other".
  • originalDeveloper: The developer of the viewer, specifically if different from the packager.
  • viewerLicense: The license under which the viewer is made available.
  • viewerURL: A URL for the website of the original viewer.
  • main: The main entry point into the WebViewer, if this is not defined, it is assumed to be a file called "index.html"

The most minimal valid WebViewer

   "modelVersion": "0.1",
   "name": "textedit",
   "version": "0.1.0",
   "actions": {

A richer form of the same viewer

   "author": "Caleb James DeLisle, XWiki SAS",
   "name": "textedit",
   "description": "Example Text Editing WebViewer",
   "version": "0.1.0",
   "releaseStatus": "beta",
   "actions": {
   "sourceURL": "https://github.com/WebViewers/textedit-webviewer.git",
   "license": "http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html",
   "type": "office",
   "main": "./index.html"

After developing your WebViewer and manifest, you'll need a copy of renderjs-stub.js to startup the WebViewer and you're ready to go. For more information, check out the Tutorial to build a simple WebViewer.

Created by Admin on 2013/09/24 14:51

This wiki is licensed under a Creative Commons 2.0 license
XWiki Enterprise 5.4.4 - Documentation