DEV Community: Carbone

Cheat Sheet for Carbone

Steeve — Thu, 20 Nov 2025 09:00:00 +0000

Carbone is a templating engine designed to generate dynamic documents (PDFs, DOCX, XLSX, PPTX, etc.) by merging templates with JSON data:

The JSON Data-set coming from your application, database, or API.
The template must be designed using a Text Editor like Word, LibreOffice or Google Docs. To inject the content dynamically you must write Tags (a.k.a. placeholder), it will be replaced with the corresponding values from the JSON data.

Carbone’s tag syntax offers a lot of possibilities! This article focuses on the essentials, but if you want to dive deeper or see more examples, check out the official documentation.

Click to download the Cheat Sheet without image compression

Essential Carbone Templating Syntax

1. Basic Placeholder

The placeholder tag injects the value of a property from the root of the JSON data object (d). It is the simplest way to insert dynamic data into your template. For instance, if the JSON dataset is:

{ 
  "firstname": "John"
}

Insert the following tag in the template:

{d.firstname}

and it will be replaced with "John" in the generated document.

2. Nested Placeholder

This tag accesses nested properties in the JSON data. It allows you to traverse deeper into the JSON structure to retrieve specific values. There is no limit to access in depth of nested properties. For instance, If your JSON is:

{
  "user": {
    "name": "Alice"
  }
}

The tag in the template file:

{d.user.name}

will be replaced with "Alice".

3. Access Parent Property

The double dot (..) notation lets you access a property of the parent object from a nested context. To access the grandparent object’s property, use three dots (...). You can chain as many dots as needed to navigate up the object hierarchy. If your JSON is:

{
  "country": "France",
  "movie": {
    "name": "Inception", 
    "sub": {
      "a" : "test"
    }
  }
}

The tag in the template:

{d.movie.sub..name}
{d.movie.sub...country}

The first tag will be replaced with "Inception".
The second tag will be replaced with "France"

4. Array Access with Static Index

This tag accesses a specific element in an array by its index using the square bracket notation [index]. It is useful for retrieving a particular item from an array without looping. If your JSON is:

{
  "movies": [
    { "name": "Inception" },
    { "name": "Matrix" }
  ]
}

The tag in the template:

{d.movies[0].name}

will be replaced with "Inception".

5. Conditional Logic

This tag uses the :ifEQ formatter to check if a value meets a specific condition. If the condition is met, it prints the specified text. It exists many conditional formatters (e.g. :ifIN, :ifGT, etc...), and it can be chained (using :and, :or) for complex logic and used in inline conditions, or conditional sections. If your JSON is:

{
  "isActive": true
  "message": "Your subscription is disabled."
}

The tag in the template:

{d.isActive:ifEQ(true):show('Yes'):elseShow(.message)}

will be replaced with the static text "Yes" if the value is true, otherwise the value of the "message" field is printed.

6. Default Value

Still using conditional formatters, the :ifEM formatter checks if a value is empty (null, undefined, empty string, empty array, or empty object). If it is, it prints the specified default value. If your JSON is:

{
  "user": {
    "name": null
  }
}

The tag in the template:

{d.user.name:ifEM:show('Unknown')}

will be replaced with the static text "Unknown".

7. Loop (Array Iteration)

Use the square bracket notation [i] to iterate over arrays, The character i is the loop iterator (automatically managed by Carbone). Then insert the [i+1] tag, which signals the end of the pattern and is automatically removed during rendering.

This allows you to repeat content for each item in an array. If your JSON is:

{
  "users": [
    { "id": 1, "name": "Alice", "role": "Admin" },
    { "id": 2, "name": "Bob", "role": "Editor" },
    { "id": 3, "name": "Charlie", "role": "Viewer" }
  ]
}

The tag in the template:

{d.users[i].id} - {d.users[i].name}
<!-- End of loop pattern -->
{d.users[i+1]}

will print each user's id and name in a new line.

Note: You do not need to repeat each [i] tag with [i+1], just the one [i+1] is enough for Carbone to recognize the loop pattern.

8. Loop of Nested Arrays

Use the square bracket notation [i] and [i+1] (explained the previous point) to iterate over arrays, including nested ones. You can nest loops as deeply as needed. Finally, always use i as the loop iterator, even for nested arrays: Do not ever use "j" or other characters. If your JSON is:

[
  {
    "brand": "Toyota",
    "models": [
      { "size": "Prius 4", "power": 125 },
      { "size": "Prius 5", "power": 139 }
    ]
  },
  {
    "brand": "Kia",
    "models": [
      { "size": "EV4", "power": 450 },
      { "size": "EV6", "power": 500 }
    ]
  }
]

