---
title: "Creating a (pre)registration form"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Creating a (pre)registration form}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
systematicReview_exampleForm <-
  get(data(list="form_inclSysRev_v0_92", package='preregr'));
```

To start creating a (pre)registration form, use `preregr::form_create()`. Only the title and the version fields are mandatory, but when the author isn't specified, this is shown as `NA`. When the date is omitted, today's date is inserted. The form is prefilled with one instruction, one section, and one item.

```{r}
formExample <-
  preregr::form_create(
    title = "Minimal form with only a few fields",
    version = "0.0.1",
    author = "Stibbons, P."
  ) |>
  preregr::form_show();
```

To add actual content, use `preregr::form_add_instruction()`, `preregr::form_add_section()`, and `preregr::form_add_item()`. If the default instruction, section, and items still exist, they will be replaced.

```{r}
formExample <-
  formExample |>
  preregr::form_add_instruction(
    heading = "Instructions",
    description = paste0(
      "This form is simple, so it doesn't require much ",
      "instruction. Still, it's advisable to always RTFM, ",
      "and in the case of (pre)registration forms, the ",
      "instructions are the manual. So better read closely!"
    )
  ) |>
  preregr::form_add_section(
    id = "only_section",
    label = "Only Section",
    description = paste0(
      "This is the only section in this form. That's ",
      "because this is such a simple form. However, that ",
      "means this section is very important, because it ",
      "contains all the items. Therefore, you may want to ",
      "study this section description very carefully."
    )
  ) |>
  preregr::form_add_item(
    id = "study_title",
    label = "Study Title",
    section_id = "only_section",
    description = paste0(
      "Think of a catchy title, preferably with a colon in ",
      "the middle. Bonus points for pop culture references."
    )
  ) |>
  preregr::form_add_item(
    id = "registration_type",
    label = "Registration type",
    section_id = "only_section",
    description = paste0(
      "Describe briefly why you are (pre)registering this ",
      "study. For example, this might be a preregistration ",
      "to allow others to know you're doing this study; or to ",
      "make it clear you value transparency in science; or to ",
      "remember your original plans later on. Or this might be ",
      "a registration to update your plans after the data came ",
      "in; or to document pragmatic changes in plans."
    )
  ) |>
  preregr::form_show();

```

It is also possible to insert the form into an R Markdown document using `preregr::form_knit()`:

```{r}
preregr::form_knit(formExample);
```

Alternatively, you can export the form to a local spreadsheet file so you can import it later:

```{r, eval=FALSE}
preregr::form_to_xlsx(
  formExample,
  file = "C:/Data/Research/amazing-new-project/prereg-form.xlsx"
);
```

# A full example

For example, this is a general (pre)registration form for systematic reviews:

```{r}
preregr::form_knit(systematicReview_exampleForm);
```