Tutorial: creating a document from html
Source:vignettes/articles/create_document_from_html.Rmd
create_document_from_html.RmdBefore you start
In this tutorial, we describe how to create an RSpace structured
document from a Quarto file using
document_create_from_html(). We advice you to read
vignette("rspacer") 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.
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.107.1"
stopifnot(res$message == "OK")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.
Create a small example document
- The rspacer package has an example file. In RStudio, go to File > New File > R Markdown. At the moment (2025-02-06) 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, 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 created before, and we want
to upload the .qmd file as an attachment. We recommend to
work with relative paths from within an R project (you can specify these
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 <- system.file("Template_example.html", package = "rspacer"))## [1] "/Users/gerhard/GitHub/rspacer/inst/Template_example.html"
(matching_code_file <- fs::path_ext_set(file_name, ".qmd"))## /Users/gerhard/GitHub/rspacer/inst/Template_example.qmd
stopifnot(file.exists(file_name))
stopifnot(file.exists(matching_code_file))Upload the file
To upload the document and attachment to the API inbox, this code chunk is sufficient:
document_create_from_html(
path = file_name,
template_id = template_id
)## Document created: <https://leiden.researchspace.com/globalId/SD402050>However, document_create_from_html() has more
parameters, in case you want to, for example, upload the file to a
specific folder or replace an existing document (click the function
above to learn more).
How to find the values for these parameters? Browse your RSpace
folders using folder_tree() and use either the
id or the globalID. Folder identifiers start
with FL, notebook identifiers start with NB,
structured document identifiers start with SD. For
example:
## # A tibble: 10 × 9
## id globalId name created lastModified parentFolderId type `_links` owner
## <int> <chr> <chr> <chr> <chr> <int> <chr> <list> <list>
## 1 356307 SD356307 Gerhard Burger 2024-01-17T14:5… 2024-01-17T… 7813 DOCU… <list> <named list>
## 2 260004 FL260004 LACDR RDM 2023-11-06T10:1… 2023-11-06T… 7813 FOLD… <list> <named list>
## 3 242175 FL242175 GABi001_EMP_regulation 2023-05-30T10:1… 2023-06-14T… 7813 FOLD… <list> <named list>
## 4 242400 FL242400 Ontologies 2023-06-01T07:2… 2023-06-01T… 7813 FOLD… <list> <named list>
## 5 242398 FL242398 Api Inbox 2023-06-01T07:2… 2023-06-01T… 7813 FOLD… <list> <named list>
## 6 242182 FL242182 Publications 2023-05-30T11:0… 2023-05-30T… 7813 FOLD… <list> <named list>
## 7 21961 FL21961 DDS2 Data management 2023-03-16T09:5… 2023-03-16T… 7813 FOLD… <list> <named list>
## 8 7833 FL7833 Templates 2022-12-22T12:3… 2022-12-22T… 7813 FOLD… <list> <named list>
## 9 7819 GF7819 Gallery 2022-12-22T12:3… 2022-12-22T… 7813 FOLD… <list> <named list>
## 10 7814 FL7814 Shared 2022-12-22T12:3… 2022-12-22T… 7813 FOLD… <list> <named list>
folder_tree("FL7833")## # A tibble: 6 × 9
## id globalId name created lastModified parentFolderId type `_links` owner
## <int> <chr> <chr> <chr> <chr> <int> <chr> <list> <list>
## 1 242238 SD242238 LACDR-ISA - Contact v0.2.0 2023-0… 2023-11-06T… 7833 DOCU… <list> <named list>
## 2 242213 SD242213 LACDR-ISA - Publication v0.1.0 2023-0… 2023-11-06T… 7833 DOCU… <list> <named list>
## 3 260025 SD260025 LACDR-ISA - Assay (General) v1.… 2023-1… 2023-11-06T… 7833 DOCU… <list> <named list>
## 4 260008 SD260008 LACDR-ISA - Study v1.0.0 2023-1… 2023-11-06T… 7833 DOCU… <list> <named list>
## 5 260005 SD260005 LACDR-ISA - Investigation v1.0.0 2023-1… 2023-11-06T… 7833 DOCU… <list> <named list>
## 6 242170 SD242170 DDS Beltman - In Silico Assay v… 2023-0… 2023-05-30T… 7833 DOCU… <list> <named list>Of course you can also find these by going to the web interface of
your RSpace instance. You can also tag your documents using a
tags vector, for example a status like “finished” or “in
progress” or “failed”. Finally, you can upload attachments, these need
to be specified using list of lists, with the field number and the path
of the file that needs to be attached to that field. An example where we
also upload the source .qmd file is provided below.
document_create_from_html(
path = file_name,
template_id = "SD377682",
folder_id = "FL242398",
tags = c("tutorial"),
attachments = tibble(field = 3, path = matching_code_file),
existing_document_id = NULL
)## File uploaded to <https://leiden.researchspace.com/globalId/GL402052>
## Document created: <https://leiden.researchspace.com/globalId/SD402053>