Introduction

This vignette will provide an overview of the formods framework for creating reproducable modules that interact with each other. Each module has its own namespace that is mantained by using a module short name as a prefix for functions. For example the figure generation module uses FG. If you want to create a module, please submit an issue at the formods github repository with the following information:

• The short name you intend to use
• A brief description of the module
• A list of modules it depends on

formods framework

To get started you need to create some template files. The example below assumes you are creating this module for a package called mypackage and that you are running this command in a git repository. Say that this module is used to produce widgets, the short name is MM which stands for My Module:

use_formods(SN          = "MM",
            Module_Name = "My Module",
            element     = "widgets", 
            package     = "mypackage")

• MM_module_components.R - An app that can be used for testing the module and highlighting the different UI elements that are used within the module (found in inst/templates).
• MM_Server.R: A bare bones file containing the expected functions and their minimal inputs. (found in R).
• MM.yaml: This module configuration file contains the the minimal elements expected, but you can add your own fields to suit your modules needs (found in inst/templates).
• MM_funcs.R: This script contains example code for the different elements of the module that can be used in the function examples and also to quickly test the different module functions while you develop them (found in inst/test_apps).

Expected functions

The module template will create a standard set of functions for you. The MM below will be replaced with whatever short name you choose above when you create the templates. These functions can be customized for your specific module. Some are optional and can be deleted. For example the MM_fetch_ds function is only needed if your module creates datasets and provides them for other modules to use (like the DW module exports data views to be used by other modules). The modules are designed to create elements. For example the DW module creates data view elements, the FG module is used to create figure elements, etc.

• MM_Server Shiny server function.
• MM_init_state Creates an empty the formods state for the module.
• MM_fetch_state Each module has a function to fetch the state. Within this function there should be no interactivity. Any access of the elements to the Shiny input should be isolated. Based on differences between the input elements (current state of the app) and the stored app state can be used to trigger different things.
• MM_fetch_code This takes as it’s first argument the module state. When called with only this argument it should return a character object containing all of the code needed to generate the elements of this module represented in the app. You can assume that any modules this one depends on will be defined previously. For example the FG module will return only that code associated with generating figures. It will be appended to the code from the UD and DW modules that define loading the dataset and creation of the data views. For modules where no code is generated (e.g. ASM) just return NULL.
• MM_append_report If a module generates reportable outputs, this function will be used to append those outputs to the overall reports generated by formods.
• MM_fetch_ds If a module provides data sets to be used in other modules you need to create this function. It should return at least the following:
  • hasds Boolean variable indicating if the modules currently has any exportable datasets.
  • isgood General return status of the funciton. Set to FALSE if any errors were encoutered.
  • msgs A character vector of any messages to pass back to the user.
  • ds A module can provide multiple datasets. This is a list with the following elements for each dataset:
    • label Text label for the dataset
    • MOD_TYPE Short name for the type of module.
    • id module ID.
    • DS Dataframe containing the actual dataset.
    • DSMETA Metadata describing DS.
    • code Complete code to build dataset.
    • checksum Module checksum.
    • DSchecksum Dataset checksum.
• MM_fetch_mdl If a module provides data sets to be used in other modules you need to create this function. It should return at least the following:
  • hasmdl Boolean variable indicating if the modules currently has any exportable models.
  • isgood General return status of the funciton. Set to FALSE if any errors were encountered.
  • msgs A character vector of any messages to pass back to the user.
  • mdl A module can provide multiple models. This is a list with the following elements for each model:
    • label Text label for the model.
    • MOD_TYPE Short name for the type of module.
    • id module ID.
    • rx_obj The rxode2 object that holds the model.
    • rx_obj_name The rxode2 object name in generated code.
    • fcn_def Text to define the model
    • DSMETA Verbose metadata describing model.
    • code Complete code to build the model.
    • checksum Checksum of the module the model came from.
    • DSchecksum Checksum of the model.
• MM_test_mksession When testing outside of Shiny it is useful to have a prepopulated session, intput, etc objects with actual data. Each module shoudl have a test_mksession function that populates these objects with useful data. If your module depends on a different module, you can use the test_mksession for the modyou yours depends on. For example the data wrangling module depends on the upload data module. So the DW_test_mksession function uses UD_test_mksession internally to load the test dataset and then builds on top of that. The function should return the following:
  • isgood Boolean indicating the exit status of the function.
  • session The value Shiny session variable (in app) or a list (outside of app) after initialization.
  • input The value of the shiny input at the end of the session initialization.
  • state App state.
  • rsc The react_state components.
• MM_new_element Creates a new module element.
• MM_fetch_current_element Extracts the current element from the state object.
• MM_set_current_element Sets the current element to the provided value.
• MM_del_element Deletes the current active element.

Expected UI components

• ui_mm_compact This is a UI output that contains a compact view of your module that can be called from the main ui functions for the App. It is composed of the individual UI elements that are shown in the MM_module_components.R file. This allows the user a quick way to utilize a model (using the ui_mm_compact), and the ability to customize the module UI by manually arranging the pieces found in MM_module_components.R.

Module interaction

Say you are using the UD module to feed data into the DW module and the user goes back to the upload form and uploads a different data set. This will need to trigger a reset of the Data Wrangling module as well as tell your larger app that something has changed.

Helper functions in formods

