219 lines
8.6 KiB
Text
219 lines
8.6 KiB
Text
Leaflet platform for LibreOffice On-Line
|
|
========================================
|
|
|
|
This is the client part of LibreOffice On-Line. For the server part, see the
|
|
../loolwsd/README, and install it first.
|
|
|
|
Build dependencies
|
|
------------------
|
|
|
|
First you need to install 'jake'. As root, do:
|
|
|
|
npm install -g jake
|
|
npm install
|
|
|
|
Alternatively, you can use the provided zip (as a normal user):
|
|
|
|
unzip node_modules/modules.zip -d node_modules
|
|
|
|
A third way is to use npm as a user, but set its prefix to a directory where
|
|
you have write access. If you want that, you need to have an ~/.npmrc with the
|
|
line e.g.
|
|
|
|
prefix=/opt/npm
|
|
|
|
Building
|
|
--------
|
|
|
|
As a normal user:
|
|
|
|
jake build
|
|
cd plugins/draw-0.2.4
|
|
jake build
|
|
|
|
Running
|
|
-------
|
|
|
|
To see an example:
|
|
|
|
* run loolwsd, like:
|
|
|
|
./loolwsd --systemplate=${SYSTEMPLATE} --lotemplate=${MASTER}/instdir --childroot=${ROOTFORJAILS}
|
|
|
|
* open debug/document/document_simple_example.html in the browser, like:
|
|
|
|
firefox debug/document/document_simple_example.html
|
|
|
|
* modify the URL to allow loleaflet to connect to a server and open a document
|
|
|
|
http://web-page/document_simple_example.html?file_path=file:///PATH/TO/DOC&host=ws://localhost:9980
|
|
|
|
and you should see the document in the browser. In case anything goes wrong,
|
|
check the loolwsd console for the debugging output.
|
|
|
|
API & events
|
|
------------
|
|
|
|
Search:
|
|
- API:
|
|
map.search(text, [backward])
|
|
- events:
|
|
map.on('search', function (e) {}) (currently only fired when no search result is found) where:
|
|
+ e.originalPhrase = the phrase that has been searched for
|
|
+ e.count = number of results
|
|
|
|
Zoom:
|
|
- API:
|
|
map.zoomIn(amount)
|
|
map.zoomOut(amout)
|
|
map.getMinZoom()
|
|
map.getMaxZoom()
|
|
- events:
|
|
map.on('zoomend zoomlevelschange', function)
|
|
|
|
Edit, view, readOnly:
|
|
- API:
|
|
map.setPermission('edit' | 'view' | 'readonly')
|
|
- events:
|
|
map.on('updatepermission', function (e) {}) where:
|
|
+ e.perm == 'edit' | 'view' | 'readonly'
|
|
|
|
Buttons like Bold, Italic, Strike through etc.
|
|
- API:
|
|
map.toggleCommandState('Bold' | 'Italic' | 'Underline' | 'Strikeout' | 'AlighLeft', etc)
|
|
- events:
|
|
map.on('commandstatechanged', function (e) {}) where:
|
|
+ e.unoCmd == 'Bold' | 'Italic' etc.
|
|
+ e.state = 'true' | 'false'
|
|
|
|
Parts (like slides in presentation, or sheets in spreadsheets):
|
|
- API:
|
|
map.setPart('next' | 'prev' | partNumber)
|
|
map.getPartPreview(id, part, maxWidth, maxHeight) where:
|
|
+ id = the ID of the request so that the response can be identified
|
|
+ maxWidth / maxHeight are the desired dimensions of the preview, a smaller
|
|
image might be returned in order to keep the original ratio of the document
|
|
map.getNumberOfParts()
|
|
map.getCurrentPart()
|
|
- events:
|
|
map.on('updateparts', function (e) {}) where:
|
|
+ e.currentPart is the current part
|
|
+ e.parts == the number of parts that the document has
|
|
+ e.docType == 'text' | 'spreadsheet' | 'presentation' | 'drawing' | 'other'
|
|
+ [e.partNames] if present, part names (e.g. sheet names)
|
|
|
|
Statusindicator (when the document is loading):
|
|
- events
|
|
map.on('statusindicator', function (e) {}) where:
|
|
+ e.statusType = 'start' | 'setvalue' | 'finish' | 'loleafletloaded' | 'alltilesloaded'
|
|
+ e.value == a value from 0 to 100 indicating the status
|
|
if the statusType is 'setvalue
|
|
+ 'loleafletloaded' is fired when the JS code is initialized and the document
|
|
load request is sent and we're waiting for the tiles
|
|
+ 'alltilesloaded' is fired when all newly requested (empty tiles) have been loaded
|
|
it is not fired during pre-fetching and during editing
|
|
|
|
Save:
|
|
- API:
|
|
map.saveAs(url, [format, options])
|
|
|
|
Scroll (the following are measured in pixels):
|
|
- API:
|
|
+ options = An object with members: update (type: Boolean, default: false)
|
|
like {update: true}
|
|
map.scroll(x,y, options)
|
|
+ scroll right by 'x' and down by 'y' (or left and up if negative)
|
|
map.scrollDown(y, options)
|
|
+ scroll down by 'y' (or up if negative)
|
|
map.scrollRight(x, options)
|
|
+ scroll right by 'x' (or left if nevative)
|
|
map.scrollTop(y, options)
|
|
+ scroll to 'y' offset relative to the beginning of the document
|
|
map.scrollLeft(x, options)
|
|
+ scroll to 'x' offset relative to the beginning of the document
|
|
map.scrollOffset()
|
|
+ returns the scroll offset relative to the beginning of the document
|
|
map.getDocSize()
|
|
+ returns the document's size in pixels
|
|
map.getDocType()
|
|
+ returns 'text' | 'spreadsheet' | 'presentation' | 'drawing' | 'other'
|
|
- events
|
|
map.on('docsize', function (e) {}) where:
|
|
+ e.x = document width
|
|
+ e.y = document height
|
|
map.on('updatescrolloffset', function (e) {}) where:
|
|
+ e.x = difference between document's left and current view's left
|
|
(how much has the document been scrolled right)
|
|
+ e.y = difference between document's top and current view's top
|
|
(how much has the document been scrolled down)
|
|
- this event is fired when zooming and the current view is maintained but the
|
|
document shrinks or grow OR when the document is panned OR when the container is resized
|
|
map.on('scrollto', function (e) {}) where:
|
|
+ e.x = view's left position (so that the cursor/search result is in the center)
|
|
+ e.y = view's top position (so that the cursor/search result is in the center)
|
|
map.on('scrollby', function (e) {}) where:
|
|
+ e.x = the amount scrolled to the right (or left if negative)
|
|
+ e.y = the amount scrolled to the bottom (or top if negative)
|
|
|
|
Writer pages:
|
|
- API:
|
|
map.goToPage(page)
|
|
map.getNumberOfPages()
|
|
map.getCurrentPart()
|
|
map.getDocPreview(id, maxWidth, maxHeight, x, y, width, height)
|
|
+ id = the ID of the request so that the response can be identified
|
|
+ maxWidth / maxHeight are the desired dimensions of the preview, a smaller
|
|
image might be returned in order to keep the original ratio of the document
|
|
+ x/y = starting position, where to get the preview from
|
|
|
|
- events
|
|
map.on('pagenumberchanged', function (e) {}) where:
|
|
+ e.currentPage = the page on which the cursor lies
|
|
+ e.pages = number of pages
|
|
+ e.docType = document type, should be 'text'
|
|
|
|
Error:
|
|
- events
|
|
map.on('error', function (e) {}) where
|
|
+ [e.msg] = a message describing the error
|
|
+ [e.cmd] = the command that caused the error
|
|
+ [e.kind] = the kind of error
|
|
|
|
Contributing
|
|
------------
|
|
|
|
Code conventions:
|
|
|
|
* 'jake lint' should be run before commiting
|
|
* files should have unix line terminators (LF)
|
|
* tools to convert files: dos2unix or fromdos
|
|
|
|
Implementation details
|
|
----------------------
|
|
|
|
Loading a document:
|
|
The map should have the following options:
|
|
- center at [0, 0] this will try to place the [0, 0] point in the middle of the
|
|
map, but it will be moved in the top left corner when the maxBounds are set
|
|
- zoom = defautl zoom value, zooming in and out will refer to this value
|
|
- server address
|
|
|
|
The layer (actual document) should have the following options:
|
|
- doc = path to the document that will be loaded
|
|
- useSocket = tells the map the tiles will be received from a websocket
|
|
connection. If this parameter is false, an image will be loaded in each tile
|
|
|
|
How zooming works:
|
|
The zoom level goes from 1 to 20 (those limits can be changed) and the initial
|
|
level is 10, which represents the 100% zoom level. The zoom factor is 1.2
|
|
|
|
Controls are added above the map in a div called "controls" is intended to be used as a toolbar.
|
|
There is no leaflet method of adding them in a separate div, so for now this is done in the html
|
|
document after the map initialization.
|
|
|
|
To enable scrollbars the map is placed above a div that contains a bigger div of
|
|
the document's size (a mock document). So the div under the map gets scrollbars which
|
|
are independent of the map's div, thus enabling us to link them to the map as needed.
|
|
When the user scrolls, the map is panned by the same amount as it would've been scrolled.
|
|
Also, some custom jquery scrollbars are used, to trigger the same scroll events across
|
|
browsers.
|