150 lines
6.3 KiB
Markdown
150 lines
6.3 KiB
Markdown
# 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`](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`](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`](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`](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`](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`](localfileeditor.js) and [`localeditor.html`](localeditor.html). Additionally it uses [`FileSaver.js`](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`](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`](revieweditor.js) and [`revieweditor.html`](revieweditor.html). Additionally it uses [`FileSaver.js`](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
|
|
|
|
1. 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
|