Design

Smart conditional blocks

Show or hide an entire table, paragraph, ..., row, column with one simple Carbone tag
ENTERPRISE FEATURE Available for:
Carbone Cloud
Carbone On-premise
Embedded Carbone JS v4.0+

Why is it smart?

Why should you use smart conditional blocks instead of hideBegin/hideEnd or showBegin/showEnd or array filters?

Shorter syntax: You only need to write one Carbone tag instead of two (Begin + End).
Simpler to use: In some situations, it can be tricky to place hideBegin/hideEnd formatters in the document, such as when hiding a row of a table.
Cleaner output: The targeted element is removed without leaving whitespace.

Compatible with DOCX, ODT, ODS, ODP, XLSX, PPTX, and HTML templates.

A Carbone tag using :drop or :keep does not print anything in the generated report. The tag is removed when executed.

:drop/:keep(element)

Use the :drop formatter to remove elements from a document if the specified condition is true.
The :keep formatter works oppositely. It retains elements if the condition is true.

Element	Description	Accepted tag position
`row`	Drop or keep a table row	In a table row
`col`	Drop or keep an entire table column	In any cell of the target column
`p`	Drop or keep a paragraph	Within a paragraph
`img`	Drop or keep an image	Image title, description, or alt text
`table`	Drop or keep a table	Inside a table cell
`chart`	Drop or keep a chart	Alternative text of the chart
`shape`	Drop or keep a shape	Title, description, or alt text
`slide`	Drop or keep a slide	Inside a text box (ODP only)
`item`	Drop or keep a list item	Within a list item (ODP/ODT only)
`sheet`	Drop or keep a sheet	Inside a table cell (ODS only)
`h`	Drop or keep a heading or custom style element	Applies within the heading element (ODT only)
`div`	Drop or keep a div block	Within a div element (HTML only)
`span`	Drop or keep a span element	Within a span element (HTML only)

A second parameter can be used with p and row to drop or keep the next N paragraphs or rows. This is not supported for col. Example:

{d.text:ifEM:drop(p, 3)}: Drops the current paragraph and the next two paragraphs if d.text is empty.
{d.text:ifEM:drop(row, 3)}: Drops the current row and the next two rows if d.text is empty.

Known limitation:

ODS templates only support dropping/keeping col, row, img, and sheet.
XLSX templates only support dropping/keeping row and col.
PPTX templates only support dropping/keeping col, row, img, p, shape, chart, and table.
HTML templates only support dropping/keeping table, col, row, p, div, and span.

Examples

Drop rows of the table if an item name contains 'Falcon':

data

[
  { "name": "Falcon 9" },
  { "name": "Model S" },
  { "name": "Model 3" },
  { "name": "Falcon Heavy" }
]

template

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

result

PlanesModel S
Model 3

Delete the entire table if the array length is lower than 6:

data

[
  { "name": "Bob" }
]

template

Planes {d:len:ifLT(6):drop(table)}{d[i].name}
{d[i+1].name}

result

Drop an entire column if a field is empty:

data

{ "showDiscount": false, "items": [
  { "name": "Falcon 9",    "price": 1000, "discount": 100 },
  { "name": "Model S",     "price": 800,  "discount": 0   }
]}

template

ProductPriceDiscount{d.items[i].name}{d.items[i].price}{d.showDiscount:ifEQ(false):drop(col)} {d.items[i].discount}{d.items[i+1].name}{d.items[i+1].price}

result

ProductPriceFalcon 91000Model S800

Best practices:

Place the marker in any single row — Carbone detects the column and applies the condition to all rows automatically.
Only one drop(col) per column is allowed — do not repeat the marker in other rows of the same column.
Nested tables inside cells of the same row are not affected.

Limitations:

Merged cells are not supported (planned).

Tutorials

Get inspired by one of our real-life examples: EditorJS JSON output from HTML WYSIWYG Tool to PDF document