# Format content

By default, the displayed content of each cell will be the result of a simple formatting. The content can also be composed as the result of a concatenation of several chunks.

There are `formatter` functions to define how columns content will be display (e.g. to define the number of decimal). This is a column-wise operation.

User can also have more control over displayed content by using function `compose`. The function enable to define the elements composing the paragraph and their respective formats. It can also be used to mix text chunks and images.

## Simple functions for formatting content

Theses are high level functions that should satisfy most of the usual needs. They can be used to define the formatting of one or more columns and eventually on a subset of rows.

Each accept a `prefix` and `suffix` argument that can be used to add a currency symbol for example. Also they all have `na_str` argument (defaut to ""), the string to use when data are not available.

- `colformat_num()` with arguments `digits` and `big.mark`
- `colformat_int()` with arguments `big.mark`
- `colformat_char()`

    dat <- head(mtcars, n = 10)
    dat[3:7, 1] <- NA
    dat[, 2] <- dat[, 6] * 1000000

    ft <- flextable(dat)
    ft

mpg | cyl | disp | hp | drat | wt | qsec | vs | am | gear | carb
21.0 | 2620000 | 160.0 | 110 | 3.90 | 2.620 | 16.46 | 0 | 1 | 4 | 4
21.0 | 2875000 | 160.0 | 110 | 3.90 | 2.875 | 17.02 | 0 | 1 | 4 | 4
NA | 2320000 | 108.0 | 93 | 3.85 | 2.320 | 18.61 | 1 | 1 | 4 | 1
NA | 3215000 | 258.0 | 110 | 3.08 | 3.215 | 19.44 | 1 | 0 | 3 | 1
NA | 3440000 | 360.0 | 175 | 3.15 | 3.440 | 17.02 | 0 | 0 | 3 | 2
NA | 3460000 | 225.0 | 105 | 2.76 | 3.460 | 20.22 | 1 | 0 | 3 | 1
NA | 3570000 | 360.0 | 245 | 3.21 | 3.570 | 15.84 | 0 | 0 | 3 | 4
24.4 | 3190000 | 146.7 | 62 | 3.69 | 3.190 | 20.00 | 1 | 0 | 4 | 2
22.8 | 3150000 | 140.8 | 95 | 3.92 | 3.150 | 22.90 | 1 | 0 | 4 | 2
19.2 | 3440000 | 167.6 | 123 | 3.92 | 3.440 | 18.30 | 1 | 0 | 4 | 4

    num_keys <- c("mpg", "disp", "drat", "wt", "qsec")
    int_keys <- c("cyl", "hp", "vs", "am", "gear", "carb")

    ft <- colformat_num(x = ft, col_keys = num_keys, big.mark = ",", digits = 2, na_str = "missing")
    #> Warning in colformat_num.flextable(x = ft, col_keys = num_keys, big.mark =
    #> ",", : argument col_keys is deprecated in favor of argument j
    ft <- colformat_int(x = ft, col_keys = int_keys, big.mark = ",")
    #> Warning in colformat_int.flextable(x = ft, col_keys = int_keys, big.mark = ","):
    #> argument col_keys is deprecated in favor of argument j
    autofit(ft)