The tags loops in the template:

{d[i].brand}
Models
{d[i].models[i].size} - {d[i].models[i].power}
{d[i].models[i+1]}
{d[i+1]}

Will generate the following content:

Toyota
Models
Prius 4 - 125
Prius 5 - 139
Kia
Models
EV4 - 450
EV6 - 500

9. Filter a Loop

In a loop, it is possible to filters Arrays to only include items that meet a specific condition. Only matching items are printed in the loop. You can add as many conditions as you want, based on the attributes in your list. To filter an array, use the following syntax in your loop tag:

{d.array[i, condition1, condition2, ...]}

If you have the following JSON:

{
  "items": [
    {"name": "Strawberries", "price": 268, "category": "fruit"},
    {"name": "Apple", "price": 50, "category": "fruit"},
    {"name": "Banana", "price": 150, "category": "fruit"},
    {"name": "Carrot", "price": 80, "category": "vegetable"}
  ]
}

The tag in the template:

{d.items[i, price > 100, category="fruit"].name}
{d.items[i+1, price > 100, category="fruit"]}

will only print "Strawberries" and "Banana". The loop prints items where the price is greater than 100 and the category is "fruit".

10. Sort a Loop

In a loop, it is possible to sorts Array by a one or multiple attributes before iterating over it. The array will be sorted in ascending order based on the first attribute, then by the second attribute if values are equal, and so on. The syntax is:

{d.array[attribute1, attribute2, ..., i]}

If your JSON is:

{
  "items": [
    {"name": "Apple", "power": 2},
    {"name": "Banana", "power": 1}
  ]
}

The tag in the template:

{d.items[power, i].name}
{d.items[power+1, i+1].name}

will print "Banana" followed by "Apple". You can specify as many attributes as you want (e.g., power, name, etc.).

Important note: while sorting, the i iterator must always be the last element in the squared brackets.

11. Formatters

Formatters are functions appended to tags with a colon (:) that modify data before display. They can accept static or dynamic parameters.

11.1 Text Formatters

These formatters transform text in various ways, such as changing case, extracting substrings, replacing text, and more.

Formatter	Description	Example
:lowerCase()	Converts text to lowercase	{d.name:lowerCase()}
:upperCase()	Converts text to uppercase	{d.name:upperCase()}
:substr(start, length)	Extracts a substring	{d.text:substr(0, 5)}
:replace(search, replace)	Replaces text	{d.text:replace('old', 'new')}
:len()	Returns the length of a string or array	{d.text:len()}
:convCRLF()	Converts line breaks to `<br>`	{d.text:convCRLF()}
:preserveCharRef()	Preserves character references	{d.text:preserveCharRef()}
:t	Translates text (Learn more on the dedicated section below)	{d.greeting:t}

11.2 Number Formatters

These formatters format numbers, including setting precision, rounding, and performing arithmetic operations.

Formatter	Description	Example
:formatN(decimals)	Formats with the specified number of decimal places.	{d.price:formatN(2)}
:round(decimals)	Rounds with the specified number of decimal places.	{d.value:round(2)}
:floor()	Rounds down to the nearest integer.	{d.value:floor()}
:ceil()	Rounds up to the nearest integer.	{d.value:ceil()}
:add(value)	Adds a value	{d.value:add(10)}
:sub(value)	Subtracts a value	{d.value:sub(10)}
:mul(value)	Multiplies by a value	{d.value:mul(2)}
:div(value)	Divides by a value	{d.value:div(2)}
:mod(value)	Modulo operation	{d.value:mod(2)}
:abs()	Absolute value	{d.value:abs()}

11.3 Currency Formatters

These formatters format numbers as currency, including setting precision and converting between currencies.

Formatter	Description	Example
:formatC(precision, currency)	Formats a number as currency	{d.price:formatC(2, 'USD')}
:convCurr(source, target)	Converts currency	{d.price:convCurr('EUR', 'USD')}

11.4 Date Formatters

These formatters format dates according to specified patterns.

Formatter	Description	Example
:formatD(pattern)	Formats a date	{d.date:formatD('YYYY-MM-DD')}
:formatI(pattern)	Formats an interval	{d.interval:formatI('HH:mm')}

11.5 Array Formatters

These formatters manipulate arrays, such as joining elements, and mapping values, and performing aggregations (Process a set of values and returns a single aggregated result).

