Skip to main content

Document

The document section defines the document parameters.

fileType​

type: string

The type of the file for the source viewed or edited document. Must be lowercase. The available values depend on the documentType:

  • doc, docm, docx, dot, dotm, dotx, epub, fb2, fodt, hml, htm, html, hwp, hwpx, md, mht, mhtml, odt, ott, pages, rtf, stw, sxw, txt, wps, wpt, xml — for documents;
  • csv, et, ett, fods, numbers, ods, ots, sxc, xls, xlsb, xlsm, xlsx, xlt, xltm, xltx, xml — for spreadsheets;
  • dps, dpt, fodp, key, odg, odp, otp, pot, potm, potx, pps, ppsm, ppsx, ppt, pptm, pptx, sxi — for presentations;
  • djvu, ofd, oxps, pdf, xps — for portable document format;
  • vsdm, vsdx, vssm, vssx, vstm, vstx — for diagrams.
info

If omitted, the file type is automatically inferred from the documentType value. If both fileType and documentType are omitted, an error will occur.

Example: "docx"

isForm​

type: boolean

Whether to open the PDF file as a form. Applies when fileType is pdf. If this parameter is not specified, then the internal checking of PDF files is started.

Example: true

key​

type: string | required

The unique document identifier used by the service to recognize the document. If a known key is sent, the document will be taken from the cache. Every time the document is edited and saved, the key must be generated anew.

note

The key must be unique for all independent services connected to the same document server. Otherwise, the service may open someone else's file from the editor cache. If multiple third-party integrators are connected to the same document server, they must also provide a unique key.

The key characters can be used: 0-9, a-z, A-Z, -.\_=. The maximal key length is 128 characters.

Example: "Khirz6zTPdfd7"

options​

type: object

The additional options for opening the document.

options.watermark​

type: object | string

The watermark added to the files that the user downloads from the editor as PDF or as an image. It is not drawn on the pages in the editor; to show the watermark on screen as well, use options.watermark_on_draw. The value has the same format as options.watermark_on_draw.

options.watermark_on_draw​

type: object | string

The watermark drawn over every page of the document while it is open in the editor. It is also added to the files that the user downloads as PDF or as an image. Other formats are downloaded without it, and the watermark is never saved to the document itself.

The value is an object, or a string with this object in JSON, with the watermark properties. The conversion request takes the same object in its watermark parameter. The transparent property sets the watermark opacity: 0 is invisible, 1 is opaque. The default value is 0.3.

The %user_name% placeholder is replaced with the name of the user who opened the document, so each user sees their own name. The placeholder is replaced anywhere in the object, not only in the run text. The name is inserted without escaping, so if it contains " or \, the object cannot be parsed and the watermark is not shown.

warning

The watermark is drawn by the editor in the browser. The user can remove it with the browser developer tools, so do not use it to restrict access to the document. To stop users from getting the document without the watermark, also set download, print and copy to false in the document permissions. To insert a watermark into the file on the server, convert the document with a watermark.

Example:

{
  "type": "rect",
  "width": 150,
  "height": 50,
  "rotate": -45,
  "transparent": 0.3,
  "fill": [],
  "stroke": [],
  "align": 1,
  "paragraphs": [
    {
      "align": 2,
      "runs": [
        {
          "text": "Confidential: %user_name%",
          "fill": [128, 128, 128],
          "font-family": "Arial",
          "font-size": 24,
          "bold": true
        }
      ]
    }
  ]
}

referenceData​

type: object

An object that is generated by the integrator to uniquely identify a file in its system.

Example:

{
  "fileKey": "BCFA2CED",
  "instanceId": "https://example.com"
}

referenceData.fileKey​

type: string

The unique document identifier used by the service to get a link to the file. It must not be changed when the document is edited and saved (i.e. it is not equal to the document.key parameter).

Example: "BCFA2CED"

referenceData.instanceId​

type: string

The unique system identifier. If the data was copied from a file on one system, and inserted into a file on another, then pasting by link will not be available and there will be no corresponding button in the context menu.

Example: "https://example.com"

title​

type: string

The desired file name for the viewed or edited document which will also be used as file name when the document is downloaded. The length is limited to 128 characters. If not specified or empty, defaults to "Unnamed.{fileType}" (e.g. "Unnamed.docx").

Example: "Example Document Title.docx"

url​

type: string | required

The absolute URL where the source viewed or edited document is stored. Be sure to add a token when using local links. Otherwise, an error will occur.

Example: "https://example.com/url-to-example-document.docx"

info​

type: object

The info section defines the document info parameters.

permissions​

type: object

The permissions section defines the document permission parameters.

Example​

const config = {
  // ...
  document: {
    fileType: "pdf",
    isForm: true,
    key: "Khirz6zTPdfd7",
    options: {
      watermark_on_draw: {
        // ...
      },
    },
    referenceData: {
      fileKey: "BCFA2CED",
      instanceId: "https://example.com",
    },
    title: "Example Title.pdf",
    url: "https://example.com/url-to-example-document.pdf",
    info: {
      // ...
    },
    permissions: {
      // ...
    },
  },
};

const docEditor = new DocsAPI.DocEditor("placeholder", config);

The example.com is the name of the server where document manager and document storage service are installed. See the How it works section to find out more on ONLYOFFICE Docs service client-server interactions.