Colors

:color(scope, type)

v4.17.0+

Apply the color on the text, paragraph, table row or table cell

Params	Description	Type
scope	Specifies the element to be color-changed - p : the current paragraph where the tag is (by default) - cell : the current cell of a table - row : the current row of a table - shape : the current shape - part : for text section (the color is applied within the same styled of the element)	String
type	Defines the property to be modified. - text for the text color (by default) - highlight to highlight the text - background for cells, rows and shapes - border for shapes only	String

Important Notes:

Compatible with PDF, ODT, ODP, DOCX, PPTX, HTML files.

• The color provided must be in 6-digit hex color notation, with or without a hashtag, and can be in lowercase or uppercase: #FF0000 or FF0000. Carbone replaces incorrect color values with light gray (#888888).
• The :color formatter manages priority between overlapping areas. A color applied to the current paragraph has a higher priority than a color applied to the current shape, cell, or row.
• For HTML, the color is applied using the style attribute only to the selected HTML tag (tr, td, p).
• For ODP (text, tables, and shapes) and ODT (shapes only), the :color formatter requires that a non-default style is already applied to the target element in the template (e.g., a custom text color).
• For PPTX, all combinations of type (background, text, border) and scope (row, cell, shape) are supported, except border which applies only to shapes. Available since v5.6.0.
• Complex nested tables with colors on sub-tables are not fully supported.
• highlight is not managed in DOCX templates.
• The :color formatter cannot be used in aliases and cannot be combined with aggregators.
• The :color(part) feature is currently available only for ODT templates.

Get inspired by one of our real-life examples: Invoice or Sensor Readings

Simple text color

The following example changes the text color to red:

Condition and color

The following example changes the text color based on a condition.

Details:

• If the test value is equal to "OK," the text color will be d.success (color "#007700").
• If the test value is not equal to "OK," the text color will be d.error (color "#FF0000").
• The :color(p) formatter applies the color to the text in the current paragraph.

Loop and color

The example conditionally changes the text color of the current table row.

In the following example, the Carbone tag {d.tests[i].result:ifEQ(ok):show(#007700):elseShow(d.error):color(row, text)} is used in the template:

• If the result value is equal to "ok," the text color will change to green (#007700). The argument passed is a string, not a value sourced from the JSON.
• If the result value is not equal to "ok," the color will be d.error.
• The :color(row, text) formatter changes the text color in the current row.

Combined colors

The example conditionally changes the background color and text color of the table row.

Two tags are used in the following template:

• {d.tests[i].result:ifEQ(ok):show(#000000):elseShow(#FFFFFF):color(row, text)}: If result is equal to ok, the text color of the current row is changed to black (#000000); otherwise, it changes to white (#FFFFFF).
• {d.tests[i].result:ifEQ(ok):show(#FFFFFF):elseShow(d.error):color(row, background)}: If result is equal to ok, the row keeps a white background (#FFFFFF); otherwise, it takes the red color sourced from the JSON (d.error).

Color Text Section

Compatible with PDF and ODT files for the moment.

The :color formatter includes a part argument, which allows you to apply color to a specific section within a paragraph. This feature is particularly useful when you need to highlight certain parts of your text without affecting the entire paragraph.

To correctly use the :color(part) formatter, follow these steps:

1. Tag Placement: Place the tag with the :color(part) formatter right next to the text you want to color.
2. Selecting Tags: In LibreOffice or MS Word, select the tags you want to color, including the tag containing the :color(part) formatter.
3. Clear Style : Click on the "Clear Direct Formatting" icon located in the "Home" tab. This will define the section to be colored for the :color(part) formatter.
4. Reapply Font Style: If you had a specific font style, reapply it after clearing the direct formatting.

Color replacement {bindColor}

We recommend the :color formatter instead of {bindColor}: it is simpler and less error-prone. {bindColor} is the former way to manage colors in Carbone.

Compatible with PDF, ODT, ODP, DOCX, and ODS files.

The {bindColor} tag replaces a color of the template with a color from the data:

{bindColor(myColorToBind, myFormat) = d.myVar}

• myColorToBind: the reference color, a hexadecimal color applied in the template. It is case-insensitive, and the leading # is optional. Carbone replaces this color on every element that uses it, so pick a color that appears nowhere else in the template. Text highlights in Microsoft Word are an exception.
• myFormat: the format of the new color in the data.
• d.myVar: the new color.

Write the tag anywhere in the document: at the end, in the header or footer, or below the [i+1] row of a loop, even if d.myVar belongs to the loop. Carbone removes the tag from the report. You can bind each reference color only once.

Supported elements:

• Text colors, text backgrounds and table cell backgrounds.
• DOCX only: shape backgrounds and line colors. Write the tag in the document body, not in the alternative text of the shape, and give the shape an RGB color in the template, not a theme color.

Simple example with {bindColor}

In this project status, the status badge uses two reference colors: #3C4257 for the text and #E3E8EE for the background. The priority uses #8792A2. The three tags at the end of the template replace them with the colors from the data.

Color formats for {bindColor}

Format	Value of d.myVar
#hexa	"#FF0000"
hexa	"FF0000"
color	"red", one of the color names below
rgb	{ "r": 255, "g": 0, "b": 0 }, each value from 0 to 255
hsl	{ "h": 0, "s": 100, "l": 50 }, h from 0 to 360, s and l from 0 to 100, or all three from 0 to 1

The color format accepts 17 names:

yellow    | green     | cyan      | magenta     | blue     | red
darkBlue  | darkCyan  | darkGreen | darkMagenta | darkRed  | darkYellow
darkGray  | lightGray | black     | white       | transparent

Microsoft Word exception for {bindColor}

In Microsoft Word, a text highlight accepts only a color name. Apply a highlight color in the template, then use its name as the reference color with the color format, for example {bindColor(lightGray, color) = d.highlight}. All the names above work except transparent.

Text colors, cell backgrounds and text shading (Borders and Shading > Shading) accept hexadecimal colors, like the status badge in this contract review.

Loop with {bindColor}

Apply the reference color to the cells of the repeated row, then bind it to the color of the current item, here {bindColor(e3e8ee, #hexa) = d.accounts[i].color}. Each row gets its own color. You can write the tag below the loop.