RealObjects Nimbudocs Editor 3.0.3929_Beta1

Guide: Quick Integration


Introduction

Nimbudocs Editor can easily be integrated into a Web page using JavaScript. There are two basic steps to perform when integrating Nimbudocs Editor:

Integrating the Editor into a Web Page

Nimbudocs Editor comes with a comprehensive JavaScript API designed to allow you to configure and integrate the editor into a web site. In the first step, we will demonstrate how to simply load the editor within a web page without any regards to the loading of content or more advanced integration requirements.

The JavaScript API for Nimbudocs Editor basically allows you to create a JavaScript object containing the editor. You can manipulate the editor's configuration by adding and modifying the objects' properties before it is finally loaded.

To use the JavaScript API, you should import the following library into to the page that will use Nimbudocs Editor.

The placeholder myserver has to be replaced by the URL of the server which runs Nimbudocs Editor.

Importing the Nimbudocs Editor JavaScript library

The following JavaScript library has to be imported in your web site.

<script src="http://myserver/nimbudocseditor.js" type="text/javascript"></script>

Simplest Integration

This is the simplest way to integrate Nimbudocs Editor into your web page.

<script type="text/javascript">
jQuery(window).load(function() {
    NimbudocsEditor.create("nimbuContainer", "http://myserver");
});
</script>

Checking compatibility

If you are not certain whether Nimbudocs Editor is supported by the browser or not, there are two possibilities to define the behavior if the editor is not supported.

Using the return value of the create method, which is false if the editor is not supported:

<script type="text/javascript">
jQuery(window).load(function() {
    var isSupported = NimbudocsEditor.create("nimbuContainer", "http://myserver");
    if(!isSupported) {
        alert("This browser does not meet the requirements of Nimbudocs Editor.");
    }
});
</script>

Or defining the onnotsupported handler:

<script type="text/javascript">
jQuery(window).load(function() {
    options = {
        onnotsupported: function() {
            alert("This browser does not meet the requirements of Nimbudocs Editor.");
        }
    }
    NimbudocsEditor.create("nimbuContainer", "http://myserver", options);
});
</script>

JavaScript only

The previous examples all required your web site to have a container element with the ID "nimbuContainer" which will contain the Nimbudocs Editor instance. It is also possible to dynamically inject this container into the web site when the editor is created using jQuery.

<script type="text/javascript">
jQuery(window).load(function() {
    NimbudocsEditor.create(jQuery("<div>").appendTo("body"), "http://myserver");
});
</script>

Getting the Editor

To get access to the Nimbudocs Editor API, you need the editor object. As the editor loads several resources asynchronously, it is not possible to get the editor object from the create-method. Instead you have to get it via the onready event handler.

The onready event is trigger once the editor is fully loaded and ready to use.

Getting the API Object

jQuery(window).load(function() {
    var nimbudocsEditor;
    var options = {
        onready: function(editor) {
            nimbudocsEditor = editor;
        }
    };
    
    NimbudocsEditor.create("nimbuContainer", "http://myserver", options);
});

Note that the API Object can only be used after, the onready event has been triggered.

Loading Content

There are several ways to load content into the editor. Basically, you can fetch the content either from a URL or you can directly load it as a string.

Load content in the constructor

jQuery(window).load(function() {
    var options = {documentUrl: "documents/myDocument.html"};
    
    NimbudocsEditor.create("nimbuContainer", "http://myserver", options);
});

Remember that the document URL must be accessible by the server.

Load content via the API

var editor;
jQuery(window).load(function() {
    var options = { onready: function(editor) {
            editor.loadDocumentFromUrl("documents/myDocument.html")
        }
    };
    NimbudocsEditor.create("nimbuContainer", "http://myserver", options);
});

Retrieving Content

After editing, you of course want to save it somehow. For this, you may use the respective API method to retrieve the document from the editor as a string. That string can now be saved e.g. to a database, depending on your integration.

Getting the document

editor.fetchDocument().then(function(doc) {
    doSomething(doc);
});

Collaboration

One of the main features of Nimbudocs Editor is the collaboration mode. If you want other people to join your collaboration session, you need to make a web page available to them where they may join.

First, create a new web page. This page has to be accessible from anywhere you want other people to join from.

Creating a collab page

The content of a collab page is basically the same as a normal editor page with additional content. You may want to add the possibility for users to enter their user name or even a collaboration password.

In this example, we have a collab page "collab.html" and also have an HTML input form field with the ID "userName" where users can enter their user name. Also, the editor is not created when the page is loaded but when the "joinButton" is clicked.

<script type="text/javascript">
jQuery("#joinButton").click(function() {
    var userName = jQuery("#userName").val();
    var options = {userName: userName};

    NimbudocsEditor.create("nimbuContainer", "http://myserver", options);
});
</script>

When you have set up your collab page, you have to specify it in your normal Nimbudocs Editor integration. This is done in the constructor by adding a link to the page.

Specifying the collab page

jQuery(window).load(function() {
    var options = {collabUrl: "http://url-to-collab-page/collab.html"};
    
    NimbudocsEditor.create("nimbuContainer", "http://myserver", options);
});

Now when you start a collab session, the editor can create a link for guest users that directly redirects them to the collab page so that they may join your collab session.