Files
online/loleaflet
Weblate 2aecaeef27 update translations
LibreOffice Online/android-app (Hungarian)
Currently translated at 100.0% (107 of 107 strings)

Change-Id: I11e181e632c3d3690e5845f8e166904f329612dd

update translations

LibreOffice Online/loleaflet-ui (Hungarian)
Currently translated at 100.0% (348 of 348 strings)

Change-Id: Ie204f535954b8e7aa884e9b72f6ba5ad3ced1b72

update translations

LibreOffice Online/loleaflet-ui (Spanish)
Currently translated at 100.0% (348 of 348 strings)

Change-Id: I785c8c7bfd196a783f87e19e07aa0a55a19ec04a

update translations

LibreOffice Online/loleaflet-ui (Catalan)
Currently translated at 100.0% (348 of 348 strings)

Change-Id: Ia4f7048090053ec9d554bdec582cd5d899b72256

update translations

LibreOffice Online/loleaflet-ui (Asturian)
Currently translated at 44.8% (156 of 348 strings)

Change-Id: I08f7544d1b4a216cd2b9a10cd2042ab9ebd4503f

Update translation files

Updated by "Update PO files to match POT (msgmerge)" hook in Weblate.

Change-Id: I5c7c1370bc62603e443792560b6c40593308ad9f
Translation: LibreOffice Online/loleaflet-ui
Translate-URL: https://weblate.documentfoundation.org/projects/libo_online/loleaflet-ui/

update translations

LibreOffice Online/android-app (Slovak)
Currently translated at 100.0% (107 of 107 strings)

Change-Id: I46c31c4a1248c66689d5dd0fea2fc10881d32a7d

update translations

LibreOffice Online/android-app (English (United Kingdom))
Currently translated at 100.0% (107 of 107 strings)

Change-Id: I938a217d2c0e48dc537d80bb523b6334cf172872

update translations

LibreOffice Online/android-lib (Chinese (Traditional))
Currently translated at 100.0% (13 of 13 strings)

Change-Id: I6b1356004e470d5675e74ec599e9ae715d8880a1

update translations

LibreOffice Online/android-app (Portuguese (Brazil))
Currently translated at 100.0% (107 of 107 strings)

Change-Id: Id8d459e74b122321165559f4f3d2750621d8afa0

update translations

LibreOffice Online/android-app (Chinese (Simplified))
Currently translated at 98.1% (105 of 107 strings)

Change-Id: I425e1add15ee3096c5150cbd5682043805821adf

update translations

LibreOffice Online/android-app (Chinese (Traditional))
Currently translated at 100.0% (107 of 107 strings)

Change-Id: I52d04f74cc9b1a277de4831b4ae815f6cf4137f6

update translations

LibreOffice Online/android-lib (Chinese (Traditional))
Currently translated at 100.0% (13 of 13 strings)

Change-Id: I3fc049d00fa9fbd516ca2c5928bccdc98c73fef9

update translations

LibreOffice Online/loleaflet-ui (Chinese (Simplified))
Currently translated at 97.6% (339 of 347 strings)

Change-Id: I89f0cca4a3356c24b10659cb6563bb836ef00ce0

update translations

LibreOffice Online/android-app (Lower Sorbian)
Currently translated at 100.0% (107 of 107 strings)

Change-Id: Id686eca772b16d1789120d6af306e43485322e50

update translations

LibreOffice Online/android-app (Upper Sorbian)
Currently translated at 100.0% (107 of 107 strings)

Change-Id: I2aa71bce22095aeb24825e39741a3e07e7327410

update translations

LibreOffice Online/android-app (Polish)
Currently translated at 100.0% (107 of 107 strings)

Change-Id: I2ec8bbcfc621542a6b58a6e4f1ebe00412caa3bd

update translations

LibreOffice Online/android-app (Asturian)
Currently translated at 71.9% (77 of 107 strings)

Change-Id: Id2f2954719a55a658646b9361c202bed14f64387

update translations

LibreOffice Online/android-app (Catalan)
Currently translated at 100.0% (107 of 107 strings)

Change-Id: If314ddee8235aa1e1a3ec840edf76240ac6a8633

update translations