mpg | cyl | disp | hp | drat | wt | qsec | vs | am | gear | carb
21.00 | 2,620,000 | 160.00 | 110 | 3.90 | 2.62 | 16.46 | 0 | 1 | 4 | 4
21.00 | 2,875,000 | 160.00 | 110 | 3.90 | 2.88 | 17.02 | 0 | 1 | 4 | 4
missing | 2,320,000 | 108.00 | 93 | 3.85 | 2.32 | 18.61 | 1 | 1 | 4 | 1
missing | 3,215,000 | 258.00 | 110 | 3.08 | 3.21 | 19.44 | 1 | 0 | 3 | 1
missing | 3,440,000 | 360.00 | 175 | 3.15 | 3.44 | 17.02 | 0 | 0 | 3 | 2
missing | 3,460,000 | 225.00 | 105 | 2.76 | 3.46 | 20.22 | 1 | 0 | 3 | 1
missing | 3,570,000 | 360.00 | 245 | 3.21 | 3.57 | 15.84 | 0 | 0 | 3 | 4
24.40 | 3,190,000 | 146.70 | 62 | 3.69 | 3.19 | 20.00 | 1 | 0 | 4 | 2
22.80 | 3,150,000 | 140.80 | 95 | 3.92 | 3.15 | 22.90 | 1 | 0 | 4 | 2
19.20 | 3,440,000 | 167.60 | 123 | 3.92 | 3.44 | 18.30 | 1 | 0 | 4 | 4

> Their names is `col_format_*` as the first version was not working with rows subset. This limitation is no more true and the functions should then be named `format_int`, `format_num`… as they can operate on rows and columns.

## set_formatter function

It is possible to define the functions that will be used to format the data.frame values into strings. `set_formatter` set column formatter functions.

    ft <- flextable(head(mtcars, n = 10 ),
                       col_keys = c("gear", "mpg", "qsec"))
    ft <- set_formatter(ft,
        mpg = function(x) sprintf("%.04f", x),
        gear = function(x) sprintf("%.0f gears", x)
      )
    ft <- theme_booktabs(ft)
    ft <- autofit(ft)
    ft

gear | mpg | qsec
4 gears | 21.0000 | 16.46
4 gears | 21.0000 | 17.02
4 gears | 22.8000 | 18.61
3 gears | 21.4000 | 19.44
3 gears | 18.7000 | 17.02
3 gears | 18.1000 | 20.22
3 gears | 14.3000 | 15.84
4 gears | 24.4000 | 20.00
4 gears | 22.8000 | 22.90
4 gears | 19.2000 | 18.30

## compose function

### Usage

`flextable` content can be defined with function `compose`.

It lets user control the formated content at the cell level of the table. It is possible to define a content for a row subset and a column as well as on the whole column. One can mix images and text (but not with PowerPoint because PowerPoint can not do it).

Below the starting point of next illustrations:

    myft <- flextable( head(mtcars),
      col_keys = c("am", "separator", "gear", "mpg", "drat", "qsec" ))
    myft <- bold(myft, part = "header")
    myft <- border(myft, border = fp_border( width = 0),
      border.top = fp_border(), border.bottom = fp_border(),
      part = "all")
    myft <- align(myft, align = "right", part = "all" )
    myft <- border(myft, j = ~ separator, border = fp_border(width=0), part = "all")
    myft <- width(myft, j = ~ separator, width = .1)
    myft

am |  | gear | mpg | drat | qsec
1 |  | 4 | 21.0 | 3.90 | 16.46
1 |  | 4 | 21.0 | 3.90 | 17.02
1 |  | 4 | 22.8 | 3.85 | 18.61
0 |  | 3 | 21.4 | 3.08 | 19.44
0 |  | 3 | 18.7 | 3.15 | 17.02
0 |  | 3 | 18.1 | 2.76 | 20.22

The function requires a call to `as_paragraph` which will concatenate text or images chunks as a paragraph.

The following example shows how to control the format of displayed values and how to associate them with specific text formatting properties (bold red text):

    myft <- compose(
      myft, j = "mpg",
      value = as_paragraph(
        "mpg value is ",
        as_chunk(sprintf("%.01f", mpg), props = fp_text(color = "red", bold = TRUE) ) )
      )
    myft <- autofit(myft)
    myft

am |  | gear | mpg | drat | qsec
1 |  | 4 | mpg value is 21.0 | 3.90 | 16.46
1 |  | 4 | mpg value is 21.0 | 3.90 | 17.02
1 |  | 4 | mpg value is 22.8 | 3.85 | 18.61
0 |  | 3 | mpg value is 21.4 | 3.08 | 19.44
0 |  | 3 | mpg value is 18.7 | 3.15 | 17.02
0 |  | 3 | mpg value is 18.1 | 2.76 | 20.22

