Creating custom RegLogConnector handlers

shiny.reglog package requires user to create dbConnector and mailConnector for the RegLogServer functionality. While creating ShinyApp almost always you want to use one database and one emailing procedure. For all usage beyond RegLogServer defaults, it would be suboptimal to define new connections. That’s why during development I came to the conclusion that these connectors should allow for easy extensions with custom functions.

The scope of this vignette is to describe:

how the RegLogConnectors operate
the default handlers functions
how to write custom handler function

RegLogConnector dataflow

Both dbConnectors (RegLogDBIConnector and RegLogGsheetConnector) and mailConnectors (RegLogEmayiliConnector and RegLogGmailrConnector) inherits from more general class: RegLogConnector. There are three public fields that are key for the whole dataflow:

RegLogConnector$listener() - reactiveVal object that intakes RegLogConnectorMessage object. RegLogConnector listens to any change in the value of this this object and reacts accordingly.
RegLogConnector$handlers - named list of handler functions. For every type of received message there should be a specific function appended there. All of them should return another RegLogConnectorMessage object informing about the result of the function.
RegLogConnector$message() - reactiveVal object containing RegLogConnectorMessage that are returned from handler function.

RegLogConnectorMessage object

RegLogConnector object reacts upon receiving some kind of RegLogConnectorMessage object and responds likewise. Its an S3 class object that contains four fields:

time: timestamp on which the message was generated
type: character string declaring handler function of the RegLogConnector that should be called when object receive message.
data: list of objects, usually some kind of input or output of the handler function
logcontent: character string declaring content that should be saved into RegLogConnector logs.

You can create message freely using function of the same name:

message <- 
  RegLogConnectorMessage(
    type = "test",
    dataframe = mtcars,
    numbers = runif(10, 0, 100),
    logcontent = paste0("I contain data.frame and random numbers"))

str(message)
#> List of 4
#>  $ time      : chr "2022-08-31 18:03:09.523"
#>  $ type      : chr "test"
#>  $ data      :List of 2
#>   ..$ dataframe:'data.frame':    32 obs. of  11 variables:
#>   .. ..$ mpg : num [1:32] 21 21 22.8 21.4 18.7 18.1 14.3 24.4 22.8 19.2 ...
#>   .. ..$ cyl : num [1:32] 6 6 4 6 8 6 8 4 4 6 ...
#>   .. ..$ disp: num [1:32] 160 160 108 258 360 ...
#>   .. ..$ hp  : num [1:32] 110 110 93 110 175 105 245 62 95 123 ...
#>   .. ..$ drat: num [1:32] 3.9 3.9 3.85 3.08 3.15 2.76 3.21 3.69 3.92 3.92 ...
#>   .. ..$ wt  : num [1:32] 2.62 2.88 2.32 3.21 3.44 ...
#>   .. ..$ qsec: num [1:32] 16.5 17 18.6 19.4 17 ...
#>   .. ..$ vs  : num [1:32] 0 0 1 1 0 1 0 1 1 1 ...
#>   .. ..$ am  : num [1:32] 1 1 1 0 0 0 0 0 0 0 ...
#>   .. ..$ gear: num [1:32] 4 4 4 3 3 3 3 4 4 4 ...
#>   .. ..$ carb: num [1:32] 4 4 1 1 2 1 4 2 2 4 ...
#>   ..$ numbers  : num [1:10] 69.827 78.551 68.815 78.962 0.914 ...
#>  $ logcontent: chr "I contain data.frame and random numbers"
#>  - attr(*, "class")= chr "RegLogConnectorMessage"

Default handler functions for dbConnectors

Both RegLogDBIConnector and RegLogGsheetConnector contain the same default handler functions. In this vignette I will focus on the messages that are received by the handler functions and their general usability. To learn about messages produced by these functions, check “RegLogServer object fields and methods” vignette and its “Message” section - as all of these messages are finally exposed in RegLogServer$message() public field.

