# @bcgov/carbone-render

> Async wrapper around Carbone render

Latest version **2.2.2** (published 2021-07-27) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @bcgov/carbone-render
pnpm add @bcgov/carbone-render
yarn add @bcgov/carbone-render
bun add @bcgov/carbone-render
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.2.2 |
| Published | 2021-07-27 |
| First published | 2020-03-16 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 20.2 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 4 |
| Author | NR Common Service Showcase |
| Maintainers | jleach, patricksimonian, shellyxuehan, parcjason, cvarjao, akroon3r, bc-gov-common-services, nicoledegreef, chobson, qqnluaq, jujaga, dgboss |
| Keywords | carbone, carbone-render, template, render, docgen, doc-generation |

## Links

- npm: https://www.npmjs.com/package/@bcgov/carbone-render
- Repository: https://github.com/bcgov/common-services-team-library
- Homepage: https://bcgov.github.io/common-services-team-library/
- Issues: https://github.com/bcgov/common-services-team-library/issues
- npm.io page: https://npm.io/package/@bcgov/carbone-render

## Dependencies (3)

- [uuid](https://npm.io/package/uuid.md) ^8.3.2
- [carbone](https://npm.io/package/carbone.md) ^3.1.0
- [fs-extra](https://npm.io/package/fs-extra.md) ^10.0.0

## Recent versions

- 2.2.2 (latest) — 2021-07-27
- 2.2.1 — 2021-07-07
- 2.2.0 — 2021-05-19
- 2.1.2 — 2021-05-17
- 2.1.1 — 2020-10-06
- 2.1.0 — 2020-10-06
- 2.0.0 — 2020-10-01
- 1.0.2 — 2020-04-21
- 1.0.1 — 2020-04-21
- 1.0.0 — 2020-03-16

## README

# [Deprecated] carbone-render

*Note: This package has been deprecated and will no longer be receiving support updates.*

[![npm](https://img.shields.io/npm/v/@bcgov/carbone-render.svg)](https://www.npmjs.com/package/@bcgov/carbone-render)
[![downloads](https://img.shields.io/npm/dm/@bcgov/carbone-render.svg)](https://npmcharts.com/compare/@bcgov/carbone-render?minimal=true)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![img](https://img.shields.io/badge/Lifecycle-Stable-97ca00)](https://github.com/bcgov/repomountie/blob/master/doc/lifecycle-badges.md)

Library to generate a document from an existing template and JSON data.  This is a wrapper around [carbone](https://carbone.io), please refer to their documentation for more detail.

## Prerequisites

This library will require LibreOffice installed to do pdf generation.

## Installation

```sh
npm i @bcgov/carbone-render
```

## Usage

```js
const carboneRenderer = require('@bcgov/carbone-render');
```

### startFactory

Optional call to start up the carbone python converter.  This is recommended to call on the start of your application. Otherwise, the first call to render will take longer as it starts the converter in the background.

```js
carboneRenderer.startFactory();
```

### fileTypes

Return a dictionary of allowable file conversions.  Convert to pdf is always allowed.

```js
const allowedConversions = carboneRenderer.fileTypes;
```

Returns dictionary

```json
{
    "csv": [
        "doc",
        "docx",
        "html",
        "odt",
        "pdf",
        "rtf",
        "txt",
        "csv"
    ],
    "docx": [
        "doc",
        "docx",
        "html",
        "odt",
        "pdf",
        "rtf",
        "txt"
    ],
    "html": [
        "html",
        "odt",
        "pdf",
        "rtf",
        "txt"
    ],
    "odt": [
        "doc",
        "docx",
        "html",
        "odt",
        "pdf",
        "rtf",
        "txt"
    ],
    "pptx": [
        "odt",
        "pdf"
    ],
    "rtf": [
        "docx",
        "pdf"
    ],
    "txt": [
        "doc",
        "docx",
        "html",
        "odt",
        "pdf",
        "rtf",
        "txt"
    ],
    "xlsx": [
        "odt",
        "pdf",
        "rtf",
        "txt",
        "csv",
        "xls",
        "xlsx"
    ]
}
```

### async render

Generate a new document from a template and JSON data.  Render the report.

```js
const data = {
    "firstName": "Jane",
    "lastName": "Smith",
    "title": "Who?"
};

const options = {
    "convertTo": "pdf",
    "reportName": "{d.firstName}-{d.lastName}.docx",
    "overwrite": "true",
    "cacheReport": "true"
};

const formatters = {
    // this formatter can be used in a template with {d.myBoolean:yesOrNo()}
    yesOrNo : function (data) { // data = d.myBoolean
        if (this.lang === 'fr') {
            return data === true ? 'oui' : 'non';
        }
        return data === true ? 'yes' : 'no';
    }
};

const output = await carboneRenderer.render(template.path, data, options, formatters);
```

| Parameters | Description |
| --- | --- |
| template | template file |
| data | object or array of objects used in the template |
| options | Options object to pass to carbone.  See carbone documenation. |
| options.convertTo | What file type to convert to, see fileTypes or pdf |
| options.reportName | Name of the generated report, should include expected extension. Can contain template placeholders, see carbone documentation. |
| formatters | Object. Additional formatters to add to carbone.  See carbone documenation. |

Returns object

```json
{
    "success": false,
    "errorType": null,
    "errorMsg": null,
    "reportName": null,
    "report": null
}
```

| Field | Description |
| --- | --- |
| success | boolean, true indicates report generated, false otherwise |
| errorType | number - error number if not successful. |
| errorMsg | string - error message if not successful. |
| reportName | string - name of the generated report |
| report | binary - generated file |

---
_Source: https://npm.io/package/@bcgov/carbone-render · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._