With that system, it’s easy to concatenate multiple values:

    myft <- compose(
      myft, j = "mpg",
      value = as_paragraph(
        "mpg value is ",
        as_chunk(sprintf("%.01f", mpg), props = fp_text(color = "red", bold = TRUE) ),
        " with ",
        as_chunk(sprintf("# %.0f", carb), props = fp_text(color = "gray", italic = TRUE) )
        )
      )

    myft <- autofit(myft)
    myft

am |  | gear | mpg | drat | qsec
1 |  | 4 | mpg value is 21.0 with # 4 | 3.90 | 16.46
1 |  | 4 | mpg value is 21.0 with # 4 | 3.90 | 17.02
1 |  | 4 | mpg value is 22.8 with # 1 | 3.85 | 18.61
0 |  | 3 | mpg value is 21.4 with # 1 | 3.08 | 19.44
0 |  | 3 | mpg value is 18.7 with # 2 | 3.15 | 17.02
0 |  | 3 | mpg value is 18.1 with # 1 | 2.76 | 20.22

Or to define specific title headers:

    myft <- compose(
      myft, j = "mpg", part = "header",
      value = as_paragraph(
        "Miles/(US) gallon ",
        as_chunk("* with num of carb.", props = fp_text(color = "gray", vertical.align = "superscript") )
        )
      )

    myft <- autofit(myft)
    myft

am |  | gear | Miles/(US) gallon * with num of carb. | drat | qsec
1 |  | 4 | mpg value is 21.0 with # 4 | 3.90 | 16.46
1 |  | 4 | mpg value is 21.0 with # 4 | 3.90 | 17.02
1 |  | 4 | mpg value is 22.8 with # 1 | 3.85 | 18.61
0 |  | 3 | mpg value is 21.4 with # 1 | 3.08 | 19.44
0 |  | 3 | mpg value is 18.7 with # 2 | 3.15 | 17.02
0 |  | 3 | mpg value is 18.1 with # 1 | 2.76 | 20.22

Note that `compose` is not appending but is replacing the content.

### Limitation for PowerPoint

Using images in flextable is not supported when output format is PowerPoint. This is not a choice nor a unimplemented feature. This is because PowerPoint is not able to embed images in a table cell. That’s a PowerPoint limitation.

If beeing able to display images in PowerPoint table is important to you, you can use the `plot` function or the `save_as_image` and embed the result in the PowerPoint. You will of course loose ability to edit the table in PowerPoint.

### Images

Function `compose` supports images insertion. Use function `as_image` in `as_paragraph` call:

    img.file <- file.path( R.home("doc"), "html", "logo.jpg" )

    myft <- compose( myft, i = ~ qsec > 18, j = "qsec",
      value = as_paragraph(as_image( src = img.file, width = .20, height = .15))
    )
    myft <- autofit(myft)
    myft

am |  | gear | Miles/(US) gallon * with num of carb. | drat | qsec
1 |  | 4 | mpg value is 21.0 with # 4 | 3.90 | 16.46
1 |  | 4 | mpg value is 21.0 with # 4 | 3.90 | 17.02
1 |  | 4 | mpg value is 22.8 with # 1 | 3.85 |
0 |  | 3 | mpg value is 21.4 with # 1 | 3.08 |
0 |  | 3 | mpg value is 18.7 with # 2 | 3.15 | 17.02
0 |  | 3 | mpg value is 18.1 with # 1 | 2.76 |

Note this chunk option requires package officedown in a R Markdown context with Word output format.

### minibar

Function `compose` supports mini barplots insertion. Use function `minibar` in `as_paragraph` call:

    myft <- flextable( head(iris, n = 10 ))

    myft <- compose( myft, j = 1,
      value = as_paragraph(
        minibar(value = Sepal.Length, max = max(Sepal.Length))
      ),
      part = "body")

    autofit(myft)

