HOWTO use the Wodo.TextEditor component

Requirements

The Wodo.TextEditor component needs to be included in webpages served by a webserver, as its code uses XHR requests to fetch more data/files where needed.

Creating the Editor

The file which needs to be included to create a Wodo.TextEditor is wodotexteditor.js.

<head>
<!-- ... -->

<script src="wodotexteditor/wodotexteditor.js" type="text/javascript" charset="utf-8"></script>

<!-- ... -->
</head>

In the body of the HTML there needs to be set a div element which should hold the editor, with a unique id value and a size as wanted.

<body>
<!-- ... -->

<div id="editorContainer" style="width: 600px;height: 600px;"></div>

<!-- ... -->
</body>

An instance of the editor is created in JavaScript by calling Wodo.createTextEditor():

<script type="text/javascript">
// ...

Wodo.createTextEditor('editorContainer', {
    allFeaturesEnabled: true,
    userData: {
        fullName: "Tim Lee",
        color:    "blue"
    }
}, function (err, editor) {
    if (err) {
        // something failed unexpectedly, deal with it (here just a simple alert)
        alert(err);
        return;
    }
    editor.openDocumentFromUrl("document.odt", function(err) {
        if (err) {
            // something failed unexpectedly, deal with it (here just a simple alert)
            alert("There was an error on opening the document: " + err);
        }
    });
});

// ...
</script>

See the example file texteditor.html how the above can be applied.

Once the editing should be done, the current state of the document can be retrieved from the editor by calling editor.getDocumentAsByteArray():

editor.getDocumentAsByteArray(function (err, odtFileAsByteArray) {
    if (err) {
        // something failed unexpectedly, deal with it (here just a simple alert)
        alert(err);
        return;
    }
    // now do something with odtFileAsByteArray (is of type Uint8Array)
});

See the example file localfileeditor.js how the above can be applied.

To track if the user has edited the document after it was loaded or since it has been synchronized the last time, the editor has a property "documentModified". The current state of the document can be set as unmodified by calling

editor.setDocumentModified(false);

e.g. when the document has been synchronized somewhere. To query if the document is modified call isDocumentModified() on the editor object,

if (editor.isDocumentModified()) {
    // ask the user if the changes should be discarded
}

See the example file localfileeditor.js how the above can be applied.

When calling Wodo.createTextEditor(), the second parameter allows to configure the editor. See the included API dox for the possible parameters.

Examples

For inspiration there are three examples included how to use the Wodo.TextEditor component.

Simple Editor

The file texteditor.html holds a very simple example of creating an editor and loading a given file into it, so that it can be edited. It does not deal with getting the result and storing it somewhere.

Editor which lets user edit files from local filesystem

The file localeditor.html extends the simple editor example above by adding two things: support for loading files from the local filesystem into the editor and support for storing the current state of the edited document using the "saveAs" feature of browsers.

The example consists of the files localfileeditor.js and localeditor.html. Additionally it uses FileSaver.js, which is a polyfill for browsers not yet supporting "saveAs".

Editor which lets user review files from local filesystem

The file revieweditor.html is a variant of the editor for files of the local filesystem: it sets the editing modus to "review", which limits the user to only add, edit and remove own annotations, but not change anything else in the document.

The example consists of the files revieweditor.js and revieweditor.html. Additionally it uses FileSaver.js, which is a polyfill for browsers not yet supporting "saveAs".

External Resources

ODF documents can reference external resources, like images or fonts, insteading of embedding them. This is done to keep the size of the files smaller. It makes a lot of sense for resources which are shared by many documents, like usually the fonts used. Of course this requires that those resources are available on the system where the document is rendered, e.g. by serving them on request from a central server.

The Wodo.TextEditor currently supports the central serving of fonts.

Fonts

Font files on the server are registered to the Wodo.TextEditor by listing them in a CSS file. Each font is registered with a normal @font-face CSS rule. The file is name fonts.css and placed in the subdirectory fonts of the resources directory. This file will be automatically read by the Wodo.TextEditor. The font files can be put whereever it suits, as long as their location is correctly given in fonts.css.

It surely makes sense to place the fonts into the same directory like "fonts.css", unless also used for other purposes. (TODO: instead of a shared "resources" path perhaps there should be an entry just for fonts/fonts.css)

Example:

The Wodo.TextEditor installation is in the path /wodotexteditor of the webserver. This requires that the fonts files are listed in /wodotexteditor/resources/fonts/fonts.css. There is a font with the font-family name "Gentium Basic" in file name GenBasR.ttf. The file is placed in /wodotexteditor/resources/fonts. So it will be listed in fonts.css as

@font-face {
    font-family: "Gentium Basic";
    src: url("./GenBasR.ttf") format("truetype");
    font-weight: normal;
    font-style: normal;
}

F.A.Q

Why is a document which is hosted on another server not loading?

Web pages with the Wodo.TextEditor must be served with the flag to allow its code to access code from servers in other domains. See https://en.wikipedia.org/wiki/Cross-origin_resource_sharing

HOWTO.md 6.3 KB Историја Датотека