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	Sefines the property to be modified and supports - 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, 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).
• 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.

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(#000000):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 black (#000000). 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 replacement {bindColor}

We recommend using :color formatter instead of {bindColor} because it is much simpler to use and less error-prone. {bindColor} was the old method in Carbone for managing color.

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

The special bindColor tag allows you to replace a color reference in the template with a new color from your JSON dataset. Usage:

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

• myColorToBind: A temporary hexadecimal color applied to text, background, or a cell background. It is used by Carbone to identify the color to replace. The hexadecimal value is case-insensitive, and the hashtag at the beginning is optional. Note an exception regarding dynamic background colors on MS Word DOCX documents.
• myFormat: The format of the new color expected from the d.myVar tag. Here is a list of available color formats.
• d.myVar: The tag that corresponds to the new color.

Unlike regular tags, {bindColor()} can be placed anywhere in the document, such as the header, footer, or below a repetition [i+1], even if the myVar argument is part of a repetition.

For more details, refer to the example below.

Important Notes:

Supported on:

• Text and background colors
• Table cell backgrounds
• Shape backgrounds and line colors for DOCX only. Write the bindColor tag in the document body, not in the alternative text of shapes. The replaced color format must be RGB only.

Simple example with {bindColor}

We recommend using :color formatter instead

Data

{
  "color": "#FF0000", // red
  "color2": "#00FF00", // green
  "color3": "#0000FF" // blue
}

Template

Details:

• Manage get the #00FFFF reference color and will be replaced by #FF0000 coming from the {d.color} tag.
• dynamic get the #FF00FF reference color and will be replaced by #00FF00 coming from the {d.color2} tag.
• color get in background the reference color #0000FF and will be replaced by #00FF00 coming from the {d.color3} tag.

Result

Color formats for {bindColor}

We recommend using :color formatter instead

There are 5 color formats:

• #hexa:

  {
    "color": "#FF0000"
  }

• hexa:

  {
    "color": "FF0000"
  }

• color:

  {
    "color": "red"
  }

• rgb:

  {
    "color": {
      "r": 255, // Between 0 and 255
      "g": 0, // Between 0 and 255
      "b": 0 // Between 0 and 255
    }
  }

• hsl:

  {
    "color": {
      "h": 300, // Between 0 and 360
      "s": 50, // Between 0 and 100 or 0 and 1
      "l": 50 // Between 0 and 100 or 0 and 1
    }
  }

Microsoft Word exception for {bindColor}

We recommend using :color formatter instead

In Microsoft Word, only a color name can be used to replace the background color of a text.
17 colors are available, which are:

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

You can still use hexadecimal colors for the text and cells backgrounds on Microsoft Word.

Data

{
  "color": "darkYellow",
  "color2": "green",
  "color3": "11BBCC"
}

Template

Microsoft get in background the red color, Word get in background the magenta color and background get the #FFFF00 color

Result

Loop with {bindColor}

We recommend using :color formatter instead

Each line in a table can be colorized by one color:

Data

{
  "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.

Result