` that incorporates page numbering (current page and total pages) and dynamic copyright information fetched from the dataset.
```html
Page of
© {d.year} {d.company}. All rights reserved.
```
--------------------------------
### Static Translation Example (fr-fr)
Source: https://carbone.io/documentation/design/advanced-features/translations-i18n
This example demonstrates how to use the `{t()}` tag for static text translation in a Carbone template. The `lang` option specifies the target language ('fr-fr'), and the `translations` object provides the localization dictionary for that language. The template uses `{t(meeting)}` and `{t(apples)}` for direct translations and a conditional translation for `{d.id}`.
```json
"data" : {},
"convertTo" : "pdf",
"lang" : "fr-fr", // target lang of the report
"translations" : {
"fr-fr" : { // localization dictionary for fr-fr
"apples" : "Pommes",
"meeting" : "rendez-vous",
"monday" : "lundi",
"tuesday" : "mardi",
},
}
```
```template
{t(meeting)}{t(apples)}{d.id:ifEQ(2):show( {t(monday)} ):elseShow( {t(tuesday)} )}
```
```result
rendez-vouspommeslundi
```
--------------------------------
### Dynamic Translation Example
Source: https://carbone.io/documentation/design/advanced-features/translations-i18n
Illustrates the use of the `:t` formatter for dynamic text translation from JSON data, including the HTTP body with multiple language dictionaries.
```APIDOC
## Dynamic Translation
Use the `:t` formatter to translate Carbone tags. Text passed to `:t` is replaced with translations from a localization dictionary based on the `lang` attribute.
### HTTP Body
```json
{
"data": {
"id": 2,
"tool": "key1",
"protection": "key2"
},
"convertTo": "pdf",
"lang": "en-us", // target lang of the report
"translations": {
"fr-fr": {
"key1": "Tournevis",
"key2": "Gants",
"key3": "Professionel",
"key4": "Particulier"
},
"en-us": {
"key1": "Screwdrivers",
"key2": "Gloves",
"key3": "Professional",
"key4": "Individual"
}
}
}
```
### Template
```
{d.tool:t}{d.protection:t}{d.id:ifEQ(2):show("key3"):elseShow("key4"):t}
```
### Result
```
ScrewdriversGlovesProfessional
```
```
--------------------------------
### Dynamic Translation Example (en-us)
Source: https://carbone.io/documentation/design/advanced-features/translations-i18n
This example showcases dynamic translation using the `:t` formatter for Carbone tags. The `lang` option is set to 'en-us', and the `translations` object includes dictionaries for both 'fr-fr' and 'en-us'. The template applies the `:t` formatter to dynamic data fields (`d.tool`, `d.protection`) and a conditional output (`key3`/`key4`).
```json
"data" : {
"id" : 2
"tool" : "key1",
"protection": "key2"
},
"convertTo" : "pdf",
"lang" : "en-us", // target lang of the report
"translations" : {
"fr-fr" : {
"key1" : "Tournevis",
"key2" : "Gants",
"key3" : "Professionel",
"key4" : "Particulier"
},
"en-us" : {
"key1" : "Screwdrivers",
"key2" : "Gloves",
"key3" : "Professional",
"key4" : "Individual"
}
}
```
```template
{d.tool:t}{d.protection:t}{d.id:ifEQ(2):show("key3"):elseShow("key4"):t}
```
```result
ScrewdriversGlovesProfessional
```
--------------------------------
### Dynamic Hyperlink with Default URL Fallback (Carbone Tag)
Source: https://carbone.io/documentation/design/advanced-features/hyperlinks
This example demonstrates how to dynamically insert a hyperlink using a Carbone tag and specifies a fallback URL using the :defaultURL formatter. If the primary URL fails validation, the fallback URL will be used. This is applicable to various document types supported by Carbone.
```Carbone Tag
{d.url:defaultURL('https://carbone.io')}
```
```Carbone Tag
{d.url:defaultURL(.urlOnError)}
```
--------------------------------
### Inject Data into ODT Chart using bindChart
Source: https://carbone.io/documentation/design/advanced-features/charts
This example demonstrates how to inject dynamic data into an ODT chart using the `bindChart` formatter within LibreOffice. It explains the process of binding variables to specific cells for chart data representation.
```text
In the first cell, the following expression is written: {d.cheeses[i].type} {bindChart(3)=d.cheeses[i].purchasedTonnes}. The cheese type is displayed using {d.cheeses[i].type}, and then bindChart is used to bind the variable d.cheeses[i].purchasedTonnes to the cell that initially contains the value 3. This means the purchasedTonnes value will be printed instead of 3.
In the first cell of the second row, the expression {d.cheeses[i+1].type} {bindChart(4)=d.cheeses[i+1].purchasedTonnes} is written. Here, bindChart will replace the value 4 with the d.cheeses[i+1].purchasedTonnes variable.
```
--------------------------------
### HTML Anchor Tag with Default URL Fallback (Carbone Tag)
Source: https://carbone.io/documentation/design/advanced-features/hyperlinks
This example shows how to format content for an HTML anchor tag using the :html formatter and a :defaultURL formatter for fallback. The :defaultURL formatter should precede the :html formatter to ensure invalid URLs are replaced with a valid alternative before HTML rendering.
```Carbone Tag
{d.content:defaultURL(.urlOnError):html}
```
--------------------------------
### Conditionally Color Text with :color() and :ifEQ()
Source: https://carbone.io/documentation/design/advanced-features/colors
This example shows how to conditionally apply text color based on a data value. It uses the :ifEQ() formatter to check a condition and then applies a color (either success or error) using the :color(p) formatter. This is useful for highlighting status or results.
```json
{
"test" : "OK",
"testError" : "ERROR",
"success" : "#007700",
"error" : "#FF0000"
}
```
```carbone
The assessment passed
{d.test:ifEQ(OK):show(.success):elseShow(.error):color(p)}Error color
{d.testError:ifEQ(OK):show(.success):elseShow(.error):color(p)}
```
--------------------------------
### Configure PDF Options using HTML Element
Source: https://carbone.io/documentation/design/template-formats/html
Demonstrates how to customize PDF generation settings directly within the HTML template using the `` element. This example sets paper size to A3, landscape orientation, a bottom margin, and disables background printing.
```html
```
--------------------------------
### Carbone.io Signature Tag Usage Example
Source: https://carbone.io/documentation/design/advanced-features/signatures
Demonstrates how to use the ':sign' tag in a Carbone template with corresponding JSON data for generating documents with electronic signature fields. The output shows the expected API response containing signature positions.
```json
{
"signatureBuyer" : {
"type": "signature",
"name": "John Doe",
"email": "john@mail.fr"
},
"signatureSellerDate" : {
"type": "date",
"name": "James Setton",
"email": "james@mail.fr"
},
"signatureSeller" : {
"type": "signature",
"name": "James Setton",
"email": "james@mail.fr"
}
}
```
```plaintext
{d.signatureBuyer:sign} {d.signatureSellerDate:sign} {d.signatureSeller:sign}
```
```json
{
"success": true,
"data": {
"renderId": "xxxxx.pdf",
"signatures": [
{
"data": {
"type": "signature",
"name": "John Doe",
"email": "john@mail.fr"
},
"page": 1,
"x": 108,
"y": 95
},
{
"data": {
"type": "date",
"name": "James Setton",
"email": "james@mail.fr"
},
"page": 1,
"x": 108,
"y": 167
},
{
"data": {
"type": "signature",
"name": "James Setton",
"email": "james@mail.fr"
},
"page": 1,
"x": 108,
"y": 191
}
]
}
}
```
--------------------------------
### Table Row Colorization with Loop and Color Formatter
Source: https://carbone.io/documentation/design/advanced-features/colors
Illustrates how to colorize each row in a table using a loop and the :color formatter. This allows dynamic coloring of table rows based on data, supporting both named colors and RGB objects. The example shows how to apply specific colors to rows and how to use color values from the data.
```json
{
"user": [
{
"firstname": "Jean",
"lastname": "Dujardin",
"color": { "r": 255, "g": 0, "b": 0 }
},
{
"firstname": "Omar",
"lastname": "Sy",
"color": { "r": 0, "g": 255, "b": 0 }
}
]
}
```
```template
The first line get the `#0000FF` color and the second line get the `#00FFFF` color. Each line get the color corresponding to the color key in each user object.
```
--------------------------------
### Carbone Formatter Argument Example
Source: https://carbone.io/documentation/design/overview/design-best-practices
Demonstrates the correct usage of single quotes for delimiting text within Carbone formatter arguments. It highlights that only single quotes are recognized, and other quote types like double quotes or smart quotes will not be processed.
```plaintext
{d.value:ifEQ(true):show('This is true!')}
```
--------------------------------
### Apply Text Color Dynamically with :color()
Source: https://carbone.io/documentation/design/advanced-features/colors
This example demonstrates how to change the text color of a paragraph using the :color(p) formatter. It takes a hex color value from the data and applies it to the specified text. Ensure the color is in a valid 6-digit hex format.
```json
{
"flowerColor": "#FF0000"
}
```
```carbone
Color of roses {d.flowerColor:color(p)}This paragraph is not colored.
```
--------------------------------
### Color Formats for {bindColor} in Carbone
Source: https://carbone.io/documentation/design/advanced-features/colors
This section details the various color formats supported by Carbone's `{bindColor}` tag and the recommended `:color` formatter. It includes HEXA (with and without '#'), named colors, RGB, and HSL formats, providing examples for each.
```json
{
"color": "#FF0000" // HEXA with hashtag
}
{
"color": "FF0000" // HEXA without hashtag
}
{
"color": "red" // Named color
}
{
"color": {
"r": 255, // RGB format
"g": 0,
"b": 0
}
}
{
"color": {
"h": 300, // HSL format
"s": 50,
"l": 50
}
}
```
--------------------------------
### Enabling Table Support with Pre-release Feature Tag
Source: https://carbone.io/documentation/design/advanced-features/html
Shows how to enable beta support for HTML tables in Carbone.io version 5.0.9 and above using the pre-release feature tag. Without this tag, table content is rendered as a single paragraph.
```template
{o.preReleaseFeatureIn=5000009}
```
--------------------------------
### HTTP API Localization Dictionary Example
Source: https://carbone.io/documentation/design/advanced-features/translations-i18n
This example illustrates how to provide a localization dictionary when using the Carbone HTTP API (Carbone Cloud and On-Premise EE). The `translations` object contains language-specific dictionaries, such as 'en-us' and 'en-gb', mapping keys to their translated values.
```json
"data" : {},
"convertTo" : "pdf",
"lang" : "en-us", // target lang of the report
"translations" : {
"en-us" : { // localization dictionary for en-us
"frites" : "French fries",
"Monsieur X" : "John Doe"
},
"en-gb" : { // localization dictionary for en-gn
"frites": "chips"
}
}
```
--------------------------------
### Render HTML with Inline Styles using :html Formatter
Source: https://carbone.io/documentation/design/advanced-features/html
Demonstrates how to use the :html formatter to render HTML content with inline CSS styles for color and background-color. It supports Hexa, HSL, RGB, and named color formats. Unsupported tags and attributes are ignored.
```html
OK
```
--------------------------------
### Injecting HTML Content into a Template with :html Formatter
Source: https://carbone.io/documentation/design/advanced-features/html
Demonstrates injecting raw HTML content from a dataset into an HTML template using the :html formatter. This preserves all HTML formatting and styles, suitable for dynamic content injection.
```html
Customer Testimonials
{d.content:html}This is additional content around the injected HTML.
```
--------------------------------
### Font-Based Barcode Generation (Limited Support)
Source: https://carbone.io/documentation/design/advanced-features/barcode
Generate barcodes using specific installed fonts for limited barcode types (ean8, ean13, ean128, code39). This method requires font installation and is generally recommended to use the 'Barcodes as Image' solution instead.
```text
{ d.productValueEan13:barcode(ean13) }
```
```text
{ d.productValueEan8:barcode(ean8) }
```
```text
{ d.productValueCode39:barcode(code39) }
```
```text
{ d.productValueCode128:barcode(ean128) }
```
--------------------------------
### Using :color(part) Formatter for Text Sections
Source: https://carbone.io/documentation/design/advanced-features/colors
This example illustrates the use of the `:color(part)` formatter in Carbone to apply color to a specific section within a text. It requires manual steps in word processors like LibreOffice or MS Word to select the text, clear direct formatting, and then reapply styles to define the target section for coloring.
```template
// Example usage within a Carbone template:
// {d.someText:color(part=mySection, #FF0000)}
/* Instructions for LibreOffice/MS Word:
1. Place the tag with :color(part) next to the text.
2. Select the tags to be colored, including the :color(part) tag.
3. Click 'Clear Direct Formatting' on the Home tab.
4. Reapply desired font styles. */
```
--------------------------------
### Get Length (:len) - JavaScript
Source: https://carbone.io/documentation/design/formatters/text
Returns the number of elements in a string or an array. Works for both strings and arrays.
```javascript
'Hello World':len() // 11
'':len() // 0
[1,2,3,4,5]:len() // 5
[1,'Hello']:len() // 2
```
--------------------------------
### Get Absolute Value with :abs in Carbone.io
Source: https://carbone.io/documentation/design/formatters/number
Returns the absolute value of a number. It can process both positive and negative numbers, including those provided as strings. Marked as NEW in v4.12.0+.
```javascript
-10:abs() // 10
-10.54:abs() // 10.54
10.54:abs() // 10.54
'-200':abs() // 200
```
--------------------------------
### Conditionally Drop an HTML Table Row
Source: https://carbone.io/documentation/design/template-formats/html
Demonstrates how to conditionally remove a specific row from an HTML table using the ':drop(row)' formatter. This example shows dropping a row if the 'name' property contains 'Falcon'.
```html
| {d[i].name}{d[i].name:ifIN('Falcon'):drop(row)} |
| {d[i+1].name} |
```
--------------------------------
### Removing Last Page Break in Carbone Loop
Source: https://carbone.io/documentation/design/overview/design-best-practices
Provides Carbone code examples for removing the last page break within a loop. It shows both a standard and a shorter version of the syntax to achieve this.
```plaintext
{d.list[i]..list:len():sub(1):ifEQ(.i):drop(p)}
```
```plaintext
{d.list[i, i=-1]:ifNEM:drop(p)}
```
--------------------------------
### Variable-Based Array Filtering in Carbone (v4.2.0+)
Source: https://carbone.io/documentation/design/substitutions/array-search
Filter array elements dynamically by referencing variables from the JSON data. If the second operand of a filter starts with a period, Carbone treats it as a variable path.
```json
{
"parent" : {
"qty" : 2
},
"subArray" : [{
"text" : 1000,
"other" : 1,
"sub" : {
"b" : { "c" : 1 }
}
},{
"text" : 2000,
"other" : 1,
"sub" : {
"b" : { "c" : 2 }
}
}]
}
```
```carbone
{d.subArray[sub.b.c = .other].text}{d.subArray[sub.b.c = ..parent.qty].text}
```
--------------------------------
### Conditionally Show Sections with :showBegin/:showEnd in HTML
Source: https://carbone.io/documentation/design/template-formats/html
Illustrates the use of ':showBegin' and ':showEnd' formatters to conditionally display HTML sections based on a boolean data field. This is effective for showing or hiding details, tables, or other content blocks. It requires JSON data and an HTML template.
```json
{
"showDetails": false,
"product": "Carbone Pro"
}
```
```html
Product: {d.product}
{d.showDetails:ifEQ(true):showBegin}
Details:
{d.showDetails:ifEQ(true):showEnd}
Thank you for using Carbone!
```
```html
Product: Carbone Pro
Thank you for using Carbone!
```
--------------------------------
### Slice String - Carbone JS
Source: https://carbone.io/documentation/design/formatters/text
Extracts a portion of a string based on start and end indices. Supports an optional `wordMode` to prevent cutting words, ensuring lines do not exceed a specified width. Available from v4.18.0+.
```javascript
'foobar':substr(0, 3) // "foo"
'foobar':substr(1) // "oobar"
'foobar':substr(-2) // "ar"
'foobar':substr(2, -1) // "oba"
'abcd efg hijklm':substr(0, 11, true) // "abcd efg "
'abcd efg hijklm':substr(1, 11, true) // "abcd efg "
```
--------------------------------
### Prepend Text Using Constant Parameter in Carbone
Source: https://carbone.io/documentation/design/formatters/overview
Shows how to add a constant prefix to a data field using the `:prepend()` formatter. It also illustrates how to handle parameters containing commas or whitespace by enclosing them in single quotes.
```carbone
{your_field:prepend(myPrefix)}
{your_field:prepend('my prefix with space')}
```
--------------------------------
### Filter Array by String Equality (Carbone Template)
Source: https://carbone.io/documentation/design/repetitions/filtering
Filters an array to include only elements where the 'type' property is exactly 'rocket'. This method is effective for selecting items based on specific string values. The example illustrates this in a Carbone template.
```Carbone Template
People{d[i , type='rocket'].name}{d[i+1, type='rocket'].name}
```
--------------------------------
### Image Aspect Ratio Formatting with imageFit
Source: https://carbone.io/documentation/design/advanced-features/pictures
Demonstrates how to use the `imageFit` formatter to control how images are resized within their containers. Supported values are `fillWidth` (default), `contain`, and `fill`. This formatter is applied directly within the template tag.
```carbone
{d.image:imageFit(contain)}
// or
{d.image:imageFit(fill)}
// or
{d.image} // 'fillWidth' is set by default
```
--------------------------------
### Ascending Sort by Power and Index in Carbone Template
Source: https://carbone.io/documentation/design/repetitions/sorting
Sorts an array of car objects first by 'power' in ascending order, and then by array index 'i' for ties. This example demonstrates using object attributes for sorting within the Carbone template language.
```json
{
"cars" : [
{ "brand" : "Ferrari" , "power" : 3 },
{ "brand" : "Peugeot" , "power" : 1 },
{ "brand" : "BMW" , "power" : 2 },
{ "brand" : "Lexus" , "power" : 1 }
]
}
```
```carbone
Cars{d.cars[power , i].brand}{d.cars[power+1, i+1].brand}
```
--------------------------------
### Chained :set operations for sequential data transformation
Source: https://carbone.io/documentation/design/computation/store-and-transform
This example illustrates the sequential execution of the :set formatter for transforming data. First, 10 is added to the `d.price` and stored in `d.total1`. Then, 20 is added to `d.total1` and stored in `d.total2`. This showcases how new variables can depend on previously created ones within the same document section.
```json
{
"price" : 1
}
```
```carbone
{d.price:add(10):set(d.total1)}
{d.total1:add(20):set(d.total2)}
Result: {d.total2}
```
```plaintext
Result: 31
```
--------------------------------
### Convert HTML to PDF using Carbone API (curl)
Source: https://carbone.io/documentation/design/template-formats/html
Shows how to convert an HTML template to a PDF using a `POST` request to the Carbone API. It includes essential parameters like the Base64 encoded template, data, conversion type, and converter choice. Requires an API key for authentication.
```bash
curl -X POST https://api.carbone.io/render/template?download=true \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-H "carbone-version: 5" \
-d '{
"template": "YOUR_HTML_TEMPLATE_AS_BASE64_STRING",
"data": {
"name": "John Doe"
},
"convertTo": "pdf",
"converter": "C"
}'
```
--------------------------------
### Show Content Conditionally with :showBegin/:showEnd
Source: https://carbone.io/documentation/design/conditions/conditional-blocks
This snippet demonstrates how to use the :showBegin and :showEnd tags to conditionally display a block of text. The content between these tags is shown only if the specified condition evaluates to true. It's recommended to use line breaks within these tags and consider the drop/keep formatter for complex elements.
```Carbone Template
Banana{d.toBuy:ifEQ(true):showBegin}ApplePineapple{d.toBuy:showEnd}Grapes
```
--------------------------------
### Dynamic Checkboxes using Emojis/Unicode
Source: https://carbone.io/documentation/design/advanced-features/forms
Provides examples of creating dynamic checkboxes using emojis or Unicode characters. The expression checks a boolean value and displays a corresponding checked or unchecked symbol. This method works in any document format supported by Carbone.
```carbone
{d.value:ifEQ(true):show(✅):elseShow(⬜️)} // Emojies
{d.value:ifEQ(true):show(☑):elseShow(☐)} // Unicode Characters 1
{d.value:ifEQ(true):show(☒):elseShow(☐)} // Unicode Characters 2
```
--------------------------------
### HTML Formatting with Carbone.io (New Paragraph)
Source: https://carbone.io/documentation/design/advanced-features/html
Illustrates how the `:html` formatter in Carbone.io can create new paragraphs. When an HTML block element like `` is encountered, it forces a new paragraph in the output, separating content.
```json
{
"name" : 'Banana',
"description" : '
is an elongated, edible fruit
'
}
```
```template
The famous fruit {d.name} {d.description:html}, botanically a berry.
```
--------------------------------
### Count Array Rows - Carbone JS
Source: https://carbone.io/documentation/design/formatters/array
The count function generates a row number for each item in an array, starting from a specified number (defaulting to 1). This is useful for sequential numbering in reports. Note: This function is superseded by cumCount in v4.0.0+.
```javascript
d[i].id:count()
d[i].id:count(5)
```
--------------------------------
### Basic HTML Template Substitution with Carbone
Source: https://carbone.io/documentation/design/template-formats/html
Demonstrates how to use basic Carbone tags to substitute JSON data into an HTML template. This is useful for generating personalized documents like emails or reports. Ensure your JSON data structure matches the paths used in the template tags.
```json
{
"user": {
"firstName": "John",
"lastName": "Doe",
"email": "john.doe@carbone.io"
},
"membershipLevel": "Premium"
}
```
```html
Welcome Email
Welcome, **{d.user.firstName}** **{d.user.lastName}**!
Thank you for registering with us.
Your email address is: **{d.user.email}**
Your membership level: **{d.membershipLevel}**
```
--------------------------------
### Perform Aggregation and Looping Simultaneously with Carbone.io
Source: https://carbone.io/documentation/design/computation/aggregation
Illustrates how to combine aggregation with looping to display cumulative sums using `:cumSum`. This allows tracking running totals as data is iterated.
```Carbone Template
BrandTotalCumulative{d[i].brand}{d[i].qty:aggSum}{d[i].qty:cumSum}{d[i+1].brand}
```