LibreOffice Online/android-app (Spanish)
Currently translated at 100.0% (107 of 107 strings)

Change-Id: I4c0b9eeedcd7f5d9b23b7aa031619c7f3f0648cb

update translations

LibreOffice Online/loleaflet-help (Italian)
Currently translated at 100.0% (418 of 418 strings)

Change-Id: I3c93ed76678389f968494f8166eaf3a7d6c4c7a6

update translations

LibreOffice Online/loleaflet-help (Esperanto)
Currently translated at 100.0% (418 of 418 strings)

Change-Id: Icef2e2c54a678d73b4692939e2554d595ed4d261

update translations

LibreOffice Online/loleaflet-ui (Italian)
Currently translated at 100.0% (347 of 347 strings)

Change-Id: I700e515880257df5421fb21495ffc075d4911968

update translations

LibreOffice Online/loleaflet-ui (Italian)
Currently translated at 100.0% (347 of 347 strings)

Change-Id: I3c0db51d2645e0942d037b506cab57423898fb0f

update translations

LibreOffice Online/loleaflet-ui (Esperanto)
Currently translated at 100.0% (347 of 347 strings)

Change-Id: Ia030f55b2ab4c0457f1c43c6839582d4f0532165

update translations

LibreOffice Online/loleaflet-ui (Italian)
Currently translated at 98.5% (342 of 347 strings)

Change-Id: I5d3376462a3d17d6a8114d449dc47f9999f2272a

update translations

LibreOffice Online/android-lib (Portuguese)
Currently translated at 100.0% (13 of 13 strings)

Change-Id: I5674e50a3c3599ccb1eaa6dbf18955a03e8e8f46

update translations

LibreOffice Online/loleaflet-help (Portuguese)
Currently translated at 55.7% (233 of 418 strings)

Change-Id: I204aadbbe1fed31742e0358b378a32b26ebb904b

update translations

LibreOffice Online/loleaflet-ui (Portuguese)
Currently translated at 100.0% (347 of 347 strings)

Change-Id: I738562ff499e8e96985f728c5eb267f3f307e355

update translations

LibreOffice Online/loleaflet-ui (Basque)
Currently translated at 100.0% (347 of 347 strings)

Change-Id: I8866029b5fb4c4980c224770e610e32756ca5df2
Reviewed-on: https://gerrit.libreoffice.org/c/online/+/103405
Tested-by: Jenkins CollaboraOffice <jenkinscollaboraoffice@gmail.com>
Reviewed-by: Andras Timar <andras.timar@collabora.com>
2020-09-30 21:23:52 +02:00
..
2020-09-30 21:23:52 +02:00

Leaflet platform for LibreOffice Online
========================================

This is the client part of LibreOffice Online.  For the server part, see the
../wsd/README, and install it first.

Build dependencies
------------------

npm is provided by the nodejs package.

npm should be at least 2.14, if not 3.x. Use `npm -v` to find the current version.
Upgrade npm (as root):

    npm install -g npm

Another 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

All of the dependency tree is locked in the repository, so there is no need to fetch
data from npm registry at all. An npm install will use the tarballs in node_shrinkwrap/
directory, so build process can move forward even without an internet connection.

To update any of the dependency, process often goes like this:

1.) Change version of the dependency in package.json
2.) Do an `npm update <package_name>', which fetches the new module from npm registry. Make sure that
    only the module that you want to update is updated.
3.) `npm shrinkwrap --dev` to update npm-shrinkwrap.json with newer information. You might see
    that this tool updates path convention of tarballs inside node_shrinkwrap/ also, but this
    should get corrected in next step.
4.) Do `shrinkpack', which should remove the old tarball, add new one, and make appropriate
    changes to npm-shrinkwrap.json (removing path convention changes by step 3).

If you have not installed `shrinkpack' globally using `npm install -g shrinkpack@next', it should be
in node_modules/.bin/shrinkpack, so you can use the binary from there.

If you need to get the sources:
	make libs

To bundle the file sanitize-url.js
	browserify braintree-sanitize-url/index.js --standalone sanitizeUrl > sanitize-url.js

Building
--------

Just do:

    make