Sepal.Length | Sepal.Width | Petal.Length | Petal.Width | Species
| 3.5 | 1.4 | 0.2 | setosa
| 3.0 | 1.4 | 0.2 | setosa
| 3.2 | 1.3 | 0.2 | setosa
| 3.1 | 1.5 | 0.2 | setosa
| 3.6 | 1.4 | 0.2 | setosa
| 3.9 | 1.7 | 0.4 | setosa
| 3.4 | 1.4 | 0.3 | setosa
| 3.4 | 1.5 | 0.2 | setosa
| 2.9 | 1.4 | 0.2 | setosa
| 3.1 | 1.5 | 0.1 | setosa

Note this chunk option requires package officedown in a R Markdown context with Word output format.

### linerange

Function `compose` supports mini linerange insertion. Use function `linerange` in `as_paragraph` call:

    myft <- flextable( head(iris, n = 10 ))

    myft <- compose( myft, j = 1,
      value = as_paragraph(
        linerange(value = Sepal.Length, max = max(Sepal.Length))
      ),
      part = "body")

    autofit(myft)

Sepal.Length | Sepal.Width | Petal.Length | Petal.Width | Species
| 3.5 | 1.4 | 0.2 | setosa
| 3.0 | 1.4 | 0.2 | setosa
| 3.2 | 1.3 | 0.2 | setosa
| 3.1 | 1.5 | 0.2 | setosa
| 3.6 | 1.4 | 0.2 | setosa
| 3.9 | 1.7 | 0.4 | setosa
| 3.4 | 1.4 | 0.3 | setosa
| 3.4 | 1.5 | 0.2 | setosa
| 2.9 | 1.4 | 0.2 | setosa
| 3.1 | 1.5 | 0.1 | setosa

Note this chunk option requires package officedown in a R Markdown context with Word output format.

### Sugar functions for complex formatting

Functions `as_b`, `as_i`, `as_sub`, `as_sup` are special functions that can be used together. They set a value as bold, italic, subscripted or superscripted. This is particularly useful when the headers need complex formatting.

    data <- structure(list(Species = structure(1:3, .Label = c("setosa",
    "versicolor", "virginica"), class = "factor"), col1 = c(5.006,
    5.936, 6.588)), class = "data.frame", row.names = c(NA, -3L))

    ft <- flextable(data)
    ft

Species | col1
setosa | 5.006
versicolor | 5.936
virginica | 6.588

    ft <- compose(ft, part = "header", j = "Species",
        value = as_paragraph(as_i(as_b("Species"))))
    ft <- compose(ft, part = "header", j = "col1",
        value = as_paragraph(as_b("µ"), as_sup("blah")))
    ft

Species | µ blah
setosa | 5.006
versicolor | 5.936
virginica | 6.588

## Captions

Captions are supported for HTML and Word output (also from a bookdown project with its specificities taken into account).

Capacities are different from one format to another. For the Word part, we can produce real auto-numbered captions with a bookmark on the automatic number which can then be used as a reference, i.e. for cross-referencing. For the HTML part, you can produce real captions but without the auto-numbering.

Of course, in a bookdown, we benefit from the cross reference capabilities.

The recommended method to set a caption is via the function `set_caption`. If this function is used, the caption will be defined from here.

Two other methods are available for `knitr` and are presented below in order of triggering:

1. with knitr’s chunk options:

   - `tab.cap.style`: Word style name to use for table captions.
   - `tab.cap.pre`: Prefix for Word numbering chunk (default to “Table”).
   - `tab.cap.sep`: Suffix for Word numbering chunk (default to “:”).
   - `tab.cap`: Caption label.
   - `tab.id`: Caption Word bookmark (unique identifier).