All of these functions aren’t exported, as they are used only internally. You can read the documentation for them though with usual syntax of ?function in console. Documentation is rendered for information how to react with them by creating RegLogConnectorMessages yourself.

RegLogDBIConnector: DBI_login_handler
RegLogGsheetConnector: gsheet_login_handler

These functions are handling querying the database for the specified by the user of the ShinyApp user ID and password and check if there is a match. Message structure:

login_message <- 
  RegLogConnectorMessage(
    type = "login",
    username = "Whatever",
    password = "&f5*MSYj^niDt=V'3.[dyEX.C/")

str(login_message)
#> List of 4
#>  $ time      : chr "2022-08-31 18:03:09.607"
#>  $ type      : chr "login"
#>  $ data      :List of 2
#>   ..$ username: chr "Whatever"
#>   ..$ password: chr "&f5*MSYj^niDt=V'3.[dyEX.C/"
#>  $ logcontent: NULL
#>  - attr(*, "class")= chr "RegLogConnectorMessage"

Handlers for register type message

RegLogDBIConnector: DBI_register_handler
RegLogGsheetConnector: gsheet_register_handler

These functions are handling querying the database and checking if the specified user ID and email for new user aren’t already existing in the database. If there is no conflicts, it will then hash provided password and input new row. Message structure:

register_message <- 
  RegLogConnectorMessage(
    type = "register",
    username = "IAmNewThere",
    email = "something@new.com",
    password = "veryHardP422w0rd!")

str(register_message)
#> List of 4
#>  $ time      : chr "2022-08-31 18:03:09.681"
#>  $ type      : chr "register"
#>  $ data      :List of 3
#>   ..$ username: chr "IAmNewThere"
#>   ..$ email   : chr "something@new.com"
#>   ..$ password: chr "veryHardP422w0rd!"
#>  $ logcontent: NULL
#>  - attr(*, "class")= chr "RegLogConnectorMessage"

Handlers for credsEdit type message

RegLogDBIConnector: DBI_credsEdit_handler
RegLogGsheetConnector: gsheet_credsEdit_handler

These functions are querying the database to search for the specified account ID and verify password. After confirming user identity, it can update the database row for this user with any or all of: new username, new email and new password. Message structure:

credsEdit_message <- 
  RegLogConnectorMessage(
    type = "credsEdit",
    account_id = 1,
    password = "&f5*MSYj^niDt=V'3.[dyEX.C/",
    new_username = "Whenever",
    new_email = "edited@email.com",
    new_password = "veryHardP422w0rd!")

str(credsEdit_message)
#> List of 4
#>  $ time      : chr "2022-08-31 18:03:09.755"
#>  $ type      : chr "credsEdit"
#>  $ data      :List of 5
#>   ..$ account_id  : num 1
#>   ..$ password    : chr "&f5*MSYj^niDt=V'3.[dyEX.C/"
#>   ..$ new_username: chr "Whenever"
#>   ..$ new_email   : chr "edited@email.com"
#>   ..$ new_password: chr "veryHardP422w0rd!"
#>  $ logcontent: NULL
#>  - attr(*, "class")= chr "RegLogConnectorMessage"

Handlers for resetCode_generate type message

RegLogDBIConnector: DBI_resetPass_generation_handler
RegLogGsheetConnector: gsheet_resetPass_generation_handler

These functions are querying the database to search for the specified username. After confirming that the specified username exists, it generates and inputs reset code that the user can use to generate new password. Message structure:

resetPass_generate_message <- 
  RegLogConnectorMessage(
    type = "resetPass_generate",
    username = "Whatever")

str(resetPass_generate_message)
#> List of 4
#>  $ time      : chr "2022-08-31 18:03:09.831"
#>  $ type      : chr "resetPass_generate"
#>  $ data      :List of 1
#>   ..$ username: chr "Whatever"
#>  $ logcontent: NULL
#>  - attr(*, "class")= chr "RegLogConnectorMessage"

Handlers for resetCode_confirm type message