• FM_le() - Creates log entries (le) that are displayed in the console.
• FM_tc() - This can be used to evaluate code, trap errors, and process results.
• has_changed()
• set_hold() - Used to set a hold on one or more UI elements. This prevents internal updating of that UI element based on the current value in the App.
• fetch_hold() - This will retrieve the hold status of a UI element.
• remove_hold() - This will remove any holds set on a UI element.
• ‘FM_build_comment()’ - This creates comments from strings so they will form sections when viewed in RStudio.
• FM_add_ui_tooltip() - Attaches a tooltip to a UI element.
• FM_init_state() - Called at the top of your module state initialization function to create a skeleton of a module state that you can then build upon.
• FM_set_notification() - Within you code you can create notifications and attach them to a module state.
• FM_notify() - Used in observeEvent() to show notifications that have not yet been displayed.
• FM_set_mod_state()
• FM_fetch_mod_state()
• FM_set_ui_msg()
• FM_pretty_sort() - Used as a general sorting function that will try to make the sorted results prettier.
• FM_pause_screen() - Pauses the screen when doing something on the server side that takes a while.
• FM_resume_screen() - Resumes activity (unpauses the screen) when you’re done with the pause.
• FM_fetch_data_format() - Creates formatting information for display for a given data frame.

The examples below require a Shiny session variable and a formods state object. Here we create some examples and other objects needed to demonstrate the functions below.

library(formods)
# This creates the state and session objects
sess_res = UD_test_mksession(session=list())
#> → UD: including file
#> → UD:   source: file.path(system.file(package="onbrand"), "templates", "report.docx")
#> → UD:   dest:   file.path("config","report.docx")
#> → UD: including file
#> → UD:   source: file.path(system.file(package="onbrand"), "templates", "report.pptx")
#> → UD:   dest:   file.path("config","report.pptx")
#> → UD: including file
#> → UD:   source: file.path(system.file(package="onbrand"), "templates", "report.yaml")
#> → UD:   dest:   file.path("config","report.yaml")
#> → UD: State initialized
#> → UD: module checksum updated:897d952fecbc804999396a96f9df4b20
state    = sess_res$state
session  = sess_res$session

# Here we load an example dataset into the df object.
data_file_local =  system.file(package="formods", "test_data", "TEST_DATA.xlsx")
sheet           = "DATA"

df = readxl::read_excel(path=data_file_local, sheet=sheet)

remove_hold_listen  <- reactive({
  list(input$my_selection)
})
observeEvent(remove_hold_listen(), {
  # Once the UI has been regenerated we
  # remove any holds for this module
  state = MM_fetch_state(id              = id,
                         input           = input,
                         session         = session,
                         FM_yaml_file    = FM_yaml_file,
                         MOD_yaml_file   = MOD_yaml_file,
                         react_state     = react_state)

  FM_le(state, "removing holds")
  # Removing all holds
  for(hname in names(state[["MM"]][["ui_hold"]])){
    remove_hold(state, session, hname)
  }
}, priority = -100)

hfmt = FM_fetch_data_format(df, state)

# Descriptive headers 
head(as.vector(unlist( hfmt[["col_heads"]])))
#> [1] "<span style='color:#3C8DBC'><b>ID</b><br/><font size='-3'>num</font></span>"      
#> [2] "<span style='color:#3C8DBC'><b>TIME_DY</b><br/><font size='-3'>num</font></span>" 
#> [3] "<span style='color:#3C8DBC'><b>TIME_HR</b><br/><font size='-3'>num</font></span>" 
#> [4] "<span style='color:#3C8DBC'><b>NTIME_DY</b><br/><font size='-3'>num</font></span>"
#> [5] "<span style='color:#3C8DBC'><b>NTIME_HR</b><br/><font size='-3'>num</font></span>"
#> [6] "<span style='color:#3C8DBC'><b>TIME</b><br/><font size='-3'>num</font></span>"

# Subtext
head(as.vector(unlist( hfmt[["col_subtext"]])))
#> [1] "num: 1,⋅⋅⋅,360"  "num: 0,⋅⋅⋅,84"   "num: 0,⋅⋅⋅,2016" "num: 0,⋅⋅⋅,42"  
#> [5] "num: 0,⋅⋅⋅,1008" "num: 0,⋅⋅⋅,2016"

hot = rhandsontable::rhandsontable(
  head(df),
  width      = "100%",
  height     = "100%",
  colHeaders = as.vector(unlist(hfmt[["col_heads"]])),
  rowHeaders = NULL
  )

sel_subtext = as.vector(unlist( hfmt[["col_subtext"]]))
library(shinyWidgets)
shinyWidgets::pickerInput(
    inputId    = "select_example",
    choices    = names(df),
    label      = "Select with subtext",
    choicesOpt = list(subtext = sel_subtext))

   state = FM_set_notification(state, "Something happened", "Example Notification")

    toNotify <- reactive({
      list(input$input1,
           input$input2)
    })

    observeEvent(toNotify(), {
      state = MM_fetch_state(id              = id,
                             input           = input,
                             session         = session,
                             FM_yaml_file    = FM_yaml_file,
                             MOD_yaml_file   = MOD_yaml_file,
                             react_state     = react_state)

      # Triggering optional notifications
      notify_res =
      FM_notify(state    = state,
                session  = session)
    })

uiele = shiny::textInput(
          inputId = "some_text", 
          label   = "You need to type harder!")
uiele = FM_add_ui_tooltip(state, uiele, 
      tooltip  = "This is a tooltip",
      position = "left")

FM_pause_screen(state, session)
FM_resume_screen(state, session)

formods state objects

When you create a formods state object it can have the following fields:

• yaml- Contents of the formods configuration file.
• MC - Contents of the module configuration file.
• MM - MM here is the short name of the current module. MOD_TYPE below), this is where you would store any app information. (see below).
• MOD_TYPE - Short name of the module.
• id - ID of the module.
• FM_yaml_file - formods configuration file.
• MOD_yaml_file - Module configuration file.
• notifications - Contains notifications set by the user through FM_set_notification().