Skip to content

Latest commit

 

History

History
146 lines (114 loc) · 4.74 KB

API-REFERENCE.md

File metadata and controls

146 lines (114 loc) · 4.74 KB
Raw

Carbone Render Javascript SDK

The Carbone Javascript SDK provides a simple interface to communicate with Carbone Render easily.

Install the Javascript SDK

npm install --save carbone-sdk-js

or

yarn add carbone-sdk-js

Quickstart with the Javascript SDK

Try the following code to render a report in 10 seconds. Just replace your API key, the template you want to render (file input), and the data object.

import carboneSDK from "carbone-sdk-js";
// SDK constructor, the access token have to be passed as an argument to carboneRenderSDK
const _carboneService = carboneSDK("eyJhbGc...");
// Template from a file input OR template ID
const _template = document.getElementById("inputFile").files[0];
// Data from an input, for example: {"data" :{"firstname":"John","lastname":"Wick"},"convertTo":"pdf"}
let _data = JSON.parse(document.getElementById("inputData").value);
// Render the report from an DOCX template and a JSON Data
_carboneService.render(_template, _data).then(({ content, name }) => {
  // name == report name as a String
  // content == report content as a Blob, it can be used to download the file
});

Javascript SDK API

CarboneSDK Constructor

Instanciate the SDK with:

import carboneSDK from "carbone-sdk-js";
// SDK constructor, the access token have to be passed as an argument to carboneRenderSDK
const _carboneService = carboneSDK("eyJhbGc...");

Or, the SDK is available through the global window variable.

// Carbone access token passed as parameter
const _carboneService = window.carboneSDK("eyJhbGc...");

Render

async function render(templateIdOrFile, data, payload = "", responseType = "blob");

The render function takes templateIdOrFile a File/Blob from an input OR a template ID, data JSON (not stringified), an optional payload, and an optional responseType which correspond to the type of the response.

It returns the report as a Blob by default and a unique report name as a string. Carbone engine deletes files that have not been used for a while. By using this method, if your file has been deleted, the render function upload automatically the template again and return the result.

When a File or Blob is passed as an argument, the function verifies if the template has been uploaded to render the report. If not, it calls addTemplate to upload the template to the server. Then it calls renderReport and getReport to generate the report.

When a template ID is passed as an argument, the function renders with the renderReport function then call getReport to return the report. If the template ID does not exist, an error is returned.

addTemplate

async function addTemplate (file, payload = '');

The function adds the template to the API and returns the response (that contains a templateId). The file argument is a type File or Blob. You can add multiple times the same template and get different template ID thanks to the optional payload.

Example

const carboneService = window.carboneRenderSDK("eyJhbGc...");

carboneService.addTemplate(file).then(data => {
  if (data.success === true) {
    // templateId: data.data.templateId
  } else {
    // error: data.error
  }
});

getTemplate

async function getTemplate(templateId, responseType = "blob");

Pass a templateId to the function and it returns the template as a blob. The template ID must exist otherwise an error is returned by the server.

const carboneService = window.carboneRenderSDK("eyJhbGc...");

carboneService.getTemplate("templateId").then(file => {
  // `file` is Blob type
});

deleteTemplate

async function deleteTemplate(templateId);

Delete a template from a templateId.

Example

const carboneService = window.carboneRenderSDK("eyJhbGc...");

carboneService.deleteTemplate("templateId").then(resp => {
  if (resp.success === false) {
    throw new Error(resp.error);
  }
});

generateTemplateId

async function generateTemplateId(fileContent, payload = "");

The Template ID is predictable and idempotent, pass the template path and it will return the templateId. Different template ID can be returned thanks to the optional payload.

setAccessToken

function setAccessToken(newToken)

It sets the Carbone access token.

setApiVersion

function setApiVersion(version)

It sets the the Carbone version requested. By default, it is calling the version 2 of Carbone.

Note: You can only set a major version of carbone.

setApiHeaders

Define custom API headers

carboneSDK.setApiHeaders({
  "carbone-template-delete-after": "86400",
  "carbone-webhook-url": "https://..."
});