---
title: "Fetching Information on Forms"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Fetching Information on Forms}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r}
#| label: setup
#| include: false

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = TRUE,
  error = FALSE,
  fig.path = "static"
)

vcr::setup_knitr(prefix = "forms-")
nettskjemar:::mock_if_no_auth()

```

# Overview

In this vignette, we demonstrate how to interact with the Nettskjema API to perform the following tasks:
1. Retrieve a list of all forms you have access to.
1. Download reports associated with a form.


## Prerequisites

Before you begin, ensure that you have already set up authentication.
If you haven’t, refer to the vignette on [authentication setup](authentication.html).

Additionally, load the required package:

```{r}
#| label: sitrep
#| cassette: true

library(nettskjemar)

ns_sitrep()
```

# Retrieving All Available Forms

To see which forms you have access to, use the `ns_get_forms` function.

## Example: Getting Forms

```{r}
#| label: head
#| cassette: true

# Retrieve all forms
forms <- ns_get_forms()

head(forms)
```

### Retrieving Raw Form Data

If you prefer to get the raw list format as returned by the API, use `asis = TRUE`.

```{r}
#| label: raw
#| cassette: true

# Retrieve raw form data
raw_forms <- ns_get_forms(asis = TRUE)

# Display the raw response
print(raw_forms)
```

# Downloading Form Reports

Each form can have reports such as CSV, Excel, or SPSS files associated with it.
Use the `ns_get_form_reports` function to download these reports.

## Example: Download a CSV Report

```r
#| label: csv

# Define the form ID
form_id <- 110000

# Download a CSV report to the default path
ns_get_form_reports(form_id, type = "csv")

# The report will be saved as `110000.csv` in your working directory
```

## Example: Download an Excel Report

```r
#| label: excel

# Download an Excel report
ns_get_form_reports(form_id, type = "excel")
```

## Example: Save SPSS Report to a Custom Path

```r
#| label: spss

# Specify the path you want to save the file
path <- fs::path_home("Desktop/110000_report.sav")

# Download and save the SPSS report
ns_get_form_reports(form_id, type = "spss", path = path)
```

## Custom Output Paths

For custom output locations, make sure to provide the full file path in the `path` argument.