eletrotupi

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
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
cirandas.net
