---
title: "Create an R Markdown template from a form"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Create an R Markdown template from a form}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

`preregr` forms can be used to generate R Markdown templates, similar to how the `prereg` package can spawn a number of pre-installed R Markdown templates (see the associated [GitHub repo](https://github.com/crsh/prereg) or the [CRAN page](https://cran.r-project.org/package=prereg) for details).

These templates are basically prestructured R Markdown files. This means the user (i.e. you) will only have to add in the (pre)registration content, knitr it, and you have a human- and machine-readable (pre)registration.

## Generating a full R Markdown template

To generate a full R Markdown template, that can be rendered as a stand-alone document, the `preregr::form_to_rmd_template()` function can be used with its default settings, so you only have to specify the form you want to use (one you created, loaded, imported, or the name of one of the forms that come pre-installed with `preregr`.

```{r, eval=FALSE}
preregr::form_to_rmd_template(
  "OSFprereg_v1",
  file = "C:/Path/To/A/File.Rmd"
);
```

This will write the R Markdown template to that file. To show how it looks, we'll save the contents to an object and show a fragment.

```{r}
rmdTemplate_example <-
  preregr::form_to_rmd_template(
    "OSFprereg_v1"
  );

### Show the fragment
cat(rmdTemplate_example[45:88], sep = "\n");
```

As can be seen above, part of the (pre)registration information is shown as HTML comments (specifically, the general instructions, the section titles, and the section descriptions), and part is shown as R comments (the item titles, and if provided, the item descriptions). This is then followed by the R code to specify the item content, prefilled with the "Unspecified" text.

The R Markdown template also includes the form itself, specified at the end so as not to confuse the user of the template with a lot of complicated R code right at the top. A fragment of the R form:

```{r}
cat(rmdTemplate_example[835:850], sep = "\n");
```

## Writing the R Markdown template to a child document to embed

It is also possible to embed the R Markdown template as a fragment in another R Markdown file. This uses [`knitr`'s Child Document functionality](https://yihui.org/knitr/demo/child/). To do this, write the R Markdown template to a file, but omit the YAML front matter using the `includeYAML` argument (setting it to `FALSE`).

```{r, eval=FALSE}
preregr::form_to_rmd_template(
  "OSFprereg_v1",
  file = "C:/Path/To/Child-document.Rmd",
  includeYAML = FALSE
);
```

Then, in the main R Markdown document where you want to include the child document (i.e. the R Markdown template), include an empty R chunk that sets option `child` to the path to the file you saved the template to. For example, to include the template produced with the call above, we would insert the following chunk:

```{r, echo=FALSE, comment=""}
cat('```{r including-the-child, child = "C:/Path/To/Child-document.Rmd"}\n');
cat('```');
```

You may also want to save a PDF version of the (pre)registration so that it can be uploaded to a (pre)registration server such as the Open Science Framework. To do that, you can use [preregr::prereg_spec_to_pdf()](https://preregr.opens.science/reference/prereg_spec_to_pdf.html). For example, using the [here::here()](https://here.r-lib.org/) function, and assuming the project directory contains a sub-directory called `prereg`, the following chunk could be included after the above chunk in the main R Markdown document that included the R Markdown template (i.e. the chunk shown above):

```{r preregistration-export, echo=FALSE, comment=""}
cat(
  '```{r, preregistration-export}',
  'preregr::prereg_spec_to_pdf(',
  '  preregrObject,',
  '  file = here::here("prereg", "registration-1---preregistration.pdf"),',
  '  author = rmarkdown::metadata$author',
  ');',
  '```',
  sep="\n"
);
```

The last argument, `author = rmarkdown::metadata$author`, inserts the author specified in the main R Markdown document as the preregistration author in the PDF.