Javascript SDK

The Carbone Cloud Javascript SDK is used to generate reports easily from a client side service (Angular, Vuejs, Svelte, React, Ember.js).

The source code is available on Github: https://github.com/carboneio/carbone-sdk-js

Install

npm install --save carbone-sdk-js

or

yarn add carbone-sdk-js

Quickstart

Try the following code to generate a report in few seconds. Insert an API key, provide the template, and the data as a stringified JSON, that's it.

import carboneSDK from "carbone-sdk-js";
// SDK constructor, the access token have to be passed as an argument to carboneRenderSDK
const _carboneService = carboneSDK("eyJhbGc..."); // same as  window.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
});

Carbone API version

function setApiVersion(version)

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

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

Use Javascript SDK with Carbone on premise

To set url of you local Carbone deployement :

function setApiUrl( carboneUrl )

Generate a report

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.

Upload a template

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
  }
});

Download a template

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
});

Delete a template

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);
  }
});

Generate a template ID

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.