Support a New Relational Database Management System

Database Modules

ReviewR facilitates these DBI connections through the use of Shiny Modules. Modules can make complex Shiny applications more manageable. They compartmentalize code and are developed for a specific purpose.

At their core, modules monitor user inputs that are defined in a User Interface (UI) function, process these inputs in a server function, and return an output. Each module operates in its own namespace, meaning that Shiny modules are portable and can be used in other applications or reused within the same application.

In ReviewR, this concept is used to create “database modules.” Each patient database back-end will have different connection requirements, meaning a new UI is needed to collect the required connection information from the user. By modularizing this connection code, ReviewR can support multiple databases so long as a correctly formatted DBI connection object is returned to the ReviewR application. Thus “database modules” are Shiny modules that are responsible for collecting appropriate database credentials (IP address, port, etc.) and returning a DBI connection object.

ReviewR dynamically switches between developed database modules with its own database setup module. This setup module allows users to interactively switch between database modules that have been developed. When selected, each individual module’s UI will be presented to guide the user through establishing a database connection.

Users can extend the functionality of ReviewR by adding developed database modules to the “Database Module Setup” code chunk within R/mod_database_setup.R as shown below:

# Database Module Setup ----
      namespace <- 'db-selector-ns'
      # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Add Database Setup Modules Here!!! ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ #
      ## Add Database Setup Modules Here
      database_setup_vars <- reactiveValues(bigquery = bigquery_setup_server(id = namespace ),
                                            postgresql = postgresql_setup_server(id = namespace ) #,
                                            # new_module = new_module_setup_server(id = namespace)
                                            )
      # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ #

Once modules are added to the database setup, they will appear in the Patient Database Module drop down on the setup tab.

Read on to learn how to develop a database module for ReviewR!

Getting Started

The first step to developing a new ReviewR module will be to fork the latest version of ReviewR from GitHub. Forking the repository will allow you to experiment with the ReviewR package and ensures you have access to the latest development tools and file structure of the ReviewR package. For simplicity, the home directory is specified as a destination directory:

# install.packages('usethis')
usethis::create_from_github(repo_spec = 'thewileylab/ReviewR', destdir = '~/')

Please see this guide if you have trouble connecting RStudio with Git. It is also possible to fork this repository directly from GitHub if all else fails.

Navigate to the forked repository and open the ReviewR.Rproj file. This will open the project in RStudio. Finally, using the devtools package run:

# install.packages('devtools')
devtools::load_all()

This will load the most recent version of ReviewR. At this point, you are ready to begin developing a database module.

Start Developing!

A helper function, dev_database_module(), has been provided with ReviewR to help jump start the database module development process. This function accepts 2 arguments:

• mod_name - This is an internal variable that ReviewR uses to keep track of the return values from the module, including the DBI connection object.
• display_name - This variable will be the “choice” that is presented to users on the Setup tab, so be sure it is descriptive and recognizable!

When ready, run:

ReviewR:::dev_database_module(mod_name = 'your_module', display_name = 'Your Module Display Name')

This will create a module file in the R/ directory of the ReviewR package and open it for editing.

General Module Structure

Take note of the ReviewR Database Module Template. It consists of 2 functions:

• {mod_name}_setup_ui - Defines the user interface that will guide someone through the database connection process
• {mod_name}_setup_server - Defines what actions to take as a result of user inputs.

ReviewR utilizes the moduleServer() function introduced in Shiny 1.5. This allows the server portion of a module to be called within your application just like any other function, instead of relying on the previous callModule() syntax.

The next thing to note is that ReviewR modules will ultimately become a part of the ReviewR package namespace. This means that both the UI and Server functions require roxygen comments, with all function parameters, returns, and necessary package imports declared.

For additional information on module development, please see: https://shiny.posit.co/r/articles/improve/modules/

Requirements

• a UI function defined as {module_name}_setup_ui that accepts a single parameter (id)
• a server function defined as {module_name}_setup_server with a reactiveValues() return
  • reactiveValues must contain the following variables, with these initial values set:
    • moduleName = ‘{Your Database Module Name}’
    • moduleType = ‘database’
    • setup_ui = ReviewR::{module_name}_setup_ui
    • is_connected = ‘no’
    • db_con = NULL

tagList(
  actionButton(inputId = ns('connect'),label = 'connect'),
  actionButton(inputId = ns('disconnect'),label = 'disconnect')
  )

library(shiny)
## Observe a connect button, defined in the UI function
observeEvent(input$connect, {
  ## When the button is pressed, store a temporary connection
  temp_con <- DBI::dbConnect(drv = database_driver(),
                             user = input$username, ## A text input, with a username
                             pass = input$password ## A password input
                             )
  ## Design a test to validate the temporary connection object
  test_result <- connection_test(temp_con)
  
  ## If the test passes, update the reactiveValues objects for the `is_connected` and `db_con` variables
  if(test_result == TRUE) {
    database_export$is_connected <- 'yes'
    database_export$db_con <- temp_con
    ## Else, don't create connection info
  } else {
    database_export$is_connected <- 'no'
  }
})
## Let ReviewR handle the rest!

## Observe a connect button, defined in the UI function
observeEvent(input$disconnect, (
  ## Tell the database you are disconnecting
  DBI::dbDisconnect(database_export$db_con)
  ## Clear the connection info
  database_export$db_con <- NULL
  ## Set `is_connected` variable back to 'no'
  database_export$is_connected <- 'no'
))

golem::document_and_reload()

Finishing up

Once you are satisfied with your module and have sufficiently tested its functionality, run:

devtools::install()

This will install a new, custom version of the ReviewR package with your newly developed module incorporated.

ReviewR Database Module Template

# UI ----
#' {display_name} Setup UI
#'
#' This module is designed to guide a user through the process of authenticating your database
#' 
#' @param id The module namespace
#' 
#' @return The {display_name} Setup UI
#' 
#' @importFrom shiny NS
#'
{mod_name}_setup_ui <- function(id) { 
  ns <- NS(id)
  tagList(
  ## UI widgets here ----
    
    )
  }

# Server ----
#' {display_name} Setup Server
#'
#' @param id The Module namespace
#'
#' @return {display_name} connection variables
#' @export
#'
#' @importFrom DBI dbConnect
#' 
{mod_name}_setup_server <- function(id) {
  moduleServer(
    id,
    function(input, output, session) {
      ns <- session$ns
      ## {mod_name} Export Values ----
      {mod_name}_export <- reactiveValues(
        ### Module Info
        moduleName = '{display_name}',
        moduleType = 'database',
        setup_ui = ReviewR::{mod_name}_setup_ui,
        is_connected = 'no',       
        db_con = NULL
        )
      # Server Code Here ----
      
      
      # Return ----
      return({mod_name}_export)
    }
  )
}