doc: improve body_add_flextable manuals

DESCRIPTION

@@ -1,7 +1,7 @@
 Package: flextable
 Type: Package
 Title: Functions for Tabular Reporting
-Version: 0.9.5.020
+Version: 0.9.5.021
 Authors@R: c(
     person("David", "Gohel", role = c("aut", "cre"),
     email = "david.gohel@ardata.fr"),

R/body_add_flextable.R

@@ -1,31 +1,100 @@
 #' @export
 #' @title Add flextable into a Word document
-#' @description add a flextable into a Word document.
+#' @description Add a flextable into a Word document
+#' created with 'officer'.
+#'
+#' @details
+#' Use the [paginate()] function to define whether the table should
+#' be displayed on one or more pages, and whether the header should be
+#' displayed with the first lines of the table body on the same page.
+#'
+#' Use the [set_caption()] function to define formatted captions
+#' (with [as_paragraph()]) or simple captions (with a string).
+#' `topcaption` can be used to insert the caption before the table
+#' (default) or after the table (use `FALSE`).
 #' @param x an rdocx object
 #' @param value `flextable` object
 #' @param align left, center (default) or right.
+#' The `align` parameter is still supported for the time being, but
+#' we recommend using `set_flextable_defaults(table_align = "center")` instead
+#' that will set this default alignment for all flextables during
+#' the R session, or to define alignement for each table with
+#' `set_table_properties(align = "center")`.
 #' @param split set to TRUE if you want to activate Word
 #' option 'Allow row to break across pages'.
-#' @param keepnext Defunct in favor of [paginate()].
+#' This argument is still supported for the time being, but
+#' we recommend using `set_flextable_defaults(split = TRUE)` instead
+#' that will set this as default setting for all flextables during
+#' the R session, or to define alignement for each table with
+#' [set_table_properties()] with argument `opts_word=list(split = TRUE)`
+#' instead.
+#' @param keepnext Defunct in favor of [paginate()]. The default value
+#' used for `keep_with_next` is set with
+#' `set_flextable_defaults(keep_with_next = TRUE)`.
 #' @param pos where to add the flextable relative to the cursor,
 #' one of "after", "before", "on" (end of line).
 #' @param topcaption if TRUE caption is added before the table, if FALSE,
 #' caption is added after the table.
 #' @importFrom officer body_add_xml
+#' @seealso [knit_print.flextable()], [save_as_docx()]
 #' @examples
+#' \dontshow{
+#' init_flextable_defaults()
+#' }
 #' library(officer)
 #'
-#' # autonum for caption
-#' autonum <- run_autonum(seq_id = "tab", bkm = "mtcars")
+#' # define global settings
+#' set_flextable_defaults(
+#'   split = TRUE,
+#'   table_align = "center",
+#'   table.layout = "autofit"
+#' )
+#'
+#' # produce 3 flextable
+#' ft_1 <- flextable(head(airquality, n = 20))
+#' ft_1 <- color(ft_1, i = ~ Temp > 70, color = "red", j = "Temp")
+#' ft_1 <- highlight(ft_1, i = ~ Wind < 8, color = "yellow", j = "Wind")
+#' ft_1 <- set_caption(
+#'   x = ft_1,
+#'   autonum = run_autonum(seq_id = "tab"),
+#'   caption = "Daily air quality measurements"
+#' )
+#' ft_1 <- paginate(ft_1, init = TRUE, hdr_ftr = TRUE)
 #'
-#' ftab <- flextable(head(mtcars))
-#' ftab <- set_caption(ftab, caption = "mtcars data", autonum = autonum)
-#' ftab <- autofit(ftab)
+#' ft_2 <- proc_freq(mtcars, "vs", "gear")
+#' ft_2 <- set_caption(
+#'   x = ft_2,
+#'   autonum = run_autonum(seq_id = "tab", bkm = "mtcars"),
+#'   caption = as_paragraph(
+#'     as_b("mtcars"), " ",
+#'     colorize("table", color = "orange")
+#'   ),
+#'   fp_p = fp_par(keep_with_next = TRUE)
+#' )
+#' ft_2 <- paginate(ft_2, init = TRUE, hdr_ftr = TRUE)
+#'
+#' ft_3 <- summarizor(iris, by = "Species")
+#' ft_3 <- as_flextable(ft_3, spread_first_col = TRUE)
+#' ft_3 <- set_caption(
+#'   x = ft_3,
+#'   autonum = run_autonum(seq_id = "tab"),
+#'   caption = "iris summary"
+#' )
+#' ft_3 <- paginate(ft_3, init = TRUE, hdr_ftr = TRUE)
+#'
+#' # add the 3 flextable in a new Word document
 #' doc <- read_docx()
-#' doc <- body_add_flextable(doc, value = ftab)
+#' doc <- body_add_flextable(doc, value = ft_1)
+#' doc <- body_add_par(doc, value = "")
+#' doc <- body_add_flextable(doc, value = ft_2)
+#' doc <- body_add_par(doc, value = "")
+#' doc <- body_add_flextable(doc, value = ft_3)
+#'
 #' fileout <- tempfile(fileext = ".docx")
-#' # fileout <- "test.docx" # uncomment to write in your working directory
 #' print(doc, target = fileout)
+#' \dontshow{
+#' init_flextable_defaults()
+#' }
 body_add_flextable <- function(x, value,
                                align = NULL,
                                pos = "after",

R/defaults.R

@@ -27,6 +27,7 @@ default_flextable_settings <- list(
   fmt_date = "%Y-%m-%d", fmt_datetime = "%Y-%m-%d %H:%M:%S",
   extra_css = "",
   scroll = NULL,
+  table_align = "center",
   split = TRUE, keep_with_next = FALSE,
   tabcolsep = 2, arraystretch = 1.5, float = "none",
   fonts_ignore = FALSE,
@@ -88,6 +89,8 @@ flextable_global$defaults <- default_flextable_settings
 #' @param extra_css css instructions to be integrated with the table.
 #' @param scroll NULL or a list if you want to add a scroll-box.
 #' See **scroll** element of argument `opts_html` in function [set_table_properties()].
+#' @param table_align default flextable alignment, supported values are 'left', 'center'
+#' and 'right'.
 #' @param split Word option 'Allow row to break across pages' can be
 #' activated when TRUE.
 #' @param keep_with_next default initialization value used by the [paginate()]
@@ -148,6 +151,7 @@ set_flextable_defaults <- function(
     fmt_date = NULL, fmt_datetime = NULL,
     extra_css = NULL,
     scroll = NULL,
+    table_align = "center",
     split = NULL, keep_with_next = NULL,
     tabcolsep = NULL, arraystretch = NULL, float = NULL,
     fonts_ignore = NULL,
@@ -188,6 +192,10 @@ set_flextable_defaults <- function(
     x$font.color <- font.color
   }
 
+  if (!is.null(table_align) && table_align %in% c("left", "right", "center")) {
+    x$table_align <- table_align
+  }
+
   if (!is.null(text.align) && text.align %in% c("left", "right", "center", "justify")) {
     x$text.align <- text.align
   }

R/flextable.R

@@ -521,7 +521,7 @@ regulartable <- function(data, col_keys = names(data), cwidth = .75, cheight = .
 #' ft_4
 #' @family flextable dimensions
 set_table_properties <- function(x, layout = "fixed", width = 0,
-                                 align = "center",
+                                 align = NULL,
                                  opts_html = list(),
                                  opts_word = list(),
                                  opts_pdf = list(),
@@ -546,7 +546,7 @@ set_table_properties <- function(x, layout = "fixed", width = 0,
   x$properties <- list(
     layout = layout,
     width = width,
-    align = align,
+    align = if (is.null(align)) get_flextable_defaults()$table_align else align,
     opts_html = do.call(opts_ft_html, opts_html),
     opts_word = do.call(opts_ft_word, opts_word),
     opts_pdf = do.call(opts_ft_pdf, opts_pdf),