Chapter 12 Captions and cross-references

Captions are supported for HTML, PDF and Word output (also from a bookdown project with its specificic features for numbering table and figure captions).

Flextable caption features are slightly different from one format to another. With the Word format, we can produce real auto-numbered captions with a bookmark attached to the automatic number. This bookmark can then be used as a reference, i.e. for cross-referencing.

In a bookdown document, you will benefit from the cross-reference and linking capabilities. This is also true for document generated with officedown::rdocx_document() except that cross-references and links will be real Word links or cross-references.

The caption will be associated with a paragraph style when the output is Word. It can also be numbered as a auto-numbered Word computed value.

12.1 Captions with set_caption

To set a caption in the flextable, use function set_caption().

ft <- flextable(head(airquality))
ft <- set_caption(ft, "airquality dataset", 
  autonum = run_autonum(seq_id = "tab", bkm = "airquality6"))
ft

Table 12.1: airquality dataset
Ozone	Solar.R	Wind	Temp	Month	Day
41	190	7.4	67	5	1
36	118	8.0	72	5	2
12	149	12.6	74	5	3
18	313	11.5	62	5	4
<na>	<na>	14.3	56	5	5
28	<na>	14.9	66	5	6

12.2 Captions with knitr chunk options

flextable captions can be defined from R Markdown documents by using knitr::opts_chunk$set(). User don’t always have to call set_caption() to set a caption and can use knitr chunk options instead. A typical call would be:

#| tab.id: bookmark_id
#| tab.cap: caption text
flextable(head(cars))

12.2.1 ‘knitr’ chunk options for flextable captions

Most important parameters are the following and should be unique per flextable:

tab.cap: Caption label
tab.id: Caption reference unique identifier.

The following parameters should be the same all along your document.

tab.cap.style: Word style name or HTML class name to be used for table caption
tab.cap.pre: Prefix for Word numbering chunk (default to “Table”)
tab.cap.sep: Suffix for Word numbering chunk (default to “:”)
tab.topcaption: Caption position, “top” (TRUE, the default value) and “bottom” (FALSE)
tab.cap.fp_text: (only applies to Word output) caption suffix formatting properties, use officer::fp_text_lite().

You should not use different styles in a document, it is always easier to read a document written with typologically homogeneous elements (i.e. all captions are formatted the same way). Best is to set these values with function knitr::opts_chunk$set():

12.2.2 Illustrations by formats

The following R Markdown document will be transformed with various formats.

---
title: "flextable caption example"
---

```{r include=FALSE}
library(knitr)
library(flextable)
opts_chunk$set(echo = FALSE)
```

```{r}
ft <- qflextable(head(airquality, n = 5))
```

# Captions

Now, let's add a caption with `set_caption`:

```{r ft.align="left"}
library(officer)
set_caption(ft, 
  caption = "airquality dataset", 
  style = "Table Caption", 
  autonum = run_autonum(seq_id = "tab", bkm = "tab1"))
```

Or use kintr chunk options:

```{r ft.align="center", tab.cap='airquality dataset', tab.id='tab2', label='tab2'}
ft
```

# Cross-references

* This is a reference to flextable \@ref(tab:tab1).
* This is a reference to flextable \@ref(tab:tab2).

# Links

* This is a link to [flextable](#tab:tab1)

12.3 Formatting captions

Caption paragraph can be formatted with a call to as_paragraph(). There is no markdown transformation, instead, use the available functions of flextable dedicated to the chunks formatting: as_b(), as_chunk(), as_equation(), as_highlight(), as_image(), as_sub(), as_sup(), colorize(), grid_chunk(), hyperlink_text(), …

ft <- flextable(mtcars[1:4, 1:4])
ft <- set_caption(ft, 
    caption = as_paragraph(
      "Caption ",
      as_b("strong"),
      " and ",
      as_i("italic"),
      " and ",
      colorize("colorized", color = "red")
    )
  )
ft

Table 12.3: Caption strong and italic and colorized
mpg	cyl	disp	hp
21.0	6	160	110
21.0	6	160	110
22.8	4	108	93
21.4	6	258	110

Argument fp_p (an officer::fp_par() objects) let user specify caption paragraph settings such as borders, paddings and alignment. By default alignment is the same as the table alignment, but it can be changed by using align_with_table=FALSE, in that case, the alignment will not be overwritten by the table alignment.

fpp <- officer::fp_par(text.align = "left", padding = 6,
                       line_spacing = 2, 
                       border.left = fp_border_default(color = "orange"),
                       border.top = fp_border_default(color = "orange")
                       )

ft <- flextable(mtcars[1:4, 1:4])
ft <- set_caption(ft, 
    caption = "a caption",
    fp_p = fpp,
    align_with_table = FALSE
  )
ft

Table 12.4: a caption
mpg	cyl	disp	hp
21.0	6	160	110
21.0	6	160	110
22.8	4	108	93
21.4	6	258	110

12.4 Cross-references

When using bookdown, you can define a cross-reference to a flextable marked with a caption. To do so, use bookdown reference pattern \@ref(tab:airquality2) where airquality2 is the caption identifier you used.

You can also create a link with the following syntax: [Link to table](#tab:airquality2).

If you work with Quarto, be aware that cross-references are not managed yet. We need a mechanism to send caption information to Quarto and this feature should be implemented soon. We will then be able to implement the feature.

Chapter 12 Captions and cross-references

12.1 Captions with set_caption

12.2 Captions with knitr chunk options

12.2.1 ‘knitr’ chunk options for flextable captions

12.2.2 Illustrations by formats

12.2.2.1 R Markdown Word format

12.2.2.2 Bookdown and Word

12.2.2.3 Bookdown and HTML

12.2.2.4 Bookdown and PDF

12.3 Formatting captions

12.4 Cross-references