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
# add a page break
mydoc <- addPageBreak( mydoc )
# add text with stylename "Normal" into mydoc
# add a plot into mydoc
filename <- "base_example.docx" # the document to produce
# write the doc
writeDoc( mydoc, file = filename)Download file base_example.docx - view with office web viewer
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
# use default template
doc <- docx()If template content should be deleted, use the argument empty_template=TRUE when calling docx function:
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 )## Normal heading 1
## "Normal" "Titre1"
## heading 2 heading 3
## "Titre2" "Titre3"
## heading 4 heading 5
## "Titre4" "Titre5"
## heading 6 heading 7
## "Titre6" "Titre7"
## heading 8 heading 9
## "Titre8" "Titre9"
## Title Subtitle
## "Titre" "Sous-titre"
## Quote Intense Quote
## "Citation" "Citationintense"
## caption TOC Heading
## "Lgende" "En-ttedetabledesmatires"
## No Spacing List Paragraph
## "Sansinterligne" "Paragraphedeliste"
## rPlotLegend header
## "rPlotLegend" "En-tte"
## footer Titre1
## "Pieddepage" "Titre10"
## BulletList Titre2
## "BulletList" "Titre20"
## TitleDoc rRawOutput
## "TitleDoc" "rRawOutput"
## rTableLegend
## "rTableLegend"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.
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'
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))
# Create a new document
# display available styles
styles( mydoc )## Normal heading 1 heading 2 header
## "Normal" "Titre1" "Titre2" "En-tte"
## footer Title rcode figurereference
## "Pieddepage" "Titre" "rcode" "figurereference"
## tablereference
## "tablereference"
mydoc <- addPageBreak( mydoc )
stylename = "figurereference") %>% # Add a legend below the plot
stylename = "tablereference") # Add a legend below the table
stylename = "figurereference") %>% # Add a legend below the plot
stylename = "tablereference") # Add a legend below the table
filename <- "toc.docx" # the document to produce
writeDoc( mydoc, file = filename)Download file toc.docx - view with office web viewer
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()
addSection( )
filename <- "section.docx" # the document to produce
writeDoc( doc, file = filename)Download file section.docx - view with office web viewer