Carbone Style Guide

This is the official style guide for the Carbone language. If you use Carbone in a project, it’s a great reference to avoid errors, bikeshedding, and anti-patterns.

Essential

These rules help prevent errors, so learn and abide by them at all costs. Exceptions may exist, but should be very rare and only be made by those with expert knowledge of Carbone. The following checklist avoids unexpected behaviors, avoids creating a corrupted document or avoids not printed values on the generated report.

Check if, each loops prints values with [i] and the end loop is defined with [i+1], such as {d.fruits[i].name}{d.fruits[i+1].name}. The [i+1] is used by Carbone to find the pattern to repeat.
Use the drop formatter to delete elements: images, paragraphs, table rows, shapes and charts.
Use the hideBegin/hideEnd or showBegin/showEnd formatters to hide a GROUP of elements.
Check if, each showBegin is followed by showEnd, or hideBegin with hideEnd.
Check if, every Carbone tags are defined on the JSON dataset. Otherwise, values and lists will not be printed on the report.
Check if, the variable type you are printing is the expected one, if it is a list of element (Array of objects), don't forget to use [i] and [i+1] to loop the whole table or use [i=0] to print only the first element.
Check if different loops are not mixed. The following example misbehaves the Carbone rendering and will generate a corrupted document : First loop: {d.fruits[i].name}{d.vegetables[i].name}{d.fruits[i+1].name} Second loop: {d.vegetables[i+1].name}. It should be: First loop: {d.fruits[i].name}{d.fruits[i+1].name}, Second loop: {d.vegetables[i].name}{d.vegetables[i+1].name}.
If the bindColor tag is used with a loop tag as an argument, check if the reference color is not applied at different places on the template, particularly in a different loop, it could return a corrupted report. For instance, on an ODT template, the green color #00FF00 is applied on a list of fruits {d.fruits[i].name}{d.fruits[i+1].name}. Changing colors dynamically would be with the expression {bindColor(#00FF00, #hexa) = d.fruits[i].newHexaColor}. However, if another text or loop has the green color #00FF00, the d.fruits[i].newHexaColor will be injected into another loop or document location that could generate a corrupted document.
Check if every formatters are chained, such as: {d.value:add(20):sub(10)}. They should not be embed or wrap into another formatter, the expression {d.value:add(20:sub(10))} does not work and is not recognized as a valid expression.
Check if every formatters, String arguments are surrounded by single-quote '. Do not use double-quotes or smart-quotes. The text editor may replace quotes with ones that cannot be interpreted by Carbone, to disable the option, follow this tutorial.
Check if dynamic images don't use pure base64 image, it must be a Data-URL or an URL, the image should look like this data:image/jpeg;base64,BASE64_IMAGE....
Check if the wrapping/anchor of special elements (images, shapes, text boxes) are set "In line with text".

Recommended

These rules have been found to improve creating and designing reports. We describe each acceptable option and suggest a default choice. That means you can feel free to make a different choice, as long as you’re consistent and have a good reason.

For consistency purpose, use LibreOffice as a text editor to design your templates because Carbone uses LibreOffice to render and convert files. MS Word documents are fully supported but generated reports could looks a bit differently as LibreOffice and Ms Word are handling XML-based file format specification differently.
When using conditional formatters showBegin/showEnd or hideBegin/hideEnd, only Break-lines (shift + Enter) should be inserted (learn more)

Use with Caution

Some features of Carbone exist to accommodate rare edge cases or smoother migrations from a legacy code base.

It is not recommended to use the following formatters: ifEmpty, ifEqual, int, toEn, toFixed, toFr, ifContain, convDate. They are and will still be supported, but simpler and more performant alternatives are available
It is not recommended to create loops with floating elements such as a loop of text boxes, the alternative is to change the anchor of the element at "In line with text", otherwise it could created unexpected results.
Avoid to use "mouse drag" to change a table column size. Instead change columns size by selecting the table column > right click > table properties > column > set the value of "preferred width"

Errors

If you got an error from Carbone Render API, Carbone Studio, CarboneJS or Carbone On-premise, check out the following page to understand the error: https://help.carbone.io/en-us/article/what-can-i-do-when-i-got-rendering-error-message-list-below-r1oznz/
If dynamic pictures are not injected into documents, it come from one of the following reasons: https://help.carbone.io/en-us/article/dynamic-pictures-are-not-rendered-into-my-document-what-is-happening-1jhafdu/?bust=1645431364737

Text editor Tips - MS Word

To repeat the first table row, go to the table properties and tick "Repeat as header at the top of each page"
To align shapes in tables, you should use Word and select the "Layout" Tab > Position "Align to center". Then Right Click on the shape > Text Wrapping > In Line With Text.
To change the padding in all table cells, Right click on the table > "table properties" > "Table" tab > Button "option" on the bottom. If you want to change the padding of only one cell: Right click on the table > "table properties" > "Cell" tab > "Options" > Untick "Same as the whole table"

If you didn't succeed to fix the issue after reading this checklist, reach the support on the chat. Before contacting the support, prepare a JSON data-set and a template to replicate the issue. Please, isolate the issue with the minimum of elements, it will be faster and easier for debugging.

The Carbone team is working actively to improve the error management in 2022 with explicit and accurate messages.

Updated on: 04/12/2023