ID	Name	Role
{d.users[i].id}	{d.users[i].name}	{d.users[i].role}
{d.users[i+1]}

ID	Name	Role
1	Alice	Admin
2	Bob	Editor
3	Charlie	Viewer

element is hidden if `d.showDiv` is false. - The

element is hidden if `d.showParagraph` is false. - The element is invisible if `d.showSpan` is false. ```cdata { "display": "none", "showDiv": false, "showParagraph": false, "showSpan": false } ``` ```ctemplate

This element is hidden and takes no space, only if 'showDiv' is 'true'.

This element is hidden and takes no space, only if 'showDiv' is 'false'.

This paragraph is hidden but occupies space, only if 'showParagraph' is 'false'.

This element is invisible but still clickable, only if the 'showSpan' is 'false'. ``` ```cresult

This paragraph is hidden but occupies space, only if 'showParagraph' is 'false'.

This element is invisible but still clickable, only if the 'showSpan' is 'false'. ``` #### Inject CSS Properties Example This example demonstrates how to dynamically inject entire CSS properties into an HTML element using Carbone tags. Two methods are available: - **Direct Injection**: The first tag injects the value of d.imageStyle directly into its style attribute. - **Conditional Injection**: The second tag uses a condition to determine which CSS property to apply, either the value of `d.imageStyle` or a static string "display:block". ```cdata { "showImage": true, "imageStyle": "display: none;" } ``` ```ctemplate Hidden Image

``` ```cresult Visible Image

