Design best practices

Configuration of Microsoft Word and LibreOffice

Carbone uses single quotes ' (also known as straight quotes) to delimit text in formatter arguments, such as: {d.value:ifEQ(true):show('This is true!')}. Other types of quotes, such as double quotes, smart quotes, or chevrons, are not recognized by Carbone.

Text editors may automatically replace "straight quotes" with "smart quotes" which are not supported by Carbone.

Solution:

• MS Word: Go to the Tools > AutoCorrect Options > AutoFormat As You Type tab and ensure that the "Straight quotes" with “smart quotes” checkbox is cleared.
• LibreOffice: Go to Tools > AutoCorrect > Localized Options. Ensure that the "Replace" checkboxes for single and double quotes are disabled.

Designer guide

• String arguments of formatters must be surrounded by single-quote '. Do not use double-quotes or smart-quotes. See above.
• Avoid using floating elements inside a Carbone loop. Check if the anchor of special elements (images, shapes, text boxes) are set "In line with text".
• Use the drop formatter to delete elements: images, paragraphs, table rows, shapes and charts instead of showBegin/showEnd/hideBegin/hideEnd
• Store variable in temporary variable or use aliases to reduce the size of Carbone tags
• Use free and open source fonts for commercial use to avoid license issues

Frequently Asked Questions

Which template type should I use?

If your final document is a PDF, it's best to use DOCX or ODT templates. These formats offer robust support for pagination, headers, footers, and handle page text overflow more effectively because text and images are positioned relative to each other.

In contrast, texts and images in presentation formats (PPTX, ODP) are positioned absolutely, and each slide is independent. This means that if a loop generates too much content for one slide, a new slide will not be created automatically. You will need to manage this yourself using loop filters. For example, you can display the first 10 items on slide N, the next 10 items on slide N+1, and so on.

Some people use spreadsheets to create PDF documents. While this works, there are limitations that aren't necessarily related to Carbone. Others use HTML templates to generate PDFs, but it cannot compete with certain features provided by DOCX or ODT, such as repeating the header of a table on new pages.

For other document types, you can use any template you prefer. Here is a list of the most commonly used template file types with available Carbone feature.

You can even generate JScript file for industrial label printers made by Zebra and CAB!

How can I make the Carbone tag more compact?

There are two solutions:

• Use aliases to reduce code repetition.
• Only the font style and size of the first character { is taken into account in the generated document.
  You can reduce the font size of 99% of the Carbone tag like this: {d.my.very.long.carbone.tag}

Is it possible to bold text in the middle of a Carbone tag?

No, the tag is treated as a single piece. The printed style is based on the style of the first { in the tag.

How do I remove the last page break or comma in a loop?

Keep in mind that Carbone always repeats the i-th part, which includes the comma or the page break. Here are two solutions to overcome this:

• For page breaks: Refer to this tutorial. In the tutorial, {d.list[i]..list:len():sub(1):ifEQ(.i):drop(p)} can also be replaced with the shorter version {d.list[i, i=-1]:ifNEM:drop(p)}.

• For a list of items: Use array formatters to flatten an array without using a loop [i] -> [i+1].

Can I use spreadsheet (XLSX, ODS) formulas in a Template?

Spreadsheet formulas (XLSX, ODS) can be used in Carbone templates.

However, it's important to keep in mind that everything (cells, rows, sheets) can move when Carbone injects data into the template:

• Carbone does not interpret or adjust spreadsheet formulas (not yet!). It simply injects data into the spreadsheet without recognizing the presence of formulas.
• Carbone inserts the data first without computing any spreadsheet formulas. Then, it executes all spreadsheet formulas using its internal LibreOffice/OnlyOffice engine.
• And Excel and LibreOffice are not aware of Carbone's data injection.

Therefore, all preexisting spreadsheet formulas in the template must take into account for these potential shifts.

This tutorial explains some of the consequences of this process, particularly with totals: How to Compute Totals in Excel Spreadsheets When Carbone Injects New Lines.

How can I do {d.val} * 100 in a spreadsheet (XLSX, ODS)?

Solution 1:

Use only Carbone features: {d.val:mul(100)}.

Solution 2:

If you want to perform calculations in Excel, you must isolate the Carbone tag in a separate cell and use :formatN to ensure that the number is converted to an Excel-compatible number format.

• Cell A1: {d.val:formatN}
• Cell A2: = A1 * 100

Solution 3:

Include the Carbone tag in the Excel formula and use IFERROR to let Excel accept the Carbone tag:

= 100 * IFERROR("{d.val}", 0)

How can I make the document generation faster?

Carbone is highly optimized.

• 99% of the time is spent in LibreOffice for document conversion (DOCX -> PDF, ODT -> PDF...).
• 1% in Carbone for injecting the data, when there is no conversion

Here are few tips to optimize the document PDF conversion:

• Remove embedded fonts in your template
• Use ODT templates instead of DOCX templates
• Reduce image resolution
• Export the document in the same format as the template (DOCX -> DOCX), and perform the PDF conversion on your own.
• Select a different document converter. Carbone v5 offers new options: OnlyOffice, Chromium.
• Use asynchronous API

Some computed fields are not updated in DOCX/ODT (total page number, ...)

You can fix this issue by setting hardRefresh: true when calling the API.
This forces Carbone to use LibreOffice to update all computed fields in the DOCX.

Another solution is to add a hidden page number (in white text) to your document. Carbone will automatically set hardRefresh: true. To do this: Insert → Page Number.