flextable (version 0.8.2)

set_caption: Set Caption

Description

Set caption value in a flextable. The function can also be used to define formattings that will be applied if possible to Word and HTML outputs.

• 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.

• The PowerPoint format ignores captions. PowerPoint documents are not structured and do not behave as HTML documents and paginated documents (word, pdf), and it's not possible to know where we should create a shape to contain the caption (technically it can't be in the PowerPoint shape containing the table).

When working with 'R Markdown' or 'Quarto', the caption settings defined with set_caption() will be prioritized over knitr chunk options.

Usage

set_caption(
  x,
  caption = NULL,
  autonum = NULL,
  word_stylename = "Table Caption",
  style = word_stylename,
  fp_p = NULL,
  align_with_table = TRUE,
  html_classes = NULL,
  html_escape = TRUE
)

Arguments

x

flextable object

caption

caption value.

autonum

an autonum representation. See officer::run_autonum(). This has only an effect when output is Word. If used, the caption is preceded by an auto-number sequence. In this case, the caption is preceded by an auto-number sequence that can be cross referenced.

word_stylename, style

'Word' style name to associate with caption paragraph. These names are available with function officer::styles_info() when output is Word. Argument style is deprecated in favor of word_stylename.

fp_p

paragraph formatting properties associated with the caption, see fp_par(). It applies when possible, i.e. in HTML and 'Word' but not with bookdown.

align_with_table

if TRUE, caption is aligned as the flextable, if FALSE, fp_p will not be updated and alignement is as defined with fp_p. It applies when possible, i.e. in HTML and 'Word' but not with bookdown.

html_classes

css class(es) to apply to associate with caption paragraph when output is 'Word'.

html_escape

should HTML entities be escaped so that it can be safely included as text or an attribute value within an HTML document.

R Markdown

flextable captions can be defined from R Markdown documents by using knitr::opts_chunk$set(). The following options are available with officedown::rdocx_document and/or bookdown:

label	name	value
Word stylename to use for table captions.	tab.cap.style	NULL
caption id/bookmark	tab.id	NULL
caption	tab.cap	NULL
display table caption on top of the table or not	tab.topcaption	TRUE
caption table sequence identifier.	tab.lp	"tab:"

The following options are only available when used with officedown::rdocx_document:

label	name	value
prefix for numbering chunk (default to "Table ").	tab.cap.pre	Table
suffix for numbering chunk (default to ": ").	tab.cap.sep	" :"
title number depth	tab.cap.tnd	0
separator to use between title number and table number.	tab.cap.tns	"-"
caption prefix formatting properties	tab.cap.fp_text	fp_text_lite(bold = TRUE)

See knit_print.flextable for more details.

Using 'Quarto'

'Quarto' manage captions and cross-references instead of flextable. That's why set_caption() is not useful in a 'Quarto' document except for Word documents where 'Quarto' does not manage captions yet (when output is raw xml which is the case for flextable).

knitr options are almost the same than those detailled in the R Markdown section (see upper), but be aware that 'Quarto' manage captions and it can be overwrite what has been defined by flextable. See Quarto documentation for more information.

Details

The values defined by set_caption() will be preferred when possible, i.e. the caption ID, the associated paragraph style, etc. Why specify "where possible"? Because the principles differ from tool to tool. Here is what we have noticed and tried to respect (if you think we are wrong, let us know):

• Word and HTML documents made with 'rmarkdown', i.e. with rmarkdown::word_document() and rmarkdown::html_document() are not supposed to have numbered and cross-referenced captions.

• PDF documents made with 'rmarkdown' rmarkdown::pdf_document() automatically add numbers before the caption.

• Word and HTML documents made with 'bookdown' are supposed to have numbered and cross-referenced captions. This is achieved by 'bookdown' but for technical reasons, the caption must not be defined in an HTML or XML block. So with flextable we lose the ability to format the caption content; surprisingly this is not the case with PDF.

• HTML and PDF documents created with Quarto will manage captions and cross-references differently; Quarto will replace captions with tbl-cap and label values.

• Word documents made with Quarto are another specific case, Quarto does not inject captions from the tbl-cap and label values. This is a temporary situation that should evolve later. flextable' will evolve according to the evolution of Quarto.

Using officer enable all options specified with set_caption().

See Also

flextable()

Examples

ftab <- flextable( head( iris ) )
ftab <- set_caption(ftab, "my caption")
ftab

library(officer)
autonum <- run_autonum(seq_id = "tab", bkm = "mtcars")
ftab <- flextable( head( mtcars ) )
ftab <- set_caption(ftab, caption = "mtcars data", autonum = autonum)
ftab