``` #### Inject Style Attribute Example This example shows how to inject an entire style attribute from your dataset into an HTML element. - **Direct Injection**: The first button uses the style defined in `d.buttonStyles1`. - **Conditional Injection**: The second button applies the value of `d.buttonStyles1` if `d.buttonTheme` is "forest", otherwise it uses the value of `d.buttonStyles2`. ```cdata { "buttonTheme": "ocean", "buttonStyles1": "style="background-color: green;color: white;border: none;"", "buttonStyles2": "style="background-color: black;color: red;border: 1px solid white;"" } ``` ```ctemplate ``` ```cresult ``` #### Inject HTML Block This example demonstrates how to inject raw HTML blocks from your dataset into your template using conditions and the **:html** formatter. - **Direct Injection**: The first line directly renders the HTML stored in `d.noteSection`. - **Conditional Injection**: The second line conditionally renders either `d.noteSection` if `d.displayNote` is true, or `d.nothingSection` if false. ```cdata { "displayNote": false, "noteSection": "

Note: Maintenance at 2 AM UTC.

", "nothingSection": "Nothing Significant To Report." } ``` ```ctemplate {d.noteSection:html} {d.displayNote:ifEQ(true):show(d.noteSection):elseShow(d.nothingSection):html} ``` ```cresult

Note: Maintenance at 2 AM UTC.

Nothing Significant To Report. ``` ### Drop / Keep The `:drop()` and `:keep()` formatters allow you to conditionally remove or retain elements (such as tables, rows, or paragraphs) in your HTML templates. These formatters are especially useful for dynamic content generation, where you want to show or hide elements based on data conditions. Syntax: - **:drop(element)** : Removes the element if the condition is true. - **:keep(element)** : Retains the element if the condition is true. | Element | Description | Tag Position | Example | | --- | --- | --- | --- | | p | Drop/keep a paragraph | Within a paragraph | {d.text:ifEM:drop(p)} | | row | Drop/keep a table row | Inside a table cell | {d.condition:ifNE(value):keep(row)} | | col | Drop/keep an entire table column | In any cell of the target column | {d.condition:ifEQ(value):drop(col)} | | table | Drop/keep an entire table | Within a table row | {d.condition:ifEQ(value):drop(table)} | | div | Drop/keep a div block | Within a div element | {d.condition:ifEQ(value):drop(div)} | | span | Drop/keep a span element | Within a span element | {d.condition:ifEQ(value):drop(span)} | **Notes** - For paragraphs and rows, you can specify a second parameter to drop/keep the next N elements (e.g., `:drop(p, 3)`). This is not supported for `col`. - No Chaining: Do not chain other formatters after :drop() or :keep(). - HTML-Specific: Only `table`, `col`, `row`, `p`, `div`, and `span` elements are supported in HTML templates. - Clean Output: The Carbone tag is removed from the final report. #### Drop a Table Example ```cdata { "showTable": false, "list": [ { "name": "Model 5" }, { "name": "Model 3" }, { "name": "Falcon Heavy" } ] } ``` ```ctemplate {d.showTable:ifEQ(false):drop(table)}

{d.list[i].name}

{d.list[i+1].name}

``` ```cresult ``` #### Drop a Table Row Example ```cdata [ { "name": "Falcon 9" }, { "name": "Model 5" }, { "name": "Model 3" }, { "name": "Falcon Heavy" } ] ``` ```ctemplate

{d[i].name}{d[i].name:ifIN('Falcon'):drop(row)}

{d[i+1].name}

``` ```cresult

Model 5

Model 3

``` #### Drop a Paragraph Example ```cdata { "text": "" } ``` ```ctemplate

{d.text}{d.text:ifEM:drop(p, 2)}This paragraph and the next one will be dropped if 'text' is empty.

This paragraph will also be dropped.

This paragraph will remain.

``` ```cresult

This paragraph will remain.

``` ### Conditional Sections The pair of `:showBegin/:showEnd` and `:hideBegin/;hideEnd` formatters allow you to conditionally display a section of content in your HTML templates. These formatters are useful when you want to show/hide whole pages or groups of text, tables, or other elements based on data conditions. Syntax: - `:showBegin` or `:hideBegin`: Marks the start of a block to show/hide if the condition is true. - `:showEnd` or `hideEnd`: Marks the end of the block. #### showBegin / showEnd Example The **details** section containing a list is hidden using the `showBegin/showEnd` formatters, only if the `showDetails` field is `true`. ```cdata { "showDetails": false, "product": "Carbone Pro" } ``` ```ctemplate

Product: {d.product}

{d.showDetails:ifEQ(true):showBegin}

Details:

Feature 1
Feature 2

{d.showDetails:ifEQ(true):showEnd}

Thank you for using Carbone!

``` ```cresult

Product: Carbone Pro

Thank you for using Carbone!

``` #### hideBegin / hideEnd Example The **greetings** section is deleted when the field `name` is `undefined/null/empty`. ```cdata { "name": null } ``` ```ctemplate

Dashboard

{d.name:ifEM:hideBegin} Welcome {d.name}! {d.name:ifEM:hideBegin} ``` ```cresult

Dashboard

``` ## Pictures Dynamic pictures allow you to inject images into your documents dynamically using data from your JSON input. For HTML templates, use the `` tag with the **src** attribute pointing to one of the following: - **Absolute URLs** (e.g., `https://carbone.io/img/carbone-logo.svg`). Carbone does not support relative paths (e.g., `/images/logo.png` or `../assets/photo.jpg`). - **Data-URIs** (Base64 encoded, e.g., `data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEASABIAAD...`). ```cdata { "userProfile": { "name": "John Doe", "profilePictureUrl": "https://carbone.io/images/john-doe.jpg", "profilePictureBase64": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEASABIAAD..." } } ``` ```ctemplate User Profile

Welcome, {d.userProfile.name}!

``` ```cresult User Profile

Welcome, John Doe!

``` To change the dimensions or scaling of an image, you can use HTML attributes or CSS styling for more control and responsiveness: - Set fixed dimensions directly in the `` tag, e.g., ` Dynamic Image

`. - Use CSS for sizing and changing aspect ratios. Inline styles can be used directly within your HTML tags: ` Dynamic Image

`. ## Charts Use the `:chart` formatter to dynamically inject charts into HTML templates: embed a Carbone tag in the **src** attribute of an `` tag. ```cdata { "chartOptions": { "type": "echarts@v5a", "width": 600, "height": 400, "theme": null, "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" }] } } } ``` ```ctemplate

Sales Overview

``` ```cresult

Sales Overview

