report_add_doc_content: Add Content to Body of a Word Document Report

In onbrand: Templated Reporting Workflows in Word and PowerPoint

Add Content to Body of a Word Document Report

Description

Appends content to the body of a Word document

Usage

report_add_doc_content(
  obnd,
  type = NULL,
  content = NULL,
  fig_start_at = NULL,
  tab_start_at = NULL,
  verbose = TRUE
)

Arguments

obnd	onbrand report object
type	Type of content to add
content	Content to add
fig_start_at	Indicates that you want to restart figure numbering at the specified value (e.g. 1) after adding this content a value of NULL (default) will ignore this option.
tab_start_at	Indicates that you want to restart figure numbering at the specified value (e.g. 1) after adding this content a value of NULL (default) will ignore this option.
verbose	Boolean variable when set to TRUE (default) messages will be displayed on the terminal; Messages will be included in the returned onbrand object.

Details

For each content types listed below the different content outlined is expected. Text can be specified in different formats: "text" indicates plain text, "fpar" is formatted text defined by the fpar command from the officer package, "ftext" is a list of formatted text defined by the ftext command, and "md" is text formatted in markdown format (?md_to_officer for markdown details).

• "break" page break, content is (NULL) and a page break will be inserted here

• "ph" adds placeholder text substitution

  • "name" placeholder name (value in body of text surrounded by three equal signs, e.g. if you have "===MYPH===". in the document the name is just "MYPH")

  • "value" value to be substituted into the placeholder ("my text")

  • "location" document location where the placeholder will be located (either "header", "footer", or "body")

• "toc" generates the table of contents, and content is a list that must contain __one__ of the following.

  • "level" number indicating the depth of the contents to display (default: 3)

  • "style" string containing the onbrand style name to use to build the TOC

• "section" formats the current document section

  • "section_type" type of section to apply, either "columns", "continuous", "landscape", "portrait", "columns", or "columns_landscape"

  • "width" override the default page width with this value in inches (NULL)

  • "height" override the default page height with this value in inches (NULL)

  • "widths" column widths in inches, number of columns set by number of values (NULL)

  • "space" space in inches between columns (NULL)

  • "sep" Boolean value controlling line separating columns (FALSE)

• "text" content is a list containing a paragraph of text with the following elements

  • "text" string containing the text content either a string or the output of "fpar" for formatted text.

  • "style" string containing the style to use (default NULL will use the doc_def, Text style)

  • "format" string containing the format, either "text", "fpar", or "md" (default NULL assumes "text" format)

• "imagefile" content is a list containing information describing an image file with the following elements

  • image string containing path to image file

  • caption caption of the image (NULL)

  • caption_format string containing the format, either "text", "ftext", or "md" (default NULL assumes "text" format)

  • notes notes to add under the image (NULL)

  • notes_format string containing the format, either "text", "ftext", or "md" (default NULL assumes "text" format)

  • key unique key for cross referencing e.g. "FIG_DATA" (NULL)

  • height height of the image (NULL)

  • width width of the image (NULL)

• "ggplot" content is a list containing a ggplot object, (eg. p = ggplot() + ....) with the following elements

  • image ggplot object

  • caption caption of the image (NULL)

  • caption_format string containing the format, either "text", "ftext", or "md" (default NULL assumes "text" format)

  • notes notes to add under the image (NULL)

  • notes_format string containing the format, either "text", "ftext", or "md" (default NULL assumes "text" format)

  • key unique key for cross referencing e.g. "FIG_DATA" (NULL)

  • height height of the image (NULL)

  • width width of the image (NULL)

• "table" content is a list containing the table content and other options with the following elements:

  • table data frame containing the tabular data

  • "style" string containing the style to use (default NULL will use the doc_def, Table style)

  • caption caption of the table (NULL)

  • caption_format string containing the format, either "text", "ftext", or "md" (default NULL assumes "text" format)

  • notes notes to add under the image (NULL)

  • notes_format string containing the format, either "text", "ftext", or "md" (default NULL assumes "text" format)

  • key unique key for cross referencing e.g. "TAB_DATA" (NULL)

  • header Boolean variable to control displaying the header (TRUE)

  • first_row Boolean variable to indicate that the first row contains header information (TRUE)