Formatter	Description	Example
:arrayJoin(separator)	Joins array elements	{d.array:arrayJoin(', ')}
:arrayMap(separator, keySeparator, key)	Maps array elements	{d.array:arrayMap(', ', ':', 'id')}
:aggStr(separator)	Aggregator to concatenate array elements	{d.array[].value:aggStr(', ')}
:aggSum()	Aggregator to sums array elements	{d.array[].value:aggSum()}
:aggAvg()	Aggregator to get the average	{d.array[].value:aggAvg()}
:aggMin()	Aggregator to get the minimum value	{d.array[].value:aggMin()}
:aggMax()	Aggregator to get the maximum value	{d.array[].value:aggMax()}
:aggCount()	Aggregator that return the total number of elements	{d.cars[sort>20].qty:aggCount}
:cumSum()	Aggregator for running totals: Calculates and prints the cumulative sum of data	{d[i].qty:cumSum} {d[i+1]}
:cumCount()	Aggregator that print a sequential integer to each row in a list.	{d[i].qty:cumCount} {d[i+1]}

12. Colors

The :color formatter lets you dynamically apply colors to text, paragraphs, cells, rows, or shapes in your templates. You specify the target element and the color value from your JSON data. The syntax is:

{d.colorValue:color(scope, types)}

If your JSON is:

{
  "warningHexa": "#FF0000",
  "highlightHexa": "#FFFF00"
}

The tag in the template:

<!-- For Text --> 
{d.warningHexa:color(p)}This text will be red.
<!-- For Tables -->
{d.highlightHexa:color(cell, background)}This cell will have a yellow background.

will color the text "This text will be red." in red and the cell background of "This cell will have a yellow background." in Yellow.

13. Inject HTML from WYSIWYG or Code Editors

The :html formatter allows you to inject raw HTML strings from your JSON data directly into your template (supported formats: DOCX, ODT and PDF). Without this formatter, "<" and ">" characters are escaped, and HTML is not rendered. If your JSON is:

{
  "welcomeMessage": "<strong>Welcome!</strong> Here’s your dashboard."
}

The tag in the DOCX template:

{d.welcomeMessage:html}

the welcome message is injected, and the HTML is rendered in the generated document.

14. Merge PDFs

The :appendFile(position) formatter lets you dynamically insert a PDF into your generated PDF document. The file can be provided as a Base64 string or a URL in your JSON data. If your JSON data is:

{
  "contractPDF": "base64EncodedPdfFile",
  "links": {
    "welcomePDF": "https://domain/welcome.pdf"
  }
}

The tag in the template:

{d.links.welcomePDF:appendFile(start)}
{d.contractPDF:appendFile(end)}

15. Images

To inject images dynamically, a placeholder image must be defined in the template with the tag as alternative text. Then Carbone will replace the placeholder images with images specified in your JSON data-set. In order you have to:

Insert a placeholder/dummy image in your template.
Place the tag in the alternative text of the placeholder image.
Specify the image in your JSON as either a Base64-encoded string or a URL.

If your JSON data is:

{
  "logoBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "profilePictureUrl": "https://example.com/profile.jpg"
}

The tag in the template:

<!-- In the alternative text of an image -->
{d.logoBase64}

will be replaced with the image from your JSON data.

16. Charts

The :chart formatter lets you generate charts using ECharts v5 configuration. Just Insert a placeholder image in your template (DOCX, ODT, etc.), then the tag must be placed in the alternative text of the placeholder image, and finally, chain the tag with the :chart formatter. If your JSON data is:

{
  "salesChart": {
    "type": "echarts@v5",
    "width": 600,
    "height": 400,
    "option": {
      "xAxis": {
        "type": "category",
        "data": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"]
      },
      "yAxis": {
        "type": "value"
      },
      "series": [{
        "data": [150, 230, 224, 218, 135, 147, 260],
        "type": "line"
      }]
    }
  }
}

The tag in the template:

<!-- In the alternative text of an image -->
{d.salesChart:chart}

will render the Echart as SVG image in the generated document.

Important Note: All ECharts configuration options are supported, but external scripts or dependencies are not.

17. Barcodes

It is possible to insert barcodes into your documents using the :barcode(type) formatter. The barcode is rendered as an SVG image and can be embedded directly into your template. The option type is required to define the format of barcode expected. How to Use:

