Function used to render flextable in knitr/rmarkdown documents.

You should not call this method directly. This function is used by the knitr package to automatically display a flextable in an "R Markdown" document from a chunk. However, it is recommended to read its documentation in order to get familiar with the different options available.

R Markdown outputs can be :

  • HTML

  • 'Microsoft Word'

  • 'Microsoft PowerPoint'

  • PDF

Table captioning is a flextable feature compatible with R Markdown documents. The feature is available for HTML, PDF and Word documents. Compatibility with the "bookdown" package is also ensured, including the ability to produce captions so that they can be used in cross-referencing.

For Word, it's recommanded to work with package 'officedown' that supports all features of flextable.

# S3 method for flextable
knit_print(x, ...)

Arguments

x

a flextable object

...

arguments passed to flextable_to_rmd().

Note

Supported formats require some minimum pandoc versions:

Output formatpandoc minimal version
HTML>= 1.12
Word (docx)>= 2.0
PowerPoint (pptx)>= 2.4
PDF>= 1.12

Chunk options

Some features, often specific to an output format, are available to help you configure some global settings relatve to the table output. knitr's chunk options are to be used to change the default settings:

chunk optionpropertydefault valueHTMLdocxPDFpptx
ft.alignflextable alignment, supported values are 'left', 'center' and 'right''center'yesyesyesno
ft.shadowHTML option, disable shadow dom (set to FALSE) for pagedown.TRUEyesnonono
ft.splitWord option 'Allow row to break across pages' can be activated when TRUE.FALSEnoyesnono
ft.keepnextWord option 'keep rows together' can be desactivated when FALSEFALSEnoyesnono
ft.tabcolsepspace between the text and the left/right border of its containing cell0nonoyesno
ft.arraystretchheight of each row relative to its default height1.5nonoyesno
ft.latex.floattype of floating placement in the document, one of 'none', 'float', 'wrap-r', 'wrap-l', 'wrap-i', 'wrap-o''none'nonoyesno
ft.leftleft coordinates in inches1.0nononoyes
ft.toptop coordinates in inches2.0nononoyes

If some values are to be used all the time in the same document, it is recommended to set these values in a 'knitr r chunk' by using function knitr::opts_chunk$set(ft.split=FALSE, ft.keepnext = FALSE, ...).

See flextable_to_rmd() for more details about these options.

Table caption

Captions can be defined in two ways.

The first is with the set_caption function. If it is used, the other method will be ignored. The second method is by using knitr chunk option tab.cap.

set_caption(x, caption = "my caption")

If set_caption function is not used, caption identifier will be read from knitr's chunk option tab.id. Note that in a bookdown and when not using officedown::rdocx_document(), the usual numbering feature of bookdown is used.

tab.id='my_id'.

Some options are available to customise captions for any output:

labelnamevalue
Word stylename to use for table captions.tab.cap.styleNULL
caption id/bookmarktab.idNULL
captiontab.capNULL
display table caption on top of the table or nottab.topcaptionTRUE
caption table sequence identifier.tab.lp"tab:"

Word output when officedown::rdocx_document() is used is coming with more options such as ability to choose the prefix for numbering chunk for example. The table below expose these options:

labelnamevalue
prefix for numbering chunk (default to "Table ").tab.cap.preTable
suffix for numbering chunk (default to ": ").tab.cap.sep" :"
title number depthtab.cap.tnd0
caption prefix formatting propertiestab.cap.fp_textfp_text_lite(bold = TRUE)
separator to use between title number and table number.tab.cap.tns"-"

HTML output

HTML output is using shadow dom to encapsule the table into an isolated part of the page so that no clash happens with styles. Some output may not support this feature. To our knowledge, only the pagedown output is concerned. Use knitr chunk option ft.shadow=FALSE to disable shadow dom.

If ft.shadow=TRUE some global CSS rules may change the desired output of flextables.

PDF output

Some features are not implemented in PDF due to technical infeasibility. These are the padding, line_spacing and height properties.

It is recommended to set theses values in a 'knitr r chunk' so that they are permanent all along the document: knitr::opts_chunk$set(ft.tabcolsep=0, ft.latex.float = "none").

Background color and merged cells does not work well together with PDF format. Authors are hoping to fix this issue in the future.

See add_latex_dep() if caching flextable results in 'R Markdown' documents.

PowerPoint output

Auto-adjust Layout is not available for PowerPoint, PowerPoint only support fixed layout. It's then often necessary to call function autofit() so that the columns' widths are adjusted if user does not provide the withs.

Images cannot be integrated into tables with the PowerPoint format.

Examples


# simple examples -----
demo_docx <- system.file(package = "flextable", "examples/rmd", "demo.Rmd")
rmd_file <- tempfile(fileext = ".Rmd")
file.copy(demo_docx, to = rmd_file, overwrite = TRUE)
#> [1] TRUE
rmd_file # R Markdown document used for demo
#> [1] "/tmp/Rtmp8v4LMn/file318d4c4bcef8.Rmd"
if (require("rmarkdown", quietly = TRUE)) {
  #  knitr::opts_chunk$set(webshot = "webshot2")
  #  render(input = rmd_file, output_format = "word_document", output_file = "doc.docx")
  #  render(input = rmd_file, output_format = "pdf_document", output_file = "doc.pdf")
  #  render(input = rmd_file, output_format = "html_document", output_file = "doc.html")
  #  render(input = rmd_file, output_format = "powerpoint_presentation", output_file = "pres.pptx")
  #  render(input = rmd_file, output_format = "slidy_presentation", output_file = "slidy.html")
  #  render(input = rmd_file, output_format = "beamer_presentation", output_file = "beamer.pdf")
  #  render(input = rmd_file, output_format = "pagedown::html_paged", output_file = "paged.html")
}
#> NULL


## bookdown examples wth captions and cross ref -----
# captions_example <- system.file(
#   package = "flextable",
#   "examples/rmd", "captions_example.Rmd")
#
# dir_tmp <- tempfile(pattern = "dir")
# dir.create(dir_tmp, showWarnings = FALSE, recursive = TRUE)
# file.copy(captions_example, dir_tmp)
# rmd_file <- file.path(dir_tmp, basename(captions_example))
#
# file.copy(captions_example, to = rmd_file, overwrite = TRUE)
#
# if(require("rmarkdown", quietly = TRUE)){
#   render(input = rmd_file,
#          output_format = word_document(),
#          output_file = "doc.docx")
#   render(input = rmd_file,
#          output_format = pdf_document(latex_engine = "xelatex"),
#          output_file = "doc.pdf")
#   render(input = rmd_file,
#          output_format = html_document(),
#          output_file = "doc.html")
#
#   # bookdown ----
#   if(require("bookdown", quietly = TRUE)){
#     render(input = rmd_file, output_format = word_document2(),
#            output_file = "book.docx")
#     render(input = rmd_file,
#            output_format = pdf_document2(latex_engine = "xelatex"),
#            output_file = "book.pdf")
#     render(input = rmd_file,
#            output_format = html_document2(),
#            output_file = "book.html")
#
#     # officedown ----
#     if(require("officedown", quietly = TRUE)){
#       render(input = rmd_file,
#              output_format = markdown_document2(base_format=rdocx_document),
#              output_file = "officedown.docx")
#     }
#   }
# }
# browseURL(dirname(rmd_file))