RegLogDBIConnector: DBI_resetPass_confirmation_handler
RegLogGsheetConnector: gsheet_resetPass_confirmation_handler

These functions are querying the database to search for the specified username and confirming that provided reset code is correct. After confirmation, it marks the reset code as used and updates password for the user. Message structure:

resetPass_confirm_message <-
  RegLogConnectorMessage(
    type = "resetPass_confirm",
    username = "Whatever",
    reset_code = "4265417643",
    password = "veryHardP422w0rd!")

str(resetPass_confirm_message)
#> List of 4
#>  $ time      : chr "2022-08-31 18:03:09.905"
#>  $ type      : chr "resetPass_confirm"
#>  $ data      :List of 3
#>   ..$ username  : chr "Whatever"
#>   ..$ reset_code: chr "4265417643"
#>   ..$ password  : chr "veryHardP422w0rd!"
#>  $ logcontent: NULL
#>  - attr(*, "class")= chr "RegLogConnectorMessage"

Default handler function for mailConnectors

All default handlers for mailConnectors use the same handler functions:

RegLogEmayiliConnector: emayili_reglog_mail_handler
RegLogGmailrConnector: gmailr_reglog_mail_handler

They send the email to the specified address using subject and html body of the email kept in the mailConnector$mails[[message_type]] list. They also replace all of occurences of ?username?, ?email?, ?app_name?, ?app_address? and ?reset_code? with respective values received in the RegLogConnectorMessage.

Mail creation is chosen from the mailConnector$mails public field on the basis of the process RegLogConnectorMessage value.

resetPass_mail_message <- 
  RegLogConnectorMessage(
    type = "reglog_mail",
    process = "resetPass",
    username = "Whatever",
    email = "edited@email.com",
    app_name = "RegLog Nice ShinyApp",
    app_address = "https://reglog.nice.com",
    reset_code = "4265417643")

str(resetPass_mail_message)
#> List of 4
#>  $ time      : chr "2022-08-31 18:03:09.984"
#>  $ type      : chr "reglog_mail"
#>  $ data      :List of 6
#>   ..$ process    : chr "resetPass"
#>   ..$ username   : chr "Whatever"
#>   ..$ email      : chr "edited@email.com"
#>   ..$ app_name   : chr "RegLog Nice ShinyApp"
#>   ..$ app_address: chr "https://reglog.nice.com"
#>   ..$ reset_code : chr "4265417643"
#>  $ logcontent: NULL
#>  - attr(*, "class")= chr "RegLogConnectorMessage"

There are also provided handlers to send custom e-mails to the logged user.

RegLogEmayiliConnector: emayili_custom_mail_handler
RegLogGmailrConnector: gmailr_custom_mail_handler

They are sending email to the specified address parsing it from provided inside the message subject and body, providing also an option to send an attachment. No additional parsing is done there and process value there is only informative - it is saved into logs and presented in the RegLogServer$mail_message() field.

message_to_send <- RegLogConnectorMessage(
    type = "custom_mail",
    process = "attachment_mail",
    username = "Whatever",
    email = "edited@email.com",
    mail_subject = "Custom message with attachement",
    mail_body = "<p>This is a custom message send from my App</p>
                 <p>It is completely optional, but that kind of message can also
                    contain an attachment!</p>",
    mail_attachement = "files/myplot.png"
  )

How to create custom handler function

Handler function system of dbConnectors and mailConnectors allows for creating custom logic for communicating with them.

For example purposes the custom action that will be described in this vignette will be the process of saving and reading from googlesheet based database results of simple, 10-item questionnaire: Rosenberg’s Self-esteem scale.

Setup the grounds to store the data

Firstly, we need to create another sheet in the googlesheet that is used by the RegLogGsheetConnector to store our data. Besides the summed score we will also need timestamp and username to read the most recent row for the currently logged user.

# create new sheet to the googlesheet
googlesheets4::write_sheet(
  ss = gsheet_ss,
  sheet = "SES_results",
  # append 0-row data.frame to create the "schema" for the sheet
  data = data.frame(timestamp = as.character(NA),
                    user_id = as.character(NA),
                    score = as.numeric(NA))[-1,]
)