Define the barcode data in your JSON.
Insert a placeholder image in your template.
Place the tag in the alternative text of the placeholder image, chain the :barcode(type) formatter (don't forget the type of barcode as argument).

If you JSON is:

{
  "productCode": "123456789",
}

The tag in the template:

<!-- In the alternative text of an image -->
{d.productCode:barcode(ean13)}

Will inject a barcode image as SVG in the generated document.

18. Translations

For multi-language documents, static and dynamic translations are supported using localization dictionaries. During rendering, the language must be provided using the lang option in the report configuration. Both static and dynamic translations rely on the same dictionary.

Static translation: use {t('key')} to translate static text in your template. The translation is based on the language set in the report options.
Dynamic translation: Use the :t formatter to translate dynamic values from your JSON data.

If your JSON is:

{
  "name": "John",
  "status": "pending"
}

AND if the localization dictionary is:

{
  "fr-fr" : { 
    "greeting" : "Bonjour",
    "pending"  : "En cours"
  },
  "en-us" : {
    "greeting" : "Hello",
    "pending"  : "In progress"
  },
}

The tag in the template:

{t('greeting')} {d.name} 👋
Payment Status: {d.status:t}.

will generate the following document if the selected language is fr:

Bonjour John 👋
Payment Status: En cours.

19. Hyperlinks

For inserting clickable links in document, insert a hyperlink in your template, and set the URL to a Carbone tag, e.g., {d.documentationUrl}, that's it. If your JSON is:

{
  "title": {
    "url": "https://carbone.io/documentation",
    "name": "Documentation"
  }
}

The tag in the template with the hyperlink {d.title.url}:

{d.title.name}

will render in the document the title "My Profile", and redirect to the page https://carbone.io/documentation.

20. Electronic Signatures

Two ways are available to inject signatures in documents:

Insert a signature image: using dynamic images.
Use a third-party e-signature service: To do this, prepare your document by placing tags with the :sign formatter where you want signatures to appear. If the JSON is:

{
  "signer": {
    "name": "John Doe",
    "email": "john.doe@example.com"
  }
}

The tag in the template:

{d.signer:sign}

will generate a document with the signature position and signer details. This information are used by third-party services like DocuSign, Yousign, Signwell, or Documenso to handle the signature process.

Conclusion

We’ve covered the most important and commonly used syntax of Carbone's templating. You can now automate the creation of contracts, reports, invoices, and other documents in many fields: finance, healthcare, accounting, legal, and science, more!

Feel free to join our Official Discord — it’s a friendly place to connect and get help from the Carbone community.

Enjoy creating stunning documents with Carbone! Cheers 🍻

Creating dynamic reports with CarboneJS V2

Steeve — Thu, 13 Aug 2020 08:07:23 +0000

The Carbone team has released a major update to add the possibility to create complex reports easily. In the v2.0.0, the core has been rewritten to fix a security breach, reduce memory consumption, and gain stability! In this article, we will go through the new and cool features:

Dynamic variables in all formatters
Dynamic content 🎉
Beta Rendering dynamic charts

Everything mentioned in this article is available on the Carbone Changelog.

What is Carbone? It is a report generator using a JSON dataset and an XML based template (ODT/DOCX/XLSX/ODS/...). I have already made an introduction about it, check this out!

If you want to learn more about Carbone, check out the project on Github: https://github.com/Ideolys/carbone

Dynamic variables in all formatters

For the next examples, the following JSON dataset is going to be used:

{
  "quantity": 3
  "numberSupply": {
    "nbrA": 10,
    "nbrB": 5
  },
  "references": {
    "id1": "Invoice 123",
    "id2": "Bill 402"
  }
}

It is possible to pass variables to formatter arguments, here is an addition on a DOCX template:

Carbone translates the marker {d.numberSupply.nbrA:add(.nbrB)} to 10 + 5 and it prints the result 15 on the report.

Adding dots can be used to backtrack to the parent object. Let's multiply by the quantity:

The marker {d.numberSupply.nbrA:add(.nbrB):mul(..quantity)} is translated to (10 + 5) * 3and it prints: 45

There's no limit in depth to access to a parent object with dots. If an element doesn't exist, the error [[C_ERROR]] badAttr not defined is returned. In the end, it is not possible to pass an array to a formatter argument.

Dynamic content block and conditional formatters

The main feature of the V2 update is the conditional sections, in other words, selectively show content on the report. Here is a template example:

Markers {d.isHidden:hideBegin()} and {d.isHidden:hideEnd()} surrounding the content define the beginning and the end of the section to hide.
If the value of the data isHidden is true, the table is going to be hidden, otherwise, it appears on the report.

The result:

The same result can be done with the pair :showBegin()/:showEnd().

Finally, a new set of conditional formatter came out:

:ifEQ(value) Matches values that are equal to a specified value. The opposite is :ifNEQ().
:ifGT(value) Matches values that are greater than a specified value. You can check the equality with :ifGTE().
:ifLT(value) Matches values that are less than a specified value. You can check the equality with :ifLTE().
:ifIN(value) Matches any of the values specified in an array or string. The opposite is :ifNIN().
:ifEM(value) Matches empty values, string, arrays or objects. The opposite is :ifNEM().
:and(value) AND operator between two consecutive conditional formatters.
:or(value) OR operator between two consecutive conditional formatters.

It helps a lot to add logic in the report, such as showing a specific title in a DOCX report:

This is the equivalent in javascript:

if (d.quantity > 2 || d.numberSupply.nbrA == 8) {
  print(d.references.id1)
}

In the dataset, d.quantity is superior to two and it validates the condition. The report generated:

Iterate on attributes of objects

Printing an object as a list has never been easier, here is the dataset used for the following example:

{
  myObject : {
    paul : '10',
    jack : '20',
    bob  : '30'
  }
}

The template used:

First, the object have to be transformed to a list with d.myObject[i], then use .att to print the attribute or use .val to print the value.

The result:

Beta - supports dynamic charts rendering in XLSX files

The feature of printing charts is still experimental and will have improvements in the future. To make it work, the following steps have to be followed:

First, temporary data have to be inserted at the top left corner of the spreadsheet.
Then, the chart can be created from the temporary data range.
Replace the temporary data by the Carbone marker pointing to the JSON data set and add the formatter :formatN().

Here is a template example:

The dataset used:

{
  "list": [
    { "key": 1, "nbr": 2 }, 
    { "key": 2, "nbr": 3 }, 
    { "key": 3, "nbr": 1 }, 
    { "key": 2, "nbr": 4.4 }, 
    { "key": 5, "nbr": 10.01 }
  ]
}

Here is the result:

Voila! 🎉

Conclusion

The community is positive and sharing good feedback about the latest release. All the changes and new features are available on the CHANGELOG.md.

Contact me if you need help with Carbone, I'll be happy to answer!

Thanks for reading!

Use CarboneJS into Docker Container 🐳

Steeve — Sun, 26 Apr 2020 09:12:10 +0000

Introduction

This tutorial is about using CarboneJS into Docker containers and generating an invoice as PDF. It can be useful to split the Carbone process into containers to generate the reports.

This article is part of a series:

Carbone Turorial - Fast and Easy report generator (as fast as a spaceship 🚀)
Generate Dynamic sheets from ODS templates
CarboneJS into Docker Container 🐳 (here we are).

Preparing the template

The following document invoice_template.odt has been made with Libre Office. All markers {d.} in the document will be replaced by data.

Preparing the data to inject

Bellow is the JSON data to inject into the template. The key names should match the template markers. The file is called invoice_data.json:

{
  "id": 42, # the corresponding marker to use in the template is {d.id}
  "date": 1492012745, # {d.date}
  "company": {
    "name": "awesomeCompany", # {d.company.name}
    "address": "77 Bleecker Street", # {d.company.address}
    "city": "Manhattan, New York",
    "postalCode": 10012
  },
  "customer": {
    "name": "customerName",
    "address": "2 Random Street",
    "city": "Far Far Away",
    "postalCode": 85000
  },
  "products": [
    {
      "name": "product 1", # {d.products[i=0].name}
      "priceUnit": 0.1,
      "quantity": 10,
      "priceTotal": 1
    },
    {
      "name": "product 2",
      "priceUnit": 0.2,
      "quantity": 20,
      "priceTotal": 4
    }
  ],
  "total": 5
}

Carbone setup

Firstly, install the Carbone dependency:

# NPM
$ npm install carbone --save
# YARN
$ yarn add carbone

In the index.js, insert the code to generate the report:

/** 1 . dependencies */
const carbone = require('carbone');
const fs = require('fs');

/** 2 . input template file name and output file name */
const _fileInputName = './invoice_template.odt';

/** 3 . Data to inject */
const _data = require("./invoice_data.json")

/** 4 . Options object */
const _options = {
  convertTo: 'pdf',
  reportName: 'invoice_{d.id}.pdf'
};

/** 5 . Call carbone render function */
carbone.render(_fileInputName, _data, _options, (err, result, reportName) => {
  if (err) {
    console.log(err);
  } else {
    fs.writeFileSync('./build/' + reportName, result);
  }
  process.exit();
});

That's a lot of code, here is the explanation:

It instantiates Carbone.
Definition of the filename template.
Import the JSON data.
An optional object can be passed to Carbone to define complement data, variables, translations, and more... In this case, the convertTo option defines the file export type and reportName the report filename.
The Carbone render function generates the report by taking as argument the template file name, the data object, and the options. If it succeeds, the final report is created with fs.writeFileSync. If the rendering fails, the callback function responds by filling the err variable. In this case, the error will be printed. To make the program stop at the end, process.exit() is necessary.

Preparing the Dockerfile

Before diving into Containers, you may need Docker basics before continuing. You can learn from the official Docker documentation 🐳 OR awesome dev.to tutorials ⚡️.

To make Carbone work properly, the environment needs to be defined:

Required: Carbone is based on NodeJs (Node 8 minimum).
Optional: Libre Office has to be installed to generate the report into PDF format. Learn more about PDF export.

Let's create a Dockerfile with these specifications:

# 1
FROM ideolys/carbone-env-docker

# 2
ENV DIR /app

# 3
WORKDIR ${DIR}

# 4
COPY . ${DIR}

# 5
RUN npm install

# 6
CMD [ "node", "index.js" ]

Details about this Dockerfile:

"ideolys/carbone-env-docker" is a Node 8 image with Libre Office already Installed. You can check the DockerFile on Github. During the docker run command, the image will be pulled from the Docker Hub.
the ENV instruction defines the app directory into environment variables
the WORKDIR instruction sets the working directory to /app
the COPY instruction copies the local files and directory into the working directory
Command to install the npm dependencies
the CMD instruction is used to define the default command to run. In our case, node index.js is executed.

Before continuing, here is the actual project directory:

Run the following command on your terminal to build the image from the Dockerfile :

$ docker build . -t myapp-carbone:1.0

On success, the message "Successfully tagged myapp-carbone:1.0" appears at the end of the process.

To verify if the image has been built, run docker image ls:

Finally, run the image in a container through this command:

$ docker run -v $(pwd)/build:/app/build myapp-carbone:1.0
$ # `-v` argument is used to persist and save the generated report into a `build` folder

After running the container, the generated report appears on the build folder 🎉 Let's take a look:

The use of Docker can be pushed further, for example, use a template directory as a volume to share templates with the container.

Conclusion

First, We covered how to set up a Carbone project with an invoice ODT template and the data to inject. Thereafter, we created the Dockerfile to make Carbone work properly. Finally, we executed the container to generate the invoice.

Do not hesitate to contact me. If you need information about Carbone, here is an article to learn the basis: Carbone Turorial - Fast and Easy report generator (as fast as a spaceship 🚀)

Leave a like to support my article or follow me to be notified of my next articles 🔥

Thanks for reading!

Generate dynamic sheets from ODS templates with CarboneJS

Steeve — Sat, 28 Mar 2020 17:37:27 +0000

Creating dynamic sheets is possible but it is not documented on the CarboneJS website and github.
The use of variables is the only way to generate new sheets on ODS files. Unfortunately, it does not work with Excel templates. before taking this forward, make sure to understand Carbone basis and here is a quick reminder about Carbone variables.

As an example, let’s generate an ODS report with multiple sheets containing fruit nutritional values.
First, let’s define 2 variables on the template:

{#sheet1 = d.fruits[i].name}
{#sheet2 = d.fruits[i+1].name}

Secondly, insert the variables on the sheet names:

{$sheet1} // for sheet number 1
{$sheet2}  // for sheet number 2

During the rendering, CarboneJS replace the variables with the repetition markers {d.fruits[i].name} and {d.fruits[i+1].name} to generate new sheets that inherit content from the first sheet.

The example below comprises of an ODS template, a JSON data, the Javascript and a screenshot of the generated document.

The following shows a template example (filename: template.ods):

The index.js to generate the report is as follows:

// Imports 
const fs = require("fs");
const carbone = require("carbone");

// Files input/ouput
const FILE_INPUT = "./template.ods";
const FILE_OUTPUT = "./result.ods";

// Data to inject
const DATA = require("./data.json");

// Report rendering
carbone.render(FILE_INPUT, DATA,  async (err, result) => {
  if (err) {
    return console.error(err);
  }
  await fs.writeFileSync(FILE_OUTPUT, result);
});

The JSON data that contain the fruit list (filename: data.json):

{
  "fruits": [
    {
      "name": "apple",
      "nutrients": [
        {
          "type": "energy",
          "value": 52,
          "unit": "Kcal"
        },
        {
          "type": "Carbohydrates",
          "value": 13.81,
          "unit": "g"
        },
        {
          "type": "Protein",
          "value": 0.26,
          "unit": "g"
        },
        {
          "type": "Fats",
          "value": 0.17,
          "unit": "g"
        },
        {
          "type": "Cholesterol",
          "value": 0,
          "unit": "g"
        },
        {
          "type": "Dietary Fiber",
          "value": 2.4,
          "unit": "g"
        }
      ]
    },
    {
      "name": "banana",
      "nutrients": [
        {
          "type": "energy",
          "value": 89,
          "unit": "Kcal"
        },
        {
          "type": "Carbohydrates",
          "value": 22.84,
          "unit": "g"
        },
        {
          "type": "Protein",
          "value": 1.09,
          "unit": "g"
        },
        {
          "type": "Fats",
          "value": 0.33,
          "unit": "g"
        },
        {
          "type": "Cholesterol",
          "value": 0,
          "unit": "g"
        },
        {
          "type": "Dietary Fiber",
          "value": 2.6,
          "unit": "g"
        }
      ]
    },
    {
      "name": "strawberry",
      "nutrients": [
        {
          "type": "energy",
          "value": 53,
          "unit": "Kcal"
        },
        {
          "type": "Carbohydrates",
          "value": 12.75,
          "unit": "g"
        },
        {
          "type": "Protein",
          "value": 1.11,
          "unit": "g"
        },
        {
          "type": "Fats",
          "value": 0.33,
          "unit": "g"
        },
        {
          "type": "Cholesterol",
          "value": 0,
          "unit": "g"
        },
        {
          "type": "Dietary Fiber",
          "value": 3.3,
          "unit": "g"
        }
      ]
    }
  ]
}

Finally, execute the index.js:

$ node index.js

Voila, the generated document result.ods contains sheet for every fruit 🍎🍌🍓:

Conclusion

We have covered how to generate multiple sheets from an ODS template. Carbone can be used to render complex (and awesome) reports, do not hesitate to contact me for any help.

If you like the Carbone project, feel free to fork and contribute: Github.

Leave a like/comment or follow me to support this article 🍻

Thanks for reading!

Carbone Tutorial: fast and easy report generator (as fast as a spaceship 🚀)

Steeve — Mon, 14 Oct 2019 18:53:11 +0000

Carbone

This article is a tutorial about Carbone, an open-source report generator available on github. I have been working on it since some time now but I do feel a lack of visibility for this awesome project.

Everything mentioned in this tutorial is available on the carbone documentation.

Table of content

Introduction
Generating our first report
Rendering options

Introduction

Some years ago, I remember one of my missions (you may have encountered): generate invoices through HTML/CSS/DB/JS (or other broken frameworks). I spent so much hours to perfectly copy the report template and find some tricks to export it to PDF (or other formats). After spending a lot of time on one report, a mate gives you the following feedback:
"It's not right here, can you change this? the design isn't right here. etc.."
Then, you lose hours in fixing the latter: It was time-consuming and not that easy 😅

Anyway, an open-source project makes the life easier * Start 1960 Funky Groovy Music 🎶 * :

🔥 Carbone ! https://github.com/Ideolys/carbone

Carbone is a mustache-like template engine that analyses your template and injects data in the document. You can export it into the same format or any other formats: ODF, DOCX, PDF, XLSX, PPT, ODS, Text, CSV and more. A simple example step by step:

Prepare your report template using your favorite text editor (LibreOffice, PowerPoint, etc...). Insert JSON-like mustache markers {d.name} directly in your document.
Fetch your JSON data from your API or any storage.
Carbone analyses and injects your data into your template and you are done.
* 🎶 enjoying funky groovy music 🎉 *

Now, time to generate our first document.

Generating our first report

Our goal is to generate a PDF document from an ODT template.

Set up

(required) Node 8 minimum.
(optional) Install LibreOffice if you want to generate your documents in PDF format (only for pdf). For this tutorial, it can be downloaded here: https://www.libreoffice.org/download/download/.

Install Carbone with NPM:

$ npm install carbone --save

Create the template

We begin with creating our template with LibreOffice by inserting some variables into single curly braces by adding d. in front of them. This is used by the carbone parser to identify variables. Finally, save the document as template.odt. For this step, you can use your favorite text editor (Word, Excel, Powerpoint).

Create an index.js file and prepare a JSON data:

  var data = {
    firstname : 'John',
    lastname : 'Wick'
  };

Next, import carbone and call the render function by passing the template created, JSON data and the options. In callback, the path of the PDF File that will be generated and the binary are passed in fs.writeFileSync() method.

const fs = require('fs');
const carbone = require('carbone');

// data object to inject
let data = {
  firstname : 'John',
  lastname : 'Wick'
};

// options object is used to pass more parameters to carbone render function 
let options = {
  convertTo: 'pdf' //can be docx, txt, ...
}

carbone.render('./template.odt', data, options, (err, res) => {
    if (err) {
      return console.log(err);
    }
    // fs is used to create the PDF file from the render result
    fs.writeFileSync('./result.pdf', res);
    process.exit();
});

The final step, execute the file.

$ node index.js

Voila, our first PDF report has been generated ! 🎉

It was a really basic example, you can do exactly the same with different file formats with any kind of design. Next, this tutorial continues and dives into more advanced (and cool) options!

Rendering options

Meanwhile, Carbone offers options for rendering which can be useful. Here is an example of some available options:


let options = {
  convertTo    : 'pdf',
  lang         : 'en-us',
  complement   : {}, 
  variableStr  : '{#def = d.id}',
  reportName   : '{d.date}.odt',
  enums        : {
    'ORDER_STATUS' : ['open', 'close'],
    'SPEED' : {
      10 : 'slow' 
      20 : 'fast' 
    }
  },    
  translations : {
    'fr-fr' : {'one':'un' },
    'es-es' : {'one':'uno'}
  }
}

The options object can be passed to the render function or to carbone.set(options).

Let's go into the details!

convertTo

Define the file type to generate. It can be a string with different format:"pdf", "ODT", "TXT", "xlsx", "docx", "ods", etc...
Also, it can be an object for CSV export:

let options = {
  convertTo: {
    formatName    : 'csv',
    formatOptions : {
      // you can define your own separators and delimiters
      fieldSeparator : '|', 
      textDelimiter  : '*',
      // utf-8, you can defined the system character set
      // check out the list: https://wiki.openoffice.org/wiki/Documentation/DevGuide/Spreadsheets/Filter_Options#Filter_Options_for_Lotus.2C_dBase_and_DIF_Filters
      characterSet   : '76' 
    }
  }
}

Example:

(An article is coming soon about array repetitions, nested array, and more, stay tuned! Follow me on dev.to)

complement

You can add complement data in the template:

var options = {
    complement: {
       johnWickQuote: "I'd like to make a dinner reservation for 12."
    }
}

Then, your template can be accessed { c. } instead of { d. }:

variableStr (alias)

This option is used to pass variables to the carbone template. The carbone documentation mentions alias, it is doing exactly the same thing: alias == variableStr. For example, you can insert in the document an alias where special characters like square brackets are not allowed. To define it:

let options: {
  variableStr: '{#version = d.versionDoc}'
}

Then you can use it:

Carbone offers a lot of possibilities about conditional logic through formatters. Again, I will explain further in another article.

reportName

The report name is passed to the callback function as third argument. It can be useful to inject dynamic data into the title, then receive it to create the file in the carbone callback. For example:

let options: {
  reportName: 'invoice_{d.id}_{d.date}.odt'
}

enums

Enums are used with the convEnum formatter, I will explain the formatters in details (coming soon).

lang & translations

I will explain translations in another article (coming soon).

The end

We have covered a lot about Carbone, it might have been difficult to explain at some point. Do not hesitate to comment for any help.

If you like the project, don't hesitate to fork and contribute (#hacktoberfest is not finished yet 🍻 hehe): Github.

Leave a like, comment, or follow me to support my first article.

Thanks for reading!

* funky groovy music fades out... 🎶 *

DEV Community: Carbone

Cheat Sheet for Carbone

Essential Carbone Templating Syntax

1. Basic Placeholder

2. Nested Placeholder

3. Access Parent Property

4. Array Access with Static Index

5. Conditional Logic

6. Default Value

7. Loop (Array Iteration)

8. Loop of Nested Arrays

9. Filter a Loop

10. Sort a Loop

11. Formatters

11.1 Text Formatters

11.2 Number Formatters

11.3 Currency Formatters

11.4 Date Formatters

11.5 Array Formatters

12. Colors

13. Inject HTML from WYSIWYG or Code Editors

14. Merge PDFs

15. Images

16. Charts

17. Barcodes

18. Translations

19. Hyperlinks

20. Electronic Signatures

Conclusion

Creating dynamic reports with CarboneJS V2

Dynamic variables in all formatters

Dynamic content block and conditional formatters

Iterate on attributes of objects

Beta - supports dynamic charts rendering in XLSX files

Conclusion

Use CarboneJS into Docker Container 🐳

Introduction

Preparing the template

Preparing the data to inject

Carbone setup

Preparing the Dockerfile

Conclusion

Generate dynamic sheets from ODS templates with CarboneJS

Conclusion

Carbone Tutorial: fast and easy report generator (as fast as a spaceship 🚀)

Carbone

Table of content

Introduction

Generating our first report

Set up

Create the template

Rendering options

convertTo

complement

variableStr (alias)

reportName

enums

lang & translations

The end

Related articles