Above step would create a non-minified bundle.js and admin-bundle.js without source-maps in dist/ for main loleaflet and admin console
respectively.

To build with debug-info, i.e with sourcemaps:

    make DEBUG=true

Above will produce source-map files, bundle.js.map and admin-bundle.js.map, for bundle.js and admin-bundle.js respectively.
It will also link existing bundle.js and admin-bundle.js to their map files by adding a sourceMappingURL to them. While debugging,
these .map files will be fetched from the server if present in dist/, otherwise there is no way to debug while browsing without these
source-map files.

To minify our bundle.js and admin-bundle.js passing a MINIFY=true flag to 'make' will minify it. This can be helpful in production
environments.

    make MINIFY=true

'make dist' forces minifying.

Running
-------

To see an example:

* run loolwsd, like:

    ./loolwsd --o:sys_template_path=${SYSTEMPLATE} --o:child_root_path=${ROOTFORJAILS}

Note that this will, by default, set the loolwsd's file server's root to the parent directory of loolwsd,
which means you can access all the files in loleaflet using /loleaflet/ path. It is advised to set
file_server_root_path manually for more control. See wsd/README for more information.

* open dist/loleaflet.html through loolwsd's fileserver

    https://localhost:9980/loleaflet/dist/loleaflet.html?file_path=file:///PATH/TO_DOC&host=wss://localhost:9980

and you should see the document in the browser.
Note that accessing local storage is disabled by default for security reasons. You need to explicitly enable it
with the --o:storage.filesystem[@allow]=true option of loolwsd. In case anything goes wrong, check the loolwsd console for
the debugging output. You might be asked to confirm the certificate if you are using self-signed certificate
for loolwsd.

Development
-----------

For faster development you might want to install browser-sync which can reload app in your browsers automatically
after you edit and save the source code (so for .css only):

npm install -g browser-sync

Remember to add '--enable-browsersync' argument for './configure' script and delete `dist` directory.

Run server and start browser-sync:

LOOL_SERVE_FROM_FS=1 make run

and in the second terminal:

make sync-[writer|calc|impress]

Your browser will open example document and now you can edit .css files and see the result without server restart.

To run another document use:
browser-sync start --config browsersync-config.js --startPath "loleaflet/96c23f663/loleaflet.html?file_path=file:///path/to/the/file.ods"

Admin Panel
-----------

You can do live monitoring of all the user sessions running on loolwsd instance. To access the admin
console you need to ask for admin.html file from loolwsd which resides in dist/admin/admin.html.

For example:

    https://localhost:9980/loleaflet/dist/admin/admin.html

It will ask for username and password which is set by the admin_console options of loolwsd. For example you can
pass --o:admin_console.username=admin --o:admin_console.password=admin in command line, or set these values in
loolwsd.xml. After entering the correct password you should be able to monitor the live documents opened, total
users, memory consumption, document URLs with number of users viewing that document etc. You can also kill the
documents directly from the panel which would result in closing the socket connection to the respective document.

API & events
------------

#######################################################################
# See /loleaflet/reference.html for a better formatted documentation. #
# See /wsd/reference.md for the HTTP API documentation.               #
#######################################################################

Search:
    - API:
        map.search(text, [backward])
        map.highlightAll(text)
    - 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
            + e.results = [SearchResult], where SearchResult = {part: part, rectangles: [Bounds]}

