libreoffice-online/loleaflet/README

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('searchnotfound', function)

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
    - 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'
            + e.value == a value from 0 to 100 indicating the status
              if the statusType is 'setvalue

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.