Tutorial document_create_from

Before you start

In this tutorial, we describe how to create an Rspace structured document from a Quarto file. We advice you to read the rspacer Get started website on https://burgerga.github.io/rspacer/index.html to make sure that you are ready to use this upload document. You need to install rspacer and set up your API url and API key before the start of this tutorial.

1. Load R libraries

library(tidyverse)
library(here)
library(rspacer)

2. Check if the API is available

This code checks if the API is available. The API status should be OK.

(res <- api_status())

## $message
## [1] "OK"
## 
## $rspaceVersion
## [1] "1.103.1"

stopifnot(res$message == "OK")

3. Create a structured document in Rspace

Create a Template from a Form with four text Fields named “Title”, “Date”, “Main part” and “Conclusion”. Write down the unique Structured Document identifier, you will need it later. Instructions to design a Template in Rspace can be found here: https://documentation.researchspace.com/article/wxfk9gf0a0-templates.

4. Create a small example document

The rspacer package has an example file. In RStudio, go to File > New File > R Markdown. At the moment (28-10-2024) there is not yet an option to create Quarto files from template, which is why we chose to provide the file as an R Markdown template.
On the left, click From Template.
Choose the rspacer Template example. Save the file as a Quarto file (.qmd).
Render the file to a html report.

Alternatively, you can create a new Quarto document. Include the same headers as the Rspace Template that you previously created in Step 3, and make sure that these headers all have two hashtags (h2 headers, with ##). You can write any code, or use h3 or h4 headers (with three or four hashtags), as long the h2 headers are identical to your structured document template.

Specify the file name of the file to upload

Rspacer needs to know which file you want to upload. In this tutorial, we want to create a structured document from the file “Template_example.html” that we made in Step 4, and we want to upload the .qmd file as an attachment. We recommend to work with relative paths from within an R project and specify these paths using the here package. If this is not what you want, you need to specify the absolute file path. The code below assumes that the html file and qmd file have the same filename. If this is not the case, change both the file_name and the matching_code_file variables.

(file_name <- here("man/example/Template_example.html"))

## [1] "C:/Users/hanneke/Documents/rspacer/man/example/Template_example.html"

(matching_code_file <- str_replace(file_name, ".html$", ".qmd"))

## [1] "C:/Users/hanneke/Documents/rspacer/man/example/Template_example.qmd"

stopifnot(file.exists(file_name))
stopifnot(file.exists(matching_code_file))

Specify the template and folder to upload to

You can ‘walk’ through folders until you find the folder or notebook where you want to upload the Structured Document, using the folder_tree() function in rspacer. If you want to replace a file, also define the existing file id. If you have a more complicated document than a Basic Document, you have to specify the identifier of the Template as well. Folder identifiers start with FL. Notebook identifiers start with NB. Structured document identifiers start with SD.

folder_tree()

## # A tibble: 8 × 9
##       id globalId name                      created                  lastModified        parentFolderId type  `_links` owner       
##    <int> <chr>    <chr>                     <chr>                    <chr>                        <int> <chr> <list>   <list>      
## 1 368771 FL368771 i001_PhD_Hanneke          2024-04-12T11:37:28.954Z 2024-04-12T11:37:2…           2790 FOLD… <list>   <named list>
## 2 366764 FL366764 Api Inbox                 2024-03-28T11:18:35.212Z 2024-03-28T11:18:3…           2790 FOLD… <list>   <named list>
## 3 239405 FL239405 Ontologies                2023-04-17T12:54:17.626Z 2023-04-17T12:54:1…           2790 FOLD… <list>   <named list>
## 5  14411 FL14411  Testing_Rspace            2023-01-12T21:07:31.965Z 2023-01-12T21:07:3…           2790 FOLD… <list>   <named list>
## 6   2810 FL2810   Templates                 2022-12-22T12:19:03.336Z 2022-12-22T12:19:0…           2790 FOLD… <list>   <named list>
## 7   2796 GF2796   Gallery                   2022-12-22T12:19:03.285Z 2022-12-22T12:19:0…           2790 FOLD… <list>   <named list>
## 8   2791 FL2791   Shared                    2022-12-22T12:19:03.267Z 2022-12-22T12:19:0…           2790 FOLD… <list>   <named list>

#folder_tree("") # Specify folder ID in brackets to keep walking.

folder_id <- "" # Specify folder ID for upload
template_id <- "" # SD identifier of the template
field_nr_for_code <- 0 # Specify the field in which the code file needs to be attached.
existing_file_id <- "" # Optional, used if one wants to replace a file. Leave empty string if no file needs to be created.

tags <- c("") # You can add multiple tags in a vector. For example a grant number, or "finished" or "in progress" or "failed".

Upload the file

Create an RSpace document using the code chunk below. It creates a document from your Template_example.html rendered file, and places the .qmd with the same name in the fourth field of the structured document. If no folder_id is specified, the function document_create_from_html() creates the document in the ‘API Inbox’. Optionally, you can add tags or replace an entire document. Make sure that the template_id is the identifier of the template that you previously made in Rspace. To upload the document and attachment to the API inbox, this code chunk is sufficient:

document_create_from_html(
    path = file_name,
    template_id = "SD377682"
)

## Document created: <https://leiden.researchspace.com/globalId/SD389616>

The function document_create_from_html has more parameters, for example to upload the document to the specified notebook or folder. If you want to upload a code file as well, it will be added in the number of the field as an attachment. Use the existing_file_id only if a file needs to be replaced instead of created.

if(existing_file_id == ""){
  document_create_from_html(
    path = file_name,
    template_id = template_id,
    folder_id = folder_id,
    tags = tags,
    attachment = list(field = field_nr_for_code, path = matching_code_file)
  )
} else {
  document_create_from_html(
    path = file_name,
    template_id = template_id,
    folder_id = folder_id,
    tags = tags,
    attachment = list(field = field_nr_for_code, path = matching_code_file),
    existing_file_id  = existing_file_id
  )
}

Session info

sessionInfo()

## R version 4.3.0 (2023-04-21 ucrt)
## Platform: x86_64-w64-mingw32/x64 (64-bit)
## Running under: Windows 11 x64 (build 22631)
## 
## Matrix products: default
## 
## 
## locale:
## [1] LC_COLLATE=Dutch_Netherlands.utf8  LC_CTYPE=Dutch_Netherlands.utf8    LC_MONETARY=Dutch_Netherlands.utf8
## [4] LC_NUMERIC=C                       LC_TIME=Dutch_Netherlands.utf8    
## 
## time zone: Europe/Amsterdam
## tzcode source: internal
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
##  [1] lubridate_1.9.2    forcats_1.0.0      stringr_1.5.0      dplyr_1.1.2        purrr_1.0.1        readr_2.1.4       
##  [7] tidyr_1.3.0        tibble_3.2.1       ggplot2_3.4.2      tidyverse_2.0.0    here_1.0.1         rspacer_0.1.0.9001
## 
## loaded via a namespace (and not attached):
##  [1] jsonlite_1.8.4   gtable_0.3.3     compiler_4.3.0   tidyselect_1.2.0 xml2_1.3.3       scales_1.2.1     yaml_2.3.7      
##  [8] fastmap_1.1.1    R6_2.5.1         generics_0.1.3   curl_5.2.3       httr2_1.0.5      knitr_1.42       munsell_0.5.0   
## [15] rprojroot_2.0.3  pillar_1.9.0     tzdb_0.3.0       rlang_1.1.0      utf8_1.2.3       stringi_1.7.12   xfun_0.39       
## [22] timechange_0.2.0 cli_3.6.1        withr_2.5.0      magrittr_2.0.3   rvest_1.0.3      digest_0.6.31    grid_4.3.0      
## [29] rstudioapi_0.14  rappdirs_0.3.3   hms_1.1.3        lifecycle_1.0.3  vctrs_0.6.5      evaluate_0.20    glue_1.6.2      
## [36] fansi_1.0.4      colorspace_2.1-0 httr_1.4.5       rmarkdown_2.21   tools_4.3.0      pkgconfig_2.0.3  htmltools_0.5.5

Tutorial document_create_from_html()