diff --git a/DESCRIPTION b/DESCRIPTION index 7012710e..16835ca5 100644 --- a/DESCRIPTION +++ b/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"), diff --git a/R/body_add_flextable.R b/R/body_add_flextable.R index 7b571b1a..b3b99295 100644 --- a/R/body_add_flextable.R +++ b/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", diff --git a/R/defaults.R b/R/defaults.R index aaef58ff..80aeaf91 100644 --- a/R/defaults.R +++ b/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 } diff --git a/R/flextable.R b/R/flextable.R index cdcca393..a95240df 100644 --- a/R/flextable.R +++ b/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), diff --git a/man/body_add_flextable.Rd b/man/body_add_flextable.Rd index e3327b16..c438541b 100644 --- a/man/body_add_flextable.Rd +++ b/man/body_add_flextable.Rd @@ -19,34 +19,105 @@ body_add_flextable( \item{value}{\code{flextable} object} -\item{align}{left, center (default) or right.} +\item{align}{left, center (default) or right. +The \code{align} parameter is still supported for the time being, but +we recommend using \code{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 +\code{set_table_properties(align = "center")}.} \item{pos}{where to add the flextable relative to the cursor, one of "after", "before", "on" (end of line).} \item{split}{set to TRUE if you want to activate Word -option 'Allow row to break across pages'.} +option 'Allow row to break across pages'. +This argument is still supported for the time being, but +we recommend using \code{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 +\code{\link[=set_table_properties]{set_table_properties()}} with argument \code{opts_word=list(split = TRUE)} +instead.} \item{topcaption}{if TRUE caption is added before the table, if FALSE, caption is added after the table.} -\item{keepnext}{Defunct in favor of \code{\link[=paginate]{paginate()}}.} +\item{keepnext}{Defunct in favor of \code{\link[=paginate]{paginate()}}. The default value +used for \code{keep_with_next} is set with +\code{set_flextable_defaults(keep_with_next = TRUE)}.} } \description{ -add a flextable into a Word document. +Add a flextable into a Word document +created with 'officer'. +} +\details{ +Use the \code{\link[=paginate]{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 \code{\link[=set_caption]{set_caption()}} function to define formatted captions +(with \code{\link[=as_paragraph]{as_paragraph()}}) or simple captions (with a string). +\code{topcaption} can be used to insert the caption before the table +(default) or after the table (use \code{FALSE}). } \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" +) -ftab <- flextable(head(mtcars)) -ftab <- set_caption(ftab, caption = "mtcars data", autonum = autonum) -ftab <- autofit(ftab) +# 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) + +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() +} +} +\seealso{ +\code{\link[=knit_print.flextable]{knit_print.flextable()}}, \code{\link[=save_as_docx]{save_as_docx()}} } diff --git a/man/set_flextable_defaults.Rd b/man/set_flextable_defaults.Rd index 1d512aa2..f386b599 100644 --- a/man/set_flextable_defaults.Rd +++ b/man/set_flextable_defaults.Rd @@ -33,6 +33,7 @@ set_flextable_defaults( fmt_datetime = NULL, extra_css = NULL, scroll = NULL, + table_align = "center", split = NULL, keep_with_next = NULL, tabcolsep = NULL, @@ -108,6 +109,9 @@ documented in \code{\link[=strptime]{strptime()}}. Default to '\%Y-\%m-\%d' and \item{scroll}{NULL or a list if you want to add a scroll-box. See \strong{scroll} element of argument \code{opts_html} in function \code{\link[=set_table_properties]{set_table_properties()}}.} +\item{table_align}{default flextable alignment, supported values are 'left', 'center' +and 'right'.} + \item{split}{Word option 'Allow row to break across pages' can be activated when TRUE.} diff --git a/man/set_table_properties.Rd b/man/set_table_properties.Rd index 383b8c6a..8357e61e 100644 --- a/man/set_table_properties.Rd +++ b/man/set_table_properties.Rd @@ -8,7 +8,7 @@ set_table_properties( x, layout = "fixed", width = 0, - align = "center", + align = NULL, opts_html = list(), opts_word = list(), opts_pdf = list(),