Guide:

1. Setup: Create a template document and insert flags to be populated with R data.

2. Create a Dictionary: Call getDictionary(“/path/to/template.docx”) to create an empty dictionary.

3. Fill Dictionary: Fill in the replacement dictionary values with data from R environment.

4. Validate Dictionary (Optional): Use checkDictionary(dictionary) to ensure dictionary meets requirements.

5. Process Document: Call docket(“/path/to/template.docx”, dictionary, “/path/to/output.docx”) to create populated template document

6. Creating Multiple Documents To create mutliple output documents from one template, use the “batch” version of the docket functions to improve processing efficiency.

Included Example Template

library(docket)

template_path <- system.file("template_document", "Template.docx", package="docket")

print(template_path)

## [1] "C:/Users/Jonra/AppData/Local/Temp/RtmpmmVa4o/Rinst8f30608e61e7/docket/template_document/Template.docx"

Formatting and Repeated Values

For performance reasons, when creating a template document, there should only be one flag per instance of data to be populated to the final document.

Incorrect

1. «Today» <- as.character(Sys.Date())
2. «Today_2» <- as.character(Sys.Date())
3. «Today_Italics» <- as.character(Sys.Date())
4. «Author» <- “John Doe”
5. «Author_Bold» <- “John Doe”
6. «Author_Italics» <- “John Doe”

Correct

1. «Today» <- as.character(Sys.Date())
2. «Author» <- “John Doe”

‘docket’ replacement values inherit the formatting of the flags they replace and can be duplicated across a document.

library(knitr)
template_screenshot <- system.file("template_document", "Document_Template.png", package="docket")
include_graphics(template_screenshot)

Note how «Author» and «Date» appear twice with different formatting. To ensure formatting propagates into the final document, format the entire flag - including the guillemets («») - in the template.

Example

myDictionary <- getDictionary(template_path)

print(myDictionary)

##              flag replace.values
## 1        «Author»             NA
## 2          «Date»             NA
## 3 «Category1_Obs»             NA
## 4 «Category2_Obs»             NA
## 5 «Category3_Obs»             NA
## 6     «Total_Obs»             NA

Example

#check the dictionary to ensure it is valid
print(checkDictionary(myDictionary))

## [1] TRUE

Dictionary Requirements

1. The dictionary is a data frame consisting of 2 columns
2. The first column is named “flag”
3. Each entry in the first column is a string surrounded by guillemets («»)

Additionally, While it’s not required for a dictionary to be generated by getDictionary(), dictionaries that do not meet these specifications will be rejected.

Null Values

Any flag not assigned a corresponding value will maintain its original flag in the output document. If a flag represents a null value, insert this as a string.

Incorrect

1. «Character» <- “John Doe”
2. «Title» <- NA
3. «Items» <- NULL

Correct

1. «Character» <- “John Doe”
2. «Title» <- “NA”
3. «Items» <- “NULL”

Example

output_path <- paste0(normalizePath(tempdir(), winslash = "/"), "/output document.docx")

#If docket accepts the input dictionary as valid, create a filled template

if (checkDictionary(myDictionary) == TRUE) {
  docket(template_path, myDictionary, output_path)
}

print(file.exists(output_path))

## [1] TRUE

getBatchDictionary()

A batch dictionary is similar to a normal dictionary in that each row represents a flag value to be replaced. However, batch dictionaries also include the name of the output file in row 1, and additional columns containing the values for each document to be populated.

# Path to the sample template file included in the package
template_path <- system.file("batch_document", "batchTemplate.docx", package="docket")

temp_dir <- normalizePath(tempdir(), winslash = "/")
output_paths <- as.list(paste0(temp_dir, paste0("/batch document", 1:5, ".docx")))

# Create a dictionary by using the getDictionary function on the sample template file
myBatchDictionary <- getBatchDictionary(template_path, output_paths)

checkBatchDictionary()

Checks that the batch dictionary meets the requirements of a normal dictionary and contains the output file names in row 1.

myBatchDictionary[2,2:ncol(myBatchDictionary)] <- Sys.getenv("USERNAME") #Author name
myBatchDictionary[3,2:ncol(myBatchDictionary)] <- as.character(Sys.Date())
myBatchDictionary[4,2:ncol(myBatchDictionary)] <- 123
myBatchDictionary[5,2:ncol(myBatchDictionary)] <- 456
myBatchDictionary[6,2:ncol(myBatchDictionary)] <- 789
myBatchDictionary[7,2:ncol(myBatchDictionary)] <- sum(as.numeric(myBatchDictionary[4:6,2]))

print(checkBatchDictionary(myBatchDictionary))

## [1] TRUE

batchDocket()

Call batchDocket() with the template name and batch dictionary as arguments

#Create multiple populated documents
if (checkBatchDictionary(myBatchDictionary) == TRUE) {
 batchDocket(template_path, myBatchDictionary)
}

#Verify documents exist
for (i in 1:length(output_paths)) {
   if (file.exists(output_paths[[i]])) {
     print(paste("docket", i, "Successfully Created"))
  }
}

## [1] "docket 1 Successfully Created"
## [1] "docket 2 Successfully Created"
## [1] "docket 3 Successfully Created"
## [1] "docket 4 Successfully Created"
## [1] "docket 5 Successfully Created"