# flextable overview

## Introduction

`flextable` can easily create reporting table from `data.frame`. You can merge cells, add header rows, add footer rows, change any format and specify how data should be displayed in cells. `flextable` objects can be rendered in HTML format but also in Microsoft Word and PowerPoint documents.

### flextable creation

Two main functions are provided: `flextable` and `regulartable`.

`flextable` function is producing flexible tables where each cell can contain several chunks of text with their own set of formatting properties (bold, font color, etc.). Function `display` lets customise text of cells (See display function).

`regulartable` function has been written because the first one is ressource consumming. The main difference is that it is producing tables where cells can contain only one chunk of text with its own set of formatting properties. Note that `regulartable` and `flextable` functions are both returning an object of class `flextable`.

Note also that `regulartable` supports strange variable names (with percent symbols, with spaces, etc.) and `flextable` does not support them.*

> The following table is made with `regulartable` and dataset data:

    data <- iris[c(1:3, 51:53, 101:104),]

Species |  | Sepal |  | Petal
| Length | Width |  | Length | Width
setosa |  | 5.100 | 3.500 |  | 1.400 | 0.200
| 4.900 | 3.000 |  | 1.400 | 0.200
| 4.700 | 3.200 |  | 1.300 | 0.200
versicolor |  | 7.000 | 3.200 |  | 4.700 | 1.400
| 6.400 | 3.200 |  | 4.500 | 1.500
| 6.900 | 3.100 |  | 4.900 | 1.500
virginica |  | 6.300 | 3.300 |  | 6.000 | 2.500
| 5.800 | 2.700 |  | 5.100 | 1.900
| 7.100 | 3.000 |  | 5.900 | 2.100
| 6.300 | 2.900 |  | 5.600 | 1.800

### flextable keypoints

A flextable is an object that will produce a reporting table from a `data.frame` object. Any formatting property related to text, paragraphs, cells in the table can be modified. Content can also be customized.

Columns to display are by default all columns of the data.frame but can be choosen from a subset of existing columns and also unexisting columns.

Unexisting columns are containing blanks by default but this content can be customized.

A flextable is containing three parts, one for header rows,
one for body rows and one for footer rows. By default, there is only one header row containing the names of the data.frame. The body part is containing data from the data.frame. The footer part is never implemented when creating the `flextable`.

header part |  | row 1 - cell from 1 to 5
| row 2 - cell from 1 to 2 | row 2 cell from 3 to 5
| row 3 cell 1 | row 3 cell 2 | row 3 cell 3 | row 3 cell 4 | row 3 cell 5
body part |  | data[1,1] | data[1,2] | data[1,3] | data[1,4] | data[1,5]
| data[2,1] | data[2,2] | data[2,3] | data[2,4] | data[2,5]
| ... | ... | ... | ... | ...
| data[n,1] | data[n,2] | data[n,3] | data[n,4] | data[n,5]
footer part |  | Grouped footer 1.1 | Grouped footer 1.2
| Grouped footer 2.1

A cell is made of one single paragraph of text. When the flextable object is created by function `flextable()`, paragraphs can contain several chunks of text with different formatting. When the flextable object is created by function `regulartable()`, paragraphs can contain only one chunk of text with one single set of formatting properties.

The dimensions of the flextable elements, widths of columns and heights of rows, are always defined. Beeing able to define the exact size necessary to display data on a single line is a key concept. See functions `autofit()` and `dim_pretty()`.

## Getting started

Let’s have a step by step demo. First create a regulartable and change header font in bold.

    library(flextable)
    library(officer)

    myft <- regulartable(
      head(mtcars),
      col_keys = c("am", "carb", "gear", "mpg", "drat" ))
    myft

am | carb | gear | mpg | drat
1.000 | 4.000 | 4.000 | 21.000 | 3.900
1.000 | 4.000 | 4.000 | 21.000 | 3.900
1.000 | 1.000 | 4.000 | 22.800 | 3.850
0.000 | 1.000 | 3.000 | 21.400 | 3.080
0.000 | 2.000 | 3.000 | 18.700 | 3.150
0.000 | 1.000 | 3.000 | 18.100 | 2.760

flextable or regulartable function: `regulartable` and `flextable` create a flextable object based on input data. Optional argument `col_keys` is used to only display a subset of columns.

Functions `theme_` are sugar functions whose role is to apply a set of formatting instructions to a flextable. For example, `theme_vanilla` set specific borders, right align paragraphs and make headers bold.

    myft <- theme_vanilla(myft)
    myft

am | carb | gear | mpg | drat
1.000 | 4.000 | 4.000 | 21.000 | 3.900
1.000 | 4.000 | 4.000 | 21.000 | 3.900
1.000 | 1.000 | 4.000 | 22.800 | 3.850
0.000 | 1.000 | 3.000 | 21.400 | 3.080
0.000 | 2.000 | 3.000 | 18.700 | 3.150
0.000 | 1.000 | 3.000 | 18.100 | 2.760

### Layout