Zoom:
    - API:
        map.zoomIn(amount)
        map.zoomOut(amount)
        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('.uno:' + 'Bold' | 'Italic' | 'Underline' | 'Strikeout' |
            'LeftPara' | 'CenterPara' | 'RightPara' | 'JustifyPara' |
            'IncrementIndent' | 'DecrementIndent'
    - events:
        map.on('commandstatechanged', function (e) {}) where:
            + e.commandName == '.uno:' + 'Bold' | 'Italic' | 'StyleApply' | 'CharFontName' | 'FontHeight' etc.
            + e.state = 'true' | 'false'
            + e.state = fontName | fontSize | styleName
        map.on('commandresult', function (e) {}) where:
            + e.commandName == '.uno:' + 'Bold' | 'Italic' | 'StyleApply' | 'CharFontName' | 'FontHeight' etc.
            + e.success = true | false | undefined

Parts (like slides in presentation, or sheets in spreadsheets):
    - API:
        map.setPart('next' | 'prev' | partNumber)
        map.getNumberOfParts()
        map.getCurrentPartNumber()
        map.getPreview(id, index, maxWidth, maxHeight, [options], forAllClients)
            + id = the ID of the request so that the response can be identified
            + index = the part / page 's number
            + maxWidth / maxHeight = max dimensions so that the ratio is preserved
            + options = {autoUpdate: <boolean>, broadcast: <boolean>} -
	      + autoUpdate - boolean, automatically updates the previews
	      + broadcast - boolean, whether the response (a preview of a slide) should be sent to all clients
                viewing the same presentation
        map.getCustomPreview(id, part, width, height, tilePosX, tilePosY, tileWidth, tileHeight, [options])
            + id = the ID of the request so that the response can be identified
            + part = the part containing the desired preview
            + width / height = the preview's size in pixels
            + tilePosX / tilePosY = the rectangles's starting position in twips
            + tileWidth / tileHeight = the rectangle's dimension in twips
            + options = {autoUpdate: true} - automatically updates the previews
        map.removePreviewUpdate(id)
            + id = the preview's id

    - events:
        map.on('updateparts', function (e) {}) where:
            + e.selectedPart 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)
        map.on('tilepreview', function (e) {}) where:
            + e.tile - the preview image
            + e.id - the preview id
            + e.width - width of the image
            + e.height - height of the image
            + [e.part] - if the preview is for a part
            + e.docType

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])
        map.downloadAs(name, [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 negative)
        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.getCurrentPageNumber()
        map.getPreview(id, index, maxWidth, maxHeight, [options])
            + id = the ID of the request so that the response can be identified
            + index = the part / page 's number
            + maxWidth / maxHeight = max dimensions so that the ratio is preserved
            + options = {autoUpdate: true} - automatically updates the previews
        map.getCustomPreview(id, part, width, height, tilePosX, tilePosY, tileWidth, tileHeight, [options])
            + id = the ID of the request so that the response can be identified
            + part = the part containing the desired preview
            + width / height = the preview's size in pixels
            + tilePosX / tilePosY = the rectangles's starting position in twips
            + tileWidth / tileHeight = the rectangle's dimension in twips
            + options = {autoUpdate: true} - automatically updates the previews
        map.removePreviewUpdate(id)
            + id = the preview's id
        map.getPageSizes()
            + returns {twips: [Bounds], pixels: [Bounds]}

    - 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

Infobars:
    - events
        map.on('infobar', function (e) {}) where
            + [e.msg] = a message
            + [e.actionlabel] = Label for the action button
            + [e.action] = A link (starting with http).
                           Please extend to allow other actions when needed.

CommandValues:
    - api:
        map.getToolbarCommandValues(command)
            + returns a JSON mapping of all possible values for the command
        map.applyFont(fontName)
        map.applyFontSize(fontSize)
        map.applyStyle(style, styleFamily)
    - events
        map.on('updatetoolbarcommandvalues', function (e) {}) where
            + e.commandName = '.uno:StyleApply', etc
            + e.commandValues = a JSON mapping of all possible values for the command

Print:
    - events
        map.on('print', function (e) {}) where
            + e.url = file download url

Contributing
------------

Code conventions:

    * 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:
        - server address
        - doc - path to the document that will be loaded
        - edit = the initial permission
        - readOnly - whether the document is read only
        - [timestamp] - optionally provided for remote documents

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.

Z-index values:
-------------------------------------------
		leaflet
-------------------------------------------
10			map
11			ruler
-------------------------------------------
		under menu
-------------------------------------------
990			sidebar
999			toolbar-up
-------------------------------------------
		menu items
-------------------------------------------
1000			main-menu(desktop-only)
0			toolbar-down
1050			closebuttonwrapper (not being used currently)
-------------------------------------------
		on the top
-------------------------------------------
1105			dialogs
1001			mobile-edit-button
1500			mobile-wizard (with class=menuwizard)
1501			toolbar-hamburger (with class=menuwizard-opened)
2000			vex-overlay
2001			vex dialog (vex-content)
-------------------------------------------