R/form_to_rmd_template.R
rmd_templates.RdThis function creates an R Markdown template from a preregr (pre)registrations form specification. Pass it the URL to a Google Sheet holding the (pre)registration form specification (in preregr format), see the "Creating a form from a spreadsheet" vignette), the path to a file with a spreadsheet holding such a specification, or a loaded or imported preregr (pre)registration form.
form_to_rmd_template(
x,
file = NULL,
title = NULL,
author = NULL,
date = "`r format(Sys.time(), '%Y-%m-%d at %H:%M:%S %Z (UTC%z)')`",
output = "html_document",
yaml = list(title = title, author = author, date = date, output = output),
includeYAML = TRUE,
chunkOpts = "echo=FALSE, results='hide'",
justify = FALSE,
headingLevel = 2,
showSpecification = FALSE,
preventOverwriting = preregr::opts$get("preventOverwriting"),
silent = preregr::opts$get("silent")
)
# S3 method for preregr_rmd_template
print(x, ...)The (pre)registration form (as produced by a call
to form_create() or import_from_html()) or
initialized preregr object (as produced by a call to
prereg_initialize() or import_from_html()); or, for
the printing method, the R Markdown template produced by a call to
form_to_rmd_template().
Optionally, a file to save the html to.
The title to specify in the template's YAML front matter.
The author to specify in the template's YAML front matter.
The date to specify in the template's YAML front matter.
The output format to specify in the template's YAML front matter.
It is also possible to specify the YAML front matter directly
using this argument. If used, it overrides anything specified in title,
author, date and output.
Whether to include the YAML front matter or omit it.
The chunk options to set for the chunks in the template.
Whether to use prereg_specify() as function for
specifying the (pre)registration content (if FALSE), or
prereg_justify() (if TRUE).
The level of the top-most heading to use (the title of the (pre)registration form).
Whether to show the specification in the Rmd
output. When FALSE, the preregr option silent is set to TRUE at
the start of the Rmd template; otherwise, it is set to FALSE.
Set to FALSE to override overwrite prevention.
Whether to be silent or chatty.
Additional argument are ignored.
x, invisibly
preregr::form_create(
title = "Example form",
version = "0.1.0"
) |>
preregr::form_to_rmd_template();
#> ---
#> title: Example form
#> author: Specify author here
#> date: '`r format(Sys.time(), ''%Y-%m-%d at %H:%M:%S %Z (UTC%z)'')`'
#> output: html_document
#>
#> ---
#>
#> <!-- This preregistration template was written by `preregr` at ~~~~-->
#> <!-- 2023-05-04 at 19:32:17 CEST (UTC+0200) ~~~~~~~~~~~~~~~~~~~~~~~-->
#>
#> ```{r preregr-formSpecification-GYvxsi, echo=FALSE, results='hide'}
#> ```
#>
#> ```{r preregr-setup-DMZyFK, echo=FALSE, results='hide'}
#>
#> ###-------------------------------------------------------------------
#> ### Setup
#> ###-------------------------------------------------------------------
#>
#> preregr::opts$set(silent = TRUE);
#>
#> preregrObject <-
#> preregr::prereg_initialize(preregrFormSpec);
#>
#> ```
#>
#> <!------------------------------------------------------------------->
#> <!-------- GENERAL (PRE)REGISTRATION FORM INSTRUCTIONS -------->
#> <!------------------------------------------------------------------->
#>
#>
#> <!-- First instruction ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
#>
#> <!-- Actual instructions -->
#>
#>
#> <!-- Example Section ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~-->
#>
#> ```{r preregr-example_section-example_item-Kz56a4, echo=FALSE, results='hide'}
#>
#> ###-------------------------------------------------------------------
#> ### Example Label
#> ###-------------------------------------------------------------------
#>
#> ### Example item description
#>
#> preregrObject <-
#> preregr::prereg_specify(
#> preregrObject,
#> example_item = "Unspecified"
#> );
#>
#> ```
#>
#> ```{r, preregr-show-form-contents-PLZAY0, echo=FALSE}
#> preregr::prereg_knit_item_content(
#> preregrObject,
#> headingLevel = 2
#> );
#> ```
#>
#>
#> <!-- Here, the form specification is included. ~~~~~~~~~~~~~~~~~~~~-->
#> <!-- This chunk is executed earlier on though. ~~~~~~~~~~~~~~~~~~~~-->
#>
#> ```{r preregr-formSpecification-GYvxsi, echo=FALSE, eval=FALSE}
#>
#> preregrFormSpec <-
#> structure(list(instructions = structure(list(heading = "First instruction",
#> description = "Actual instructions"), class = "data.frame", row.names = c(NA,
#> -1L)), metadata = structure(list(field = c("title", "version",
#> "author", "date"), contents = c("Example form", "0.1.0", NA,
#> "2023-05-04")), class = "data.frame", row.names = c(NA, -4L)),
#> items = structure(list(section_id = "example_section", item_id = "example_item",
#> item_label = "Example Label", item_description = "Example item description",
#> item_valueTemplate = "string", item_validValues = NA,
#> item_validation = NA), class = "data.frame", row.names = c(NA,
#> -1L)), sections = structure(list(section_id = "example_section",
#> section_label = "Example Section", section_description = "Example section description"), class = "data.frame", row.names = c(NA,
#> -1L)), valueTemplates = structure(list(identifier = c("numeric",
#> "integer", "string", "categorical"), description = c("Any valid number",
#> "Any valid whole number", "A single character value", "A string that has to exactly match one of the values specified in the 'items_validValues' column of the items sheet"
#> ), validValues = c(NA, NA, NA, NA), default = c(NA, NA, NA,
#> NA), examples = c("2.3 || 643.2", "30 || 8762", "'Example' || 'Another example'",
#> "VALIDVALUES"), validation = c("is.na(VALUE) || (is.numeric(VALUE) && (length(VALUE) == 1))",
#> "is.na(VALUE) || (is.numeric(VALUE) && (VALUE%%1==0) && (length(VALUE) == 1))",
#> "is.na(VALUE) || (is.character(VALUE) && length(VALUE) == 1)",
#> "is.na(VALUE) || (VALUE %in% VALIDVALUES)"), error = c("NAME is not numeric, or contains more than one value.",
#> "NAME is not numeric, contains more than one value, or contains decimals.",
#> "NAME is not a single text string.", "NAME is not one of VALIDVALUES."
#> )), class = "data.frame", row.names = c(NA, -4L))), class = c("preregr",
#> "preregr_form", "list"))
#>
#> ```