knitr::opts_chunk$set(echo = TRUE) library(ReporteRs) options("ReporteRs-fontsize" = 11)
Use the function docx
to create an r object representing a Word document.
It takes two arguments: a title (appearing only in the Word document properties)
and a template file. If none is provided, the template file will be an empty
document located in the package directory.
When creating a docx object, you use a template file. This file is copied in memory and that copy becomes the document that will be completed with R outputs. Formats and available styles will be those available in the template file.
Next, you create the components of your docx file. You create and format text, then insert it using the addParagraph function. You create and insert tables, perhaps merging cells, changing row and column colors or fonts. And, of course, you add plots. Tables, plots and paragraphs formats can be customised with dedicated functions.
Finally, using writeDoc
, you write the object into a file
with the suffix .docx
on your file system.
Below you can follow this process with a commented R script:
library( ReporteRs ) # Creation of mydoc, a mydocx object mydoc <- docx( ) # add into mydoc first 10 lines of iris mydoc <- addFlexTable( mydoc, vanilla.table(iris[1:10,] ) ) # add a page break mydoc <- addPageBreak( mydoc ) # add text with stylename "Normal" into mydoc mydoc <- addParagraph( mydoc, value = "Hello World!", stylename = "Normal" ) # add a plot into mydoc mydoc <- addPlot( mydoc, function() barplot( 1:8, col = 1:8 ) ) filename <- "base_example.docx" # the document to produce # write the doc writeDoc( mydoc, file = filename)
office_web_viewer( url = paste0( "https://davidgohel.github.io/ReporteRs/articles/", basename(filename) ) )
You may need to generate docx documents in a particular corporate template
(with specific fonts, colour schemes, logos, etc.). The function docx
has an optional argument template, it lets you create documents based
on existing Word documents.
If you don't direct ReporteRs to a template file, an empty document will be used (located into the package directory) and you will have a document with its Word styles.
It loads in memory your template word document to add content to. R outputs will be inserted at the end of that copy (except if you are using bookmarks). The approach is to use a Word document that contains the layout and main styles of your final document. You can edit an existing file in Word, delete the whole content or not, modify paragraph styles, headers, etc., and use it as a template. New reports will have the same layout and styles than the template.
# use D:/docs/template/my_corporate_template.docx as template doc <- docx(template = 'D:/docs/template/my_corporate_template.docx') # use default template doc <- docx()
If template content should be deleted, use the argument empty_template=TRUE
when calling docx
function:
doc <- docx(template = 'D:/docs/template/my_corporate_template.docx', empty_template = TRUE)
Available styles will be paragraph styles of the base document (e.g. Normal, Title1, etc.). Names of the returned character vector are internal Word labels associated with styles names.
doc <- docx() styles( doc )
When using a template, styles names of the template should only
contain letters (from a to z) and numbers. For example, in France
the default style named Legend
becomes L?gende
and is returned as Lgende
by the styles R function. The workaround
is to create a new style based on L?gende
and to name it Legende
.
It will be then a valid name to use with ReporteRs.
styles are used by several function, adding text with addParagraph
,
adding titles with addTitle
, adding specific TOC with addTOC
.
Function addParagraph
has an optional argument stylename
whose value must
be one of the names returned by the function styles
.
doc <- addParagraph( doc, value = "Hello", stylename = "Normal")
Insert a table of contents with function addTOC
.
doc <- addTOC(doc)
When added, a TOC will make Word to pop-up a message-box asking you if you want to update TOC entries. This is not an error, you should click 'Yes' to update TOC entries.
Add a customized table of contents with the argument stylename
.
If used, a table of contents will be created containing entries
formatted with specified styles.
# add a table of all paragraphs with style 'stylename' doc <- addTOC( doc, stylename = 'stylename' )
Example: Add a list of figures and a list of tables
In the following example, style figurereference
is used as style of paragraphs
following graphics, as a caption for plots. Style tablereference
is used as style
of paragraphs following table, as a caption for tables.
These styles are available in the template file templates/template_toc.docx.
We will:
library( ReporteRs ) library( ggplot2 ) library(magrittr) myplot1 <- qplot(Sepal.Length, Petal.Length, data = iris, color = Species, size = Petal.Width, alpha = I(0.7)) myplot2 <- qplot(mpg, wt, data = mtcars, colour = cyl ) # Create a new document mydoc <- docx( template = "template_toc.docx" ) # display available styles styles( mydoc ) mydoc <- mydoc %>% addTitle( "Table of contents", level = 1 ) %>% addTOC( ) %>% # add a table of content addPageBreak() # add a page break mydoc <- mydoc %>% addTitle( "List of graphics", level = 1 ) %>% addTOC( stylename = "figurereference" ) %>% addTitle( "List of tables", level = 1 ) %>% addTOC( stylename = "tablereference" ) mydoc <- addPageBreak( mydoc ) mydoc <- mydoc %>% addTitle( "iris outputs", level = 1 ) %>% addTitle( "Plot", level = 2 ) %>% addPlot(function( ) print( myplot1 ) ) %>% addParagraph( value = "iris plot", stylename = "figurereference") %>% # Add a legend below the plot addTitle( "Table", level = 2 ) %>% addFlexTable( vanilla.table( head( iris ) ) ) %>% addParagraph( value = "iris table", stylename = "tablereference") # Add a legend below the table mydoc <- mydoc %>% addTitle( "mtcars outputs", level = 1 ) %>% addTitle( "Plot", level = 2 ) %>% addPlot(function( ) print( myplot2 ) ) %>% addParagraph( value = "mtcars plot", stylename = "figurereference") %>% # Add a legend below the plot addTitle( "Table", level = 2 ) %>% addFlexTable( vanilla.table( head( mtcars ) ) ) %>% addParagraph( value = "mtcars table", stylename = "tablereference") # Add a legend below the table filename <- "toc.docx" # the document to produce writeDoc( mydoc, file = filename)
office_web_viewer( url = paste0( "https://davidgohel.github.io/ReporteRs/articles/", basename(filename) ) )
Insert a page break with function addPageBreak
doc <- addPageBreak(doc)
Function addSection
lets you add a section.
With a section, you can change document orientation and
split new content along 2 or more columns.
The function requires you to add a section before and after the item(s) that you want to be on a landscape and/or multicolumns mode page.
library(magrittr) doc <- docx() doc <- addSection( doc, landscape = TRUE) %>% addFlexTable( vanilla.table(mtcars)) %>% addSection() doc <- addSection( doc, ncol = 2, landscape = FALSE) %>% addParagraph( "My text on column 1", stylename = "Normal" ) %>% addColumnBreak( ) %>% addParagraph("Hi on the right", stylename = "Normal" ) %>% addSection( ) filename <- "section.docx" # the document to produce writeDoc( doc, file = filename)
office_web_viewer( url = paste0( "https://davidgohel.github.io/ReporteRs/articles/", basename(filename) ) )
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.