{sparkle} is intended to be a package that empowers programmers to easily add content to MS Word documents at specific locations via a standardized API. The power of {sparkle} comes through its ability to easily be extended to support any sort of input via the “polish_content” method.
To get started, lets first load in an example word document included
in the package. This is done with the load_docx() function
and the path to the word document.
sparkle_doc_path <- system.file("basic_sparkle_doc.docx", package = "sparkle")
my_doc <- load_docx(path = sparkle_doc_path)Now that the document has been loaded, we can see where the document author wanted to add content via text highlighted by comments. For this we call comments_df() on the document object (my_doc).
The function generates a tibble showing: comment_id: the unique identifier of the comment docx_text: the text within the documnent that is commented on comment_text: the text within the comment comment_author: who generated the comment
sparkle::comments_df(my_doc)
#> # A tibble: 6 × 4
#> comment_id docx_text comment_text comment_author
#> <chr> <chr> <chr> <chr>
#> 1 0 {{object}} mtcars Ellis Hughes
#> 2 1 {{file}} inst/test_file.txt Ellis Hughes
#> 3 2 Insert Object new_df Ellis Hughes
#> 4 3 Insert File My_File_123.txt Ellis Hughes
#> 5 4 {{inline insert}} Inline VALUE Ellis Hughes
#> 6 5 {{inline insert}} This is a test reply Ellis HughesThe combination of all this information is what tells you which content should be added where in the document.
For example, comment 0 highlighted the text “{{object}}” and in the comment the user wrote “mtcars”. As a programmer we can interpret that this means the user wants to add the mtcars dataset object at that comment.
Now that we know which comments exist where, we can now determine
which content shall be added. The most basic approach is to use the
add_sparkle() function. This takes the document object, a
comment id, and a value to be added into the document. This is the most
direct way to add content.
When possible the value will be polished via the “polish_content”
method into viable ooxml
, to be then added into the word doc. To see what objects have methods,
use ?polish_content to review the help pages.
my_doc |>
add_sparkle(
comment_id = 0,
value = mtcars[1:5,]
)However, sparkle and the polish_content method do not only support
adding R objects but some other file formats as well. In this scenario,
the “value” is the path to the file to be added wrapped in a
as_file() function.
my_doc |>
add_sparkle(
comment_id = 1,
value = as_file(system.file("test_file.txt", package = "sparkle"))
)See the ?polish_content help page for the set of supported objects and file types.
Now that we know how the mechanism works, adding for each comment is
not exactly fast or scaleable. This is where the
add_sparkles_pattern() function comes in. If the user
follows a pattern in both the text content in the document as well as
the comment text, you can write a function to add content quickly and
efficiently.
Rather than identifying the comment via its id, you write out a regular expression to match with the in-document text to identify which comments to add values at, and another function to parse the comment text to figure out what objects to add. For example, in this document, the author has multiple instances of using the word “Insert”, but also a few comments with “{{inline insert}}”, so to identify the first two comments as the locations we want to add content at, we use “^Insert$” regular expression, indicating the comment text must only contain the word “Insert”.
my_doc |>
add_sparkles_pattern(
docx_text_pattern = "^Insert$",
comment_text_func = function(...){
## generate some content
mtcars[sample(seq_len(nrow(mtcars)), 1), , drop = FALSE]
}
)Once the document has had all the content you intend to add, you save
the document. This should be done with the save_docx()
function, which takes the document object and the path to save it
to.