2. with knitr chunk and bookdown options (if you’re in a bookdown):

   - `tab.cap.style`: Word style name to use for table captions.
   - `tab.cap.pre`: Prefix for Word numbering chunk (default to “Table”).
   - `tab.cap.sep`: Suffix for Word numbering chunk (default to “:”).
   - `tab.cap`: Caption label.
   - `label`: Caption reference unique identifier.

(This css instructions is only there to make the caption styled:)

    caption {
      color:red;
      line-height: 1.5em;
      font-size: 10px;
    }

    ft <- set_caption(ft, caption = "this is a caption")
    ft

this is a caption
Species | µ blah
setosa | 5.006
versicolor | 5.936
virginica | 6.588

You can have a look at R Markdown document illustrating captions for different supported format here:

    system.file(package = "flextable", "examples", "rmd", "captions")

Copy one of these files in your working directory and run knitr:

- captions_html_document2.Rmd
- captions_rdocx_document.Rmd
- captions_word_document.Rmd
- captions_word_document2.Rmd

## footnotes

Adding footnotes is possible by using function `compose` but it requires a two step approach (add the reference symbol and add the corresponding footnote in the footer part).

To make the process simpler, use function `footnote` that will ease the addition of footnotes.

    ft <- flextable(head(iris))
    ft <- footnote( ft, i = 1, j = 1:3,
                value = as_paragraph(
                  c("This is footnote one",
                    "This is footnote two",
                    "This is footnote three")
                ),
                ref_symbols = c("a", "b", "c"),
                part = "header")
    ft <- valign(ft, valign = "bottom", part = "header")
    autofit(ft)

Sepal.Length a | Sepal.Width b | Petal.Length c | Petal.Width | Species
5.1 | 3.5 | 1.4 | 0.2 | setosa
4.9 | 3.0 | 1.4 | 0.2 | setosa
4.7 | 3.2 | 1.3 | 0.2 | setosa
4.6 | 3.1 | 1.5 | 0.2 | setosa
5.0 | 3.6 | 1.4 | 0.2 | setosa
5.4 | 3.9 | 1.7 | 0.4 | setosa
a This is footnote one
b This is footnote two
c This is footnote three

You can also add footnotes inline using the `inline` argument and specify a seperator string with `sep` (default “;”)

    ft <- flextable(head(iris))
    ft <- autofit(ft)
    ft <- footnote( ft, i = 1, j = 1:2,
                    value = as_paragraph(
                      c("This is footnote one",
                        "This is footnote two")
                    ),
                    ref_symbols = c("a", "b"),
                    part = "header",inline=T)
    ft <- footnote( ft, i = 1, j = 3:4,
                    value = as_paragraph(
                      c("This is footnote three",
                        "This is footnote four")
                    ),
                    ref_symbols = c( "c","d"),
                    part = "header",inline=T)
    ft

Sepal.Length a | Sepal.Width b | Petal.Length c | Petal.Width d | Species
5.1 | 3.5 | 1.4 | 0.2 | setosa
4.9 | 3.0 | 1.4 | 0.2 | setosa
4.7 | 3.2 | 1.3 | 0.2 | setosa
4.6 | 3.1 | 1.5 | 0.2 | setosa
5.0 | 3.6 | 1.4 | 0.2 | setosa
5.4 | 3.9 | 1.7 | 0.4 | setosa
a This is footnote one; b This is footnote two; c This is footnote three; d This is footnote four

## Two lines in a cell

> A cell is made of one single paragraph of text. Paragraphs can contain several chunks of text with different formatting but also images. (see keypoints)

When designed, flextable was not supposed to support soft return (a new line in a paragraph). As requested by some users, some workarounds have been implemented to let add some `\n` as soft break in paragraphs.

With HTML, it works fine. But with Word or PowerPoint it comes with limitations/issues (we are working on it):

- With PowerPoint the padding is also applied where the soft break is written.
- With Word, the text format is lost and the default style is used.