Get started • odsrmd

library(odsrmd)

library(dplyr)
library(rmarkdown)

This vignette guides you through the procedure to display the content of an Rmarkdown file on a classic page from the Opendatasoft platform. You can either go step by step with separated functions, or, if you prefer a single command line version, directly use update_ods_page().

In both cases, we assume that you have access to an Opendatasoft platform and you have the rights to create and edit a page on the platform. As described in the README, you need to add the following environment variables to your Renviron file: ODS_DOMAIN_ID, ODS_USERNAME and ODS_PASSWORD. The ODS_DOMAIN_ID variable corresponds to the domain ID of your Opendatasoft domain. ODS_USERNAME and ODS_PASSWORD correspond respectively to your username and password to access the platform.
We also assume that you already created an empty classic page, for which the page URL (or page slug) is “odsrmd-example”.

For this vignette, we will take a simple Rmarkdown file, stored as example in the package {odsrmd}. You can prepare your own Rmarkdown file. Note that you can query data from your own Opendatasoft platform using the ODS Explore API version 2. We also provide an example of output from get_ods_page() to test {odsrmd} without credentials.

get_body_and_style

get_body_and_style() renders the Rmarkdown file as an .html file and extracts the html nodes corresponding to the body and the style of the page. Note that you cannot include scripts on a classic page from the Opendatasoft platform. Hence, scripts nodes are removed from the html document by get_body_and_style() and interactive libraries such as {plotly} or {highcharter} don’t work here.

# Temporary directory for reproducible example
dir_tmp <- tempfile(pattern = "proj-")
dir.create(dir_tmp)

file.copy(from = system.file("examples/example_rmd.Rmd", package = "odsrmd"), to = dir_tmp)
file.copy(from = system.file("examples/style.css", package = "odsrmd"), to = dir_tmp)
# browseURL(dir_tmp)
path <- paste0(dir_tmp, "/example_rmd.Rmd")

body_and_style <- get_body_and_style(path, add_extra_css = "no")

get_ods_page

get_ods_page() gets all pre-existing information of the page, such as its title, description, tags and current content. If no other information is provided to create_json(), elements collected by get_ods_page() will be re-used bycreate_json() to create the JSON object that will be sent back on the Opendatasoft platform using the put_ods_page() function.

#' \dontrun{
#' page_slug <- "odsrmd-example" 
#' page_elements <- get_ods_page(page_slug) 
#' }

get_languages

get_languages() retrieves all languages available on an Opendatasoft platform, from the information contained in page_elements, the output from get_ods_page(). You can use it apart to check languages available on your Opendatasoft platform. Otherwise, it is used inside is_available(). Here, we provide an example of page_elements to illustrate the action of get_languages().

# Temporary directory for reproducible example
dir_tmp <- tempfile(pattern = "proj-")
dir.create(dir_tmp)

file.copy(from = system.file("examples/page_elements_example", package = "odsrmd"), to = dir_tmp)
page_elements <- readRDS(paste0(dir_tmp, "/page_elements_example"))

all_languages <- get_languages(page_elements)
#> Languages available on the platform: EN, FR.

is_available

is_available() checks if a given language is available on the ODS platform from the list of languages contained in page_elements, the output from get_ods_page(). You can use it apart to check if a given language is available on your Opendatasoft platform. Otherwise, it is used inside create_json(). Here, we provide an example of page_elements to illustrate the action of is_available().

# Temporary directory for reproducible example
dir_tmp <- tempfile(pattern = "proj-")
dir.create(dir_tmp)

file.copy(from = system.file("examples/page_elements_example", package = "odsrmd"), to = dir_tmp)
page_elements <- readRDS(paste0(dir_tmp, "/page_elements_example"))

is_available("EN", page_elements)

create_json

create_json() combines information coming from the Opendatasoft page (with get_ods_page()) and the Rmarkdown document (with get_body_and_style()) into a JSON object ready to be sent back to the Opendatasoft platform. With the chosen_language parameter, you can decide to update all or only some language versions of the page. Here, we provide an example of output from get_ods_page(), called page_elements, to illustrate the action of create_json().

# Temporary directory for reproducible example
dir_tmp <- tempfile(pattern = "proj-")
dir.create(dir_tmp)

file.copy(from = system.file("examples/example_rmd.Rmd", package = "odsrmd"), to = dir_tmp)
file.copy(from = system.file("examples/style.css", package = "odsrmd"), to=dir_tmp)
# browseURL(dir_tmp)
path <- paste0(dir_tmp, "/example_rmd.Rmd")
body_and_style <- get_body_and_style(path, add_extra_css = "no")

file.copy(from = system.file("examples/page_elements_example", package = "odsrmd"), to = dir_tmp)
page_elements <- readRDS(paste0(dir_tmp, "/page_elements_example"))

json_to_send <- create_json(page_elements, body_and_style,
  chosen_languages = "all",
  title = NULL, description = NULL,
  tags = NULL, restricted = NULL
)
#> Languages available on the platform: EN, FR.
#> Chosen languages: ALL.

put_ods_page

put_ods_page() updates the content of the page on the Opendatasoft platform with a JSON object coming from create_json(). It sends back an HTTP response if the request is successful, otherwise it throws an error.

#' \dontrun{
#' # Temporary directory for reproducible example
#' dir_tmp <- tempfile(pattern = "proj-")
#' dir.create(dir_tmp)
#' 
#' file.copy(from = system.file("examples/example_rmd.Rmd", package = "odsrmd"), to=dir_tmp)
#' file.copy(from = system.file("examples/style.css", package = "odsrmd"), to=dir_tmp)
#' # browseURL(dir_tmp)
#' path <- paste0(dir_tmp, "/example_rmd.Rmd")
#' page_slug <- "odsrmd-example"
#' 
#' body_and_style <- get_body_and_style(path)
#' 
#' page_elements <- get_ods_page(page_slug)
#' 
#' json_to_send <- create_json(page_elements, body_and_style, chosen_languages = c("en", "fr"), 
#'                         title = "English title", description = NULL,  
#'                         tags = NULL, restricted = NULL)
#' 
#' put_ods_page(page_slug, json_to_send)
#' }

update_ods_page

update_ods_page() is an all-in-one function to fill in and update an ODS page with the content of an Rmarkdown file. It combines get_body_and_style(), get_ods_page(), create_json() and put_ods_page() in a single command line.

#' \dontrun{
#' # Temporary directory for reproducible example
#' dir_tmp <- tempfile(pattern = "proj-")
#' dir.create(dir_tmp)
#' 
#' file.copy(from = system.file("examples/example_rmd.Rmd", package = "odsrmd"), to = dir_tmp)
#' file.copy(from = system.file("examples/style.css", package = "odsrmd"), to=dir_tmp)
#' # browseURL(dir_tmp)
#' path <- paste0(dir_tmp, "/example_rmd.Rmd")
#' page_slug <- "odsrmd-example"
#' 
#' update_ods_page(path, page_slug, add_extra_css = "no", chosen_languages = "all", title = NULL,
#'   description = NULL, tags = NULL, restricted = NULL
#' )
#' }