# 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`.
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.
An instance of the editor is created in JavaScript by calling `Wodo.createTextEditor()`:
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