Create a handler for writing to database

All handler functions need to take as arguments objects self, private and message and return RegLogConnectorMessage.

write_SES_handler <- function(self, private, message) {
  
  googlesheets4::sheet_append(
    # ID of the connected googlesheet is stored inside private of the
    # RegLogGsheetConnector
    ss = private$gsheet_ss,
    sheet = "SES_results",
    data = data.frame(
      # db_timestamp creates nicely formatted and interpretable by most
      # databases current time
      timestamp = db_timestamp(),
      # user ID and score should be received inside received message
      user_id = message$data$user_id,
      score = message$data$score
      ))
  
  return(RegLogConnectorMessage(type = "write_SES",
                                success = TRUE))
  
}

Create a handler for reading from database

As we have now the writing handler ready, we should create a handler to retrieve the data in another user session.

read_SES_handler <- function(self, private, message) {
  
  # read all results
  SES_results <- googlesheets4::read_sheet(
    ss = private$gsheet_ss,
    sheet = "SES_results",
    col_types = "ccn")
  
  # get the lastest result for the current user
  SES_results <- SES_results |>
    dplyr::filter(user_id == message$data$user_id) |>
    dplyr::arrange(dplyr::desc(timestamp)) |>
    dplyr::slice_head()
  
  # return the RegLogConnectorMessage with the score if available
  if (nrow(SES_results) == 1) {
    return(RegLogConnectorMessage(type = "read_SES",
                                  success = TRUE,
                                  score = SES_results$score))
  } else {
    return(RegLogConnectorMessage(type = "read_SES",
                                  success = FALSE))
  }
}

Have everything in motion

I will present there only code for the server logic, containing all needed elements for appending created custom handlers and sending the RegLogConnectorMessages to both write and read data from new sheet.

# create and assign RegLogServer object
RegLog <- RegLogServer$new(
  # create googlesheet connector
  dbConector = RegLogGsheetConnector$new(
    # provide correct googlesheet ID
    gsheet_ss = gsheet_ss,
    # provide handlers in a named list. Names will be used to choose on basis
    # of received RegLogConnectorMessage which function to use
    custom_handlers = list(write_SES = write_SES_handler,
                           read_SES = read_SES_handler)
  ),
  # provide some mailConnector with all needed data
  mailConnector = mailConnector
)

# create an event to write the data to the database: there actionButton will
# trigger it
observeEvent(input$write_ses_result, {
  
  # make sure the inputs are provided
  req(input$SES_1, input$SES_2, input$SES_3, input$SES_4, input$SES_5,
      input$SES_6, input$SES_7, input$SES_8, input$SES_9, input$SES_10)
  
  # get the score by summing all raw scores of items
  score <- sum(input$SES_1, input$SES_2, input$SES_3, input$SES_4, input$SES_5,
               input$SES_6, input$SES_7, input$SES_8, input$SES_9, input$SES_10)
  
  # send message to the dbConnector's listener
  RegLog$dbConnector$listener(
    RegLogConnectorMessage(
      # specify correct type - the same as the name of the handler
      type = "write_SES",
      # get required user ID from the RegLog object
      user_id = RegLog$user_id(),
      score = score))
})

# create an event to read the data from the database: eg. another actionButton
observeEvent(input$read_last_ses_result, {
  
  # send correct message to the dbConnector's listener
  RegLog$dbConnector$listener(
    RegLogConnectorMessage(
      type = "read_SES",
      user_id = RegLog$user_id())
  )
})

# assign the retrieved data: eg. to the reactive

SES_result <- reactive(
  # retrieved data will be available in `message()` field of RegLog object
  received_message <- RegLog$message()
  # make sure to only process correct type of message
  req(received_message$type == "read_SES")

  if (!is.null(score)) {
    # get the score if there was any saved in the database
    received_message$data$score
  })