``` In this example, the `{d.chartOptions:chart}` tag is replaced with an SVG image of the chart, which is dynamically generated based on the data provided in your dataset. Key points: - **Supported ECharts Version:** Carbone supports echarts@v5 (default) and echarts@v5a (optimized for SVG compatibility). - **Styling:** Chart styling must be defined within the JSON dataset. - **No External Dependencies:** Chart configuration does not support external dependencies (e.g., JS scripts). - **Dimensions:** You can adjust the dimensions of the chart in two ways: - Using the `` Tag: Set the **width** and **height** attributes directly on the `` tag to control the size of the chart as it appears in the HTML document. - Using the EChart Configuration: Define the **width** and **height** within the EChart configuration object in your JSON dataset. This allows you to specify the dimensions programmatically. ## Colors You can dynamically set or change CSS color properties in your HTML templates using Carbone tags. This is useful for theming, conditional styling, or personalization based on your dataset. Two Methods are available: - **Direct Injection**: Inject color values directly from your dataset into style attributes. - **Conditional Injection**: Use Carbone’s `:ifEQ`, `:show`, and `:elseShow` to conditionally apply colors. ```cdata { "theme": "dark", "textColor": "#ffffff", "bgColor": "#1a1a1a", "alertColor": "#ff4444", "isUrgent": true } ``` ```ctemplate

This div uses colors from the dataset.

{d.isUrgent:ifEQ(true):show('Urgent message!'):elseShow('Normal message.')}

``` ```cresult

This div uses colors from the dataset.

Urgent message!

``` ## Formatters Carbone provides built-in formatters to transform data values directly inside your HTML templates. Formatters are chained to a Carbone tag using the `:` operator (e.g. `{d.value:formatterName(args)}`). The sections below cover the most commonly used formatters for dates, numbers, and currencies. For the full list of available formatters, see the [Formatters documentation](/documentation/design/formatters/overview.md). ### Date Formatting Use the `:formatD()` formatter to display dates in any format. The pattern follows [Day.js](https://day.js.org/docs/en/display/format) tokens (e.g. `YYYY`, `MM`, `DD`, `dddd`). ```cdata { "orderDate": "2025-03-15T14:30:00Z", "deliveryDate": "2025-04-01T00:00:00Z" } ``` ```ctemplate

Order date: {d.orderDate:formatD('DD/MM/YYYY')}

Delivery date: {d.deliveryDate:formatD('dddd DD MMMM YYYY')}

``` ```cresult

Order date: 15/03/2025

Delivery date: Tuesday 01 April 2025

``` For the full list of supported date patterns and options, see the [Date formatter documentation](/documentation/design/formatters/date.md). ### Number Formatting Use the `:formatN()` formatter to control decimal precision and thousands separators. The output format automatically adapts to the `lang` option passed at render time. ```cdata { "quantity": 1234567.891, "rating": 4.5 } ``` ```ctemplate

Quantity: {d.quantity:formatN(2)}

Rating: {d.rating:formatN(1)}

``` ```cresult

Quantity: 1,234,567.89

Rating: 4.5

``` For the full list of options, see the [Number formatter documentation](/documentation/design/formatters/number.md). ### Currency Formatting Use the `:formatC()` formatter to display monetary values with the correct currency symbol, decimal precision, and locale-aware formatting. ```cdata { "price": 4999.99, "discount": 250 } ``` ```ctemplate

Price: {d.price:formatC(2, 'EUR')}

Discount: {d.discount:formatC(2, 'USD')}

``` ```cresult

Price: €4,999.99

Discount: $250.00

``` For the full list of supported currencies and options, see the [Currency formatter documentation](/documentation/design/formatters/currency.md). ## Barcodes Carbone supports barcode generation in HTML templates using the `:barcode` formatter. This allows you to inject barcodes as SVG images directly into your documents. How It Works: 1. Use the `:barcode` formatter in an tag's src attribute. 2. Specify the barcode type (e.g., `qrcode`, `code128`, `ean13`). [See the full list of supported barcode types here.](/documentation/design/advanced-features/barcode.md#barcodes-as-image-supported-barcodes) 3. Optional - Adjust dimensions either via the `` tag attributes or within the formatter. ```cdata { "productCode": "123456789", "qrData": "https://example.com/product/123456789" } ``` ```ctemplate QR Code

``` ```cresult QR Code

