R/form_to_rmd_template.R
rmd_templates.Rd
This 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(), \"%H:%M:%S on %Y-%m-%d %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 = 1,
showSpecification = FALSE,
preventOverwriting = rock::opts$get("preventOverwriting"),
silent = rock::opts$get("silent")
)
The (pre)registration form (as produced by a call
to preregr::form_create()
or preregr::import_from_html()
) or
initialized preregr
object (as produced by a call to
preregr::prereg_initialize()
or preregr::import_from_html()
); or, for
the printing method, the R Markdown template produced by a call to
preregr::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 preregr::prereg_specify()
as function for
specifying the (pre)registration content (if FALSE
), or
preregr::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.
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 ~~~~-->
#> <!-- 2024-01-21 at 10:05:52 UTC (UTC+0000) ~~~~~~~~~~~~~~~~~~~~~~~~-->
#>
#> ```{r preregr-formSpecification-YWxNDv, echo=FALSE, results='hide'}
#> ```
#>
#> ```{r preregr-setup-hncrUo, 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-BF7QxM, echo=FALSE, results='hide'}
#>
#> ###-------------------------------------------------------------------
#> ### Example Label
#> ###-------------------------------------------------------------------
#>
#> ### Example item description
#>
#> preregrObject <-
#> preregr::prereg_specify(
#> preregrObject,
#> example_item = "Unspecified"
#> );
#>
#> ```
#>
#> ```{r, preregr-show-form-contents-z0h9UK, 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-YWxNDv, 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,
#> "2024-01-21")), 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"))
#>
#> ```