DOCSEARCHbyAlgolia
Submit Docs

ZetaJS

repository·main·Indexed 42 days ago

https://github.com/allotropia/zetajs

A JavaScript wrapper for interacting with ZetaOffice (a web-based LibreOffice instance) via the UNO API. Version 1.2.0 enables developers to embed office capabilities, create custom text editing or spreadsheet components, or perform headless document processing directly in the browser.

Tokens
8K
Snippets
35
Records
52
Agent score
52%

What's inside ZetaJS

  1. What is zetajs and how does it work?

    main

    zetajs is a JavaScript library that allows you to run and control an instance of ZetaOffice (a web-based office suite) directly in your browser. It provides a wrapper over the LibreOffice UNO technology, offering a more idiomatic JavaScript experience while hiding the underlying Embind-based machinery.

    Common use cases include:

    • Embedding a full in-browser office suite.
    • Creating custom text editing or spreadsheet components for your website.
    • Running a headless instance for background document conversion.

  2. How communication between threads works in zetajs

    main

    Because code using zetajs runs in a worker thread rather than the browser's main thread, it cannot directly access the browser's document object. To bridge this gap, zetajs uses a MessageChannel to facilitate communication between the main thread and the worker thread.

    To implement this communication:

    1. In the browser's main thread: Access Module.uno_main, which is a Promise that resolves to one of the two ports of the MessageChannel.
    2. In the zetajs worker thread: Use zetajs.mainPort to access the corresponding port of the channel.

    The specific communication protocol (the structure and meaning of messages sent across these ports) is determined by your application's implementation.

  3. Handle UNO `ANY` values in JavaScript

    main

    The UNO ANY type is a container that can hold any value. In zetajs, it maps to a combination of wrapped and unwrapped representations.

    Wrapped Representation

    An ANY value can always be represented as a wrapped opaque JavaScript object containing:

    • type: A zetajs representation of the UNO TYPE.
    • val: A zetajs representation of the actual value.

    Unwrapped Representation

    Depending on the contained type, ANY can map directly to a JavaScript value (unwrapped):

    1. Direct Mapping (Simple Types): If the contained value is VOID, BOOLEAN, LONG, HYPER, STRING, TYPE, a UNO enum, a UNO struct, or a UNO exception, it maps directly to its JavaScript equivalent.

    2. Direct Mapping (Numeric/Sequence/Interface Types): If the contained value is BYTE, SHORT, UNSIGNED SHORT, UNSIGNED LONG, UNSIGNED HYPER, FLOAT, DOUBLE, CHAR, a UNO sequence, or a UNO interface, it also maps to an unwrapped representation. However, the direction of conversion has specific rules:

      • Large Integers: JS Numbers in $[2^{63}, 2^{64})$ map to UNO UNSIGNED LONG.
      • Floats: JS Numbers not covered by LONG/UNSIGNED LONG map to UNO DOUBLE.
      • Large BigInts: JS BigInts $> 2^{63}-1$ map to UNO UNSIGNED HYPER.
      • Arrays: JS Array maps to a UNO "sequence of ANY".
      • Objects: JS null or JS objects representing UNO objects map to UNO interface type com.sun.star.uno.XInterface.

    For programmatic manipulation, refer to zetajs.Any, zetajs.getAnyType, and zetajs.fromAny.

  4. Build the Letter Address Tool for deployment to a web server

    main

    To generate production-ready files that can be hosted on a web server, run the distribution build command.

    Important Production Note: When deploying to production, you must replace the local file: link for zetajs in your package.json with a proper version from npmjs.com to ensure dependencies are resolved correctly.

    npm install
npm run dist

  7. Access remote documents via WebSocket emulation

    main

    By default, LOWA cannot access documents via HTTPS/HTTP URLs directly. You can emulate HTTP access using the WebSocket protocol by configuring the Module.websocket setting.

    If the target server does not support WebSockets, you must use a proxy like websockify to bridge the connection. Note that this method is limited to a single WebSocket endpoint.

    Steps to implement:

    1. Set Module.websocket in your HTML file before loading soffice.js.
    2. Run a websockify proxy to forward the local WebSocket port to the remote HTTPS port.
    // In your HTML file before including soffice.js
Module.websocket = {url: 'ws://127.0.0.1:6932', subprotocol: 'binary'};
Module.arguments = ['https://freetestdata.com/wp-content/uploads/2021/09/Free_Test_Data_100KB_ODT.odt'];
    # Run websockify to bridge local port 6932 to the remote HTTPS port 443
$ websockify 127.0.0.1:6932 freetestdata.com:443

  8. Set up the ZetaJS Letter Address Tool (Vue.js-3)

    main

    This project is a Web form letter demo using a stripped-down, standalone Writer document canvas. It is built using Vue.js-3 and requires Node.js.

    To set up the environment, ensure you have Node.js and npm installed. If you are using nodeenv, you can initialize the environment with: nodeenv --node=system --with-npm nodeenv/

    npm install

  12. Initialize and use the zetajs object

    main

    To use zetajs, you must first ensure zeta.js is listed as the first element in the Module.uno_scripts array. Then, wait for the Module.zetajs Promise to resolve to obtain the zetajs object.

    // Example initialization pattern
Module.uno_scripts = ['path/to/zeta.js', 'path/to/your-script.js'];

Module.zetajs.then((zetajs) => {
  // Use the zetajs object here
  console.log('zetajs is ready');
});