``` ## Hyperlinks You can dynamically set the **href** attribute of tags using Carbone tags. This is useful for generating links based on your dataset, such as personalized URLs. ```cdata { "documentationUrl": "https://carbone.io/documentation/", "isLoggedIn": true, "profileUrl": "https://account.carbone.io/", "defaultUrl": "https://account.carbone.io/login", "product": { "name": "Carbone Cloud", "url": "https://carbone.io/pricing.html" } } ``` ```ctemplate Read the Docs {d.isLoggedIn:ifEQ(true):show('Your Profile'):elseShow('Login')} Learn about {d.product.name} Documentation ``` ```cresult Read the Docs Your Profile Learn about Carbone Cloud Documentation ``` ## Inject HTML in HTML Carbone allows you to inject raw HTML strings from your dataset into your templates using the **:html** formatter. Without it, `<` and `>` characters are automatically encoded as `<` and `>`, which prevents the HTML from being rendered as markup. ```cdata { "welcomeMessage": "Welcome! Here’s your dashboard.", "alertMessage": "

⚠️ Maintenance at 2 AM UTC.

", "isAdmin": true, "adminPanel": "Go to Admin Panel", "userPanel": "Go to Profile" } ``` ```ctemplate

{d.welcomeMessage}

{d.welcomeMessage:html}

{d.isAdmin:ifEQ(true):show(d.adminPanel):elseShow(d.userPanel):html} ``` ```cresult

<strong>Welcome!</strong> Here’s your dashboard.

Welcome! Here’s your dashboard.

Go to Admin Panel ``` ## Page Breaks To insert a page break in PDFs generated from HTML templates, first define the following CSS class in your template’s `

Contents

{d.sections[i].title}
- {d.sections[i].subSections[i].title}
{d.sections[i].subSections[i+1]}

{d.sections[i]}

{d.sections[i].title}

{d.sections[i].subSections[i].title}

{d.sections[i].subSections[i].content}

{d.sections[i+1].subSections[i+1]}

``` ```cresult TOC Example

Contents

First Point Header
- First Sub Point 1
- First Sub Point 2
Second Point Header
Third Point Header

First Point Header

First Sub Point 1

This is the content for the first sub-point. You can add as much detail as needed here.

First Sub Point 2

This is the content for the second sub-point. More details or paragraphs can go here.

Second Point Header

Third Point Header

``` ## Page Formats By default, Carbone generates a PDF document in the `A4` format. Insert the `` custom element in the HTML template, and use the **paper-size** option to specify standard page sizes: | Value | Description | | --- | --- | | `A0`, `A1`, `A2`, `A3`, `A4`, `A5`, `A6` | ISO A-series paper sizes | | `Letter` | US Letter (8.5 × 11 in) | | `Legal` | US Legal (8.5 × 14 in) | | `Tabloid` | Tabloid (11 × 17 in) | | `Ledger` | Ledger (17 × 11 in) | **Note:** Additional [PDF Conversion options](#pdf-conversion-options) (margins, scaling, headers/footers, etc.) are available. ### Example This sets the PDF to A3 size in landscape orientation. ```html ``` ## Headers Footers Carbone allows you to define custom headers and footers for PDF documents generated from HTML templates. **Custom Elements** - ``: Defines the header for every page (e.g. [header example](#headers-footers-custom-header-example)). - ``: Defines the footer for every page (e.g. [footer example](#headers-footers-custom-footer-example)). **Key Features** - Include static text, dynamic content (using Carbone tags), and page numbers. - For page numbering, use: - `` for the current page. - `` for the total pages. - Insert only Inline CSS because external stylesheets are not supported. - Headers and footers are PDF-only and are ignored in HTML output. - Elements render in PDF even if hidden or commented out in the HTML template. **Limitation** The same header/footer applies to every page: A `` or `` cannot be turned on or off, or changed, on a specific page. For example, hiding the page number on the cover page with a CSS rule like `.pageNumber:first-child { display: none; }` will not work — the rule is silently ignored. This is a known limitation we are working on. In the meantime, two workarounds are available: 1. **Split the document into two HTML templates.** Put the cover page in one template (without ``) and the body of the document in a second template (with ``). Use the [`:appendTemplate`](/documentation/design/advanced-features/file-operations.md#appendtemplate-templateorversionid-position) formatter to concatenate them into one. The drawback is that page numbering restarts at 1 on the second template, as the two PDFs are merged after rendering. 2. **Use a DOCX, PPTX, or XLSX template instead.** Office formats natively support different headers and footers on the first page, on odd/even pages, or per section. A single template can have a cover page without a footer and the rest of the document with one — no template-splitting or PDF concatenation required. ### Custom Header Example This example demonstrates a custom PDF header with dynamic content: - Displays a centered title (Company Report | Q3 Financials). - Shows the current date (Generated: 2025-10-17) using Carbone's built-in `{c.now}` chained with `:formatD('YYYY-MM-DD')` to format dates. - Includes the user's name (User: John Doe) from the dataset. ```cdata { "reportTitle": "Q3 Financials", "user": { "name": "John Doe" } } ``` ```ctemplate

Company Report | {d.reportTitle} Generated: {c.now:formatD('YYYY-MM-DD')} User: {d.user.name}

``` ```cresult

Company Report | Q3 Financials Generated: 2025-10-17 User: John Doe

``` ### Custom Footer Example This example demonstrates a custom PDF footer with: - Page numbering (e.g., "Page 5 of 10") using `` and ``. - Dynamic copyright text injected from the dataset (`d.year` and `d.company`). ```cdata { "year": "2025", "company": "Acme Inc" } ``` ```ctemplate

Page of

``` ```cresult

Page 5 of 10

``` ## Convert HTML to PDF > ℹ️ **Note:** **Using Carbone with AI-generated content:** LLMs like ChatGPT, Claude, and Gemini can generate HTML templates. A typical workflow is: prompt your LLM to produce a structured HTML document → inject dynamic fields with Carbone tags (e.g. `{d.clientName}`, `{d.date}`) → call the Carbone API with your JSON data to render the final PDF. Ideal for automated invoices, reports, contracts, and certificates. To generate a PDF from an HTML template using the Carbone API, follow this workflow: 1. **Prepare Two Files**: Create an **HTML Template** (with Carbone tags e.g. `{d.name}`) and a **JSON dataset** to populate the template. 2. **Generate a PDF**, you have three options: - Use the official Carbone integrations for platforms like N8N, Make, Zapier, Airtable, or Bubble. - **Or**, use one of the Carbone SDKs (Node.js, Go, Python, Java, JavaScript, or PHP). - **Or**, send a `POST /render/template` HTTP request to the [Carbone API](/documentation/developer/http-api/introduction.md). Here’s an example using curl: ```bash curl --location --request POST 'https://api.carbone.io/render/template?download=true' \ --header 'carbone-version: 5' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer API_TOKEN' \ --data-raw "{ \"data\": {}, \"template\": \"$(base64 -i webpage.html)\", \"convertTo\": \"pdf\", \"converter\": \"C\" }" \ --output result.pdf ``` > 💡 **Linux users**: replace `base64 -i webpage.html` with `base64 -w 0 webpage.html` **Key Parameters** | Parameter | Description | | --- | --- | | `template` | Your HTML template, encoded as a Base64 string. | | `data` | JSON dataset used to populate the template. | | `convertTo` | Must be set to "pdf". | | `converter` | Must be set to `"C"` to use the Chromium rendering engine; output matches what you see in Chrome. | | `?download=true` | Query parameter to download the document as a stream. | | `Authorization` | Header required for the Carbone Cloud API. [Get your API key here.](https://account.carbone.io/) | For more details, refer to the [Carbone API Documentation](/documentation/developer/http-api/introduction.md). ## PDF Conversion Options Customize the PDF document by inserting the `` element in the HTML template, and provide [options](#pdf-conversion-options) as attributes. ### Example This configures the PDF to use A3 size, landscape orientation, a 2.5-inch bottom margin, and disables background printing. ```html ``` ### Available Options | Option | Type | Description | | --- | --- | --- | | `landscape` | boolean | Paper orientation. Defaults to `false`. | | `display-header-footer` | boolean | Display header and footer. Defaults to `false`, or `true` if header/footer is provided | | `print-background` | boolean | Print background graphics. Defaults to `true`. | | `scale` | number | Scale of the webpage rendering. Defaults to `1`. | | `paper-size` | string | Letter, Legal, Tabloid, Ledger, A0, A1, A2, A3, A4, A5, A6 (Default: A4) | | `paper-width` | number | Overwrite Paper width in inches. Defaults to `8.27` inches (Default: A4) | | `paper-height` | number | Overwrite Paper height in inches. Defaults to `11.7` inches (Default: A4) | | `margin-top` | number | Overwrite Top margin in inches. Defaults to `0.5` inches. | | `margin-bottom` | number | Overwrite Bottom margin in inches. Defaults to `0.5` inches. | | `margin-left` | number | Overwrite Left margin in inches. Defaults to `0.5` inches. | | `margin-right` | number | Overwrite Right margin in inches. Defaults to `0.5` inches. | | `page-ranges` | string | Paper ranges to print, e.g., `1-5, 8, 11-13`. Pages are printed in document order. No page appears more than once. Empty string prints entire document. Invalid ranges are ignored. An error is thrown if the start page is greater than the end page. | | `prefer-css-page-size` | boolean | Prefer CSS-defined page size. Defaults to `false`, in which case the content will be scaled to fit the paper size | | `generate-tagged-pdf` | boolean | Generate a tagged PDF/UA for accessibility. Enables semantic structure for screen readers. Defaults to `false`. | ## Translations and i18n Carbone can generate documents in any language from a single HTML template. Instead of maintaining one template per language, you define a **localization dictionary** and pass a `lang` option at render time — Carbone automatically substitutes all translated strings. Two mechanisms are available: - **`{t( )}`** for static text in the template (labels, headings, fixed strings). - **`:t` formatter** for dynamic text values coming from your JSON dataset (translated via a dictionary key). Locale-aware formatters such as `:formatD()`, `:formatN()`, and `:formatC()` automatically adapt their output to the target language as well. ```cdata { "data" : { "tool": "key1", "protection": "key2" }, "convertTo" : "pdf", "lang" : "en-us", "translations" : { "fr-fr" : { "Invoice" : "Facture", "Date" : "Date", "key1" : "Tournevis", "key2" : "Gants" }, "en-us" : { "Invoice" : "Invoice", "Date" : "Date", "key1" : "Screwdrivers", "key2" : "Gloves" } } } ``` ```ctemplate

{t(Invoice)}

{t(Date)}: {d.date:formatD('DD/MM/YYYY')}

Item	Quantity
{d.tool:t}	1
{d.protection:t}	2

``` ```cresult

Invoice

Date: 15/03/2025

Item	Quantity
Screwdrivers	1
Gloves	2

``` > ℹ️ **Note:** The localization dictionary can be passed directly in the API request body (`translations` field). For the complete reference including CLI tools and dictionary generation, see the [Translations i18n documentation](/documentation/design/advanced-features/translations-i18n.md). ## Comments Carbone processes all text in your template, including HTML comments (``). If you include Carbone tags (e.g., `{d.user.name}`) inside comments, they will be evaluated and replaced with data. **Best Practices:** - **Documentation and Notes**: If you must include Carbone tags in comments for taking notes, you can "escape" them by breaking the syntax so Carbone won’t interpret them: ``. - **Dynamic Comments**: If a whole HTML comment is injected, you must use the `:html` at the end of the Carbone tag (as described in the [documentation above](#inject-html-in-html)). ```cdata { "showComment": true, "user": { "name": "John" }, "comment": "" } ``` ```ctemplate User Profile {d.showComment:ifEQ(true):show(.comment):elseShow(''):html} ``` ```cresult User Profile ``` ## Related topics - [PDF templates](/documentation/design/template-formats/pdf.md) - [Markdown templates](/documentation/design/template-formats/markdown.md)

Welcome, {d.user.firstName} {d.user.lastName}!

Welcome, John Doe!

User List

User List

Dashboard

Dashboard

Welcome, {d.userProfile.name}!

Welcome, John Doe!

Sales Overview

Sales Overview

{d.sections[i].title}

{d.sections[i].subSections[i].title}

First Point Header

First Sub Point 1

First Sub Point 2

Second Point Header

Third Point Header

{t(Invoice)}

Invoice