• "flextable" content is a list containing flextable content and other options with the following elements (defaults in parenthesis):

  • table data frame containing the tabular data

  • caption caption of the table (NULL)

  • caption_format string containing the format, either "text", "ftext", or "md" (default NULL assumes "text" format)

  • notes notes to add under the image (NULL)

  • notes_format string containing the format, either "text", "ftext", or "md" (default NULL assumes "text" format)

  • key unique key for cross referencing e.g. "TAB_DATA" (NULL)

  • header_top, header_middle, header_bottom (NULL) a list with the same names as the data frame names containing the tabular data and values with the header text to show in the table

  • header_format string containing the format, either "text", or "md" (default NULL assumes "text" format)

  • merge_header (TRUE) Set to true to combine column headers with the same information

  • table_body_alignment, table_header_alignment ("center") Controls alignment

  • table_autofit (TRUE) Automatically fit content, or specify the cell width and height with cwidth (0.75) and cheight (0.25)

  • table_theme ("theme_vanilla") Table theme

• "flextable_object" content is a list specifying the a user defined flextable object with the following elements:

  • ft flextable object

  • caption caption of the table (NULL)

  • caption_format string containing the format, either "text", "ftext", or "md" (default NULL assumes "text" format)

  • notes notes to add under the image (NULL)

  • notes_format string containing the format, either "text", "ftext", or "md" (default NULL assumes "text" format)

  • key unique key for cross referencing e.g. "TAB_DATA" (NULL)

Value

onbrand object with the content added to the body or isgood set to FALSE with any messages in the msgs field. The isgood value is a Boolean variable indicating the current state of the object.

Examples

# Read  Word template into an onbrand object
obnd = read_template(
 template = file.path(system.file(package="onbrand"), "templates", "report.docx"),
 mapping  = file.path(system.file(package="onbrand"), "templates", "report.yaml"))

# The examples below use the following packages
library(ggplot2)
library(flextable)
library(officer)

# Adding text
obnd = report_add_doc_content(obnd,
  type     = "text",
  content  = list(text="Text with no style specified will use the doc_def text format."))


# Text formatted with fpar
fpartext = fpar(
ftext("Formatted text can be created using the ", prop=NULL),
ftext("fpar ", prop=fp_text(color="green")),
ftext("command from the officer package.", prop=NULL))

obnd = report_add_doc_content(obnd,
 type     = "text",
 content  = list(text   = fpartext,
                 format = "fpar",
                 style  = "Normal"))

# Text formatted with markdown
mdtext = "Formatted text can be created using
**<color:green>markdown</color>** formatting"
obnd = report_add_doc_content(obnd,
 type     = "text",
 content  = list(text   = mdtext,
                 format = "md",
                 style  = "Normal"))


# Adding figures
p = ggplot() + annotate("text", x=0, y=0, label = "picture example")
imgfile = tempfile(pattern="image", fileext=".png")
ggsave(filename=imgfile, plot=p, height=5.15, width=9, units="in")

# From an image file:
obnd = report_add_doc_content(obnd,
type     = "imagefile",
content  = list(image   = imgfile,
               caption = "This is an example of an image from a file."))

# From a ggplot object
obnd = report_add_doc_content(obnd,
type     = "imagefile",
content  = list(image   = imgfile,
               caption = "This is an example of an image from a file."))


#Adding tables
tdf =    data.frame(Parameters = c("Length", "Width", "Height"),
                Values     = 1:3,
                Units      = c("m", "m", "m") )

# Word table
tab_cont = list(table   = tdf,
               caption = "Word Table.")
obnd = report_add_doc_content(obnd,
 type     = "table",
 content  = tab_cont)

# onbrand flextable abstraction:
tab_cont = list(table   = tdf,
               caption = "Word Table.")
obnd = report_add_doc_content(obnd,
type     = "table",
content  = tab_cont)

# flextable object
tab_fto = flextable(tdf)
obnd = report_add_doc_content(obnd,
 type     = "flextable_object",
 content  = list(ft=tab_fto,
                 caption  = "Flextable object created by the user."))

# Saving the report output
save_report(obnd, tempfile(fileext = ".docx"))

onbrand documentation built on May 29, 2024, 11:17 a.m.