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")
)

Arguments

x

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().

file

Optionally, a file to save the html to.

title

The title to specify in the template's YAML front matter.

author

The author to specify in the template's YAML front matter.

date

The date to specify in the template's YAML front matter.

output

The output format to specify in the template's YAML front matter.

yaml

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.

includeYAML

Whether to include the YAML front matter or omit it.

chunkOpts

The chunk options to set for the chunks in the template.

justify

Whether to use preregr::prereg_specify() as function for specifying the (pre)registration content (if FALSE), or preregr::prereg_justify() (if TRUE).

headingLevel

The level of the top-most heading to use (the title of the (pre)registration form).

showSpecification

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.

preventOverwriting

Set to FALSE to override overwrite prevention.

silent

Whether to be silent or chatty.

Value

x, invisibly

Examples

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"))
#> 
#> ```