> To learn more, see article about layouts.

Table layout can be modified. One can add or change header/footer rows, change cells height and width and merge cells. Also, there is an important function named `autofit` (it adjusts widths and heights regarding to text widths and heights).

We will use `merge_v()` to merge identical consecutive cells of columns “carb” and “am”.

    myft <- merge_v(myft, j = c("am", "carb") )
    myft

am | carb | gear | mpg | drat
1.000 | 4.000 | 4.000 | 21.000 | 3.900
4.000 | 21.000 | 3.900
1.000 | 4.000 | 22.800 | 3.850
0.000 | 3.000 | 21.400 | 3.080
2.000 | 3.000 | 18.700 | 3.150
1.000 | 3.000 | 18.100 | 2.760

Cells can be merged with functions `merge_none()`, `merge_v()`, `merge_h()` and `merge_at()`.

`set_header_labels()` set labels:

    myft <- set_header_labels( myft, carb = "# carb." )
    myft <- width(myft, width = .75) # set width of all columns to .75 in
    myft

am | # carb. | gear | mpg | drat
1.000 | 4.000 | 4.000 | 21.000 | 3.900
4.000 | 21.000 | 3.900
1.000 | 4.000 | 22.800 | 3.850
0.000 | 3.000 | 21.400 | 3.080
2.000 | 3.000 | 18.700 | 3.150
1.000 | 3.000 | 18.100 | 2.760

Headers can be modified with functions `set_header_df()`, `set_header_labels()` and `add_header()`.

`autofit()` adjust widths and heights of cells. This should be the last operation as some operations make columns wider, e.g. changing font size, changing font weight. `autofit` makes sure that any content is displayed as a single line of text.

    myft <- autofit(myft)
    myft

am | # carb. | gear | mpg | drat
1.000 | 4.000 | 4.000 | 21.000 | 3.900
4.000 | 21.000 | 3.900
1.000 | 4.000 | 22.800 | 3.850
0.000 | 3.000 | 21.400 | 3.080
2.000 | 3.000 | 18.700 | 3.150
1.000 | 3.000 | 18.100 | 2.760

### Formating

> To learn more, see article about format.

Many sugar functions can be used to format flextables: `bg()`, `fontsize()`, `italic()`, `bold()`, `color()`, `padding()`…

    myft <- italic(myft, j = 1)
    myft <- bg(myft, bg = "#C90000", part = "header")
    myft <- color(myft, color = "white", part = "header")
    myft

am | # carb. | gear | mpg | drat
1.000 | 4.000 | 4.000 | 21.000 | 3.900
4.000 | 21.000 | 3.900
1.000 | 4.000 | 22.800 | 3.850
0.000 | 3.000 | 21.400 | 3.080
2.000 | 3.000 | 18.700 | 3.150
1.000 | 3.000 | 18.100 | 2.760

Conditional formatting can be made by using the selector arguments. All formatting functions are accepting selector arguments.

    myft <- color(myft, ~ drat > 3.5, ~ drat, color = "red")
    myft <- bold(myft, ~ drat > 3.5, ~ drat, bold = TRUE)
    myft <- autofit(myft)

    myft

am | # carb. | gear | mpg | drat
1.000 | 4.000 | 4.000 | 21.000 | 3.900
4.000 | 21.000 | 3.900
1.000 | 4.000 | 22.800 | 3.850
0.000 | 3.000 | 21.400 | 3.080
2.000 | 3.000 | 18.700 | 3.150
1.000 | 3.000 | 18.100 | 2.760

## Supported output formats

When working in RStudio, flextable will be printed in the rstudio viewer pane.

### R Markdown documents

`flextables` can be inserted in R Markdown documents; HTML and Word output are managed with method `knitr::knit_print`.

Print the `flextable` object in the rmarkdown’s chunk as demonstrated in this document (…generated from an R Markdown document).

Note that pandoc 2.0 required for flextable rendering in docx with `rmarkdown`

### PowerPoint or Word documents with package officer

To add these objects in PowerPoint or Word documents, use functions:

- `ph_with_flextable()` or `ph_with_flextable_at()` (PowerPoint)
- `body_add_flextable()` (Word)

`officer` package is required to create a PowerPoint or Word document.

    library(officer)

The following is producing a PowerPoint document:

    ft <- regulartable(head(mtcars))
    ft <- theme_booktabs(ft)
    ft <- autofit(ft)

    ppt <- read_pptx()
    ppt <- add_slide(ppt, layout = "Title and Content", master = "Office Theme")
    ppt <- ph_with_flextable(ppt, value = ft, type = "body")

    print(ppt, target = "assets/pptx/example.pptx")

Download file example.pptx - view with office web viewer

The following is producing a Word document:

    doc <- read_docx()
    doc <- body_add_flextable(doc, value = ft)
    print(doc, target = "assets/docx/example.docx")

Download file example.docx - view with office web viewer

## xtable

`xtable` objects can be transformed as flextable objects with function `xtable_to_flextable()`.