Actualización
This commit is contained in:
149
main/inc/lib/javascript/wodotexteditor/HOWTO.md
Normal file
149
main/inc/lib/javascript/wodotexteditor/HOWTO.md
Normal file
@@ -0,0 +1,149 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user