From 097386c35ba5e8c920c04bd60a22c3133c0a1ba6 Mon Sep 17 00:00:00 2001
From: bzkrouse <rebecca_zabel@rhoworld.com>
Date: Tue, 26 Feb 2019 11:46:49 -0500
Subject: [PATCH] document shiny app functions

---
 .../eDISH_app/modules/dataUpload/dataUpload.R | 29 +++++++++++
 .../modules/dataUpload/dataUploadUI.R         | 13 +++++
 .../modules/renderChart/renderEDishChart.R    | 16 ++++++
 .../modules/renderChart/renderEDishChartUI.R  |  8 +++
 .../modules/renderSettings/renderSettings.R   | 51 +++++++++++++++++--
 .../modules/renderSettings/renderSettingsUI.R | 16 +++++-
 .../renderSettings/util/createControl.R       | 18 +++++++
 .../renderSettings/util/createSettingLabel.R  |  7 +++
 .../renderSettings/util/createSettingsUI.R    |  9 ++++
 .../modules/renderSettings/util/flagSetting.R |  8 ---
 .../renderSettings/util/labelSetting.R        | 14 -----
 .../renderSettings/util/updateSettingStatus.R | 17 +++++--
 inst/eDISH_app/server.R                       |  7 +++
 inst/eDISH_app/ui.R                           |  2 +
 14 files changed, 184 insertions(+), 31 deletions(-)
 delete mode 100644 inst/eDISH_app/modules/renderSettings/util/flagSetting.R
 delete mode 100644 inst/eDISH_app/modules/renderSettings/util/labelSetting.R

diff --git a/inst/eDISH_app/modules/dataUpload/dataUpload.R b/inst/eDISH_app/modules/dataUpload/dataUpload.R
index 781b1410..82ee0633 100644
--- a/inst/eDISH_app/modules/dataUpload/dataUpload.R
+++ b/inst/eDISH_app/modules/dataUpload/dataUpload.R
@@ -1,3 +1,32 @@
+#' Data upload module - server code
+#'
+#' This module creates the Data tab for the Shiny app. 
+#' 
+#' Workflow:
+#' (1) A reactiveValues() list is created with example dataset as first entry. 
+#'     The following information is included in list:
+#'        - dataset and name
+#'        - current (whether the dataset came from most recent upload)
+#'        - data standard / quality of match
+#' (2) Upon user data upload:
+#'        - reactiveValues list is updated with information about new data.
+#'        - radio buttons are updated with new data choices
+#' (3) When a new dataset is selected, the data preview output is invalidated
+#' (4) When a new dataset is selected OR the standard changes (since these don't update at the same time), the
+#'     the settings object ("settings()") is invalidated.
+#' (5) When a new dataset is selected OR the settings object is updated, the settings validation ("status()") is 
+#'     invalidated.
+#' 
+#' @param input Input objects from module namespace
+#' @param output Output objects from module namespace
+#' @param session An environment that can be used to access information and functionality relating to the session
+#'
+#' @return A list of reactive values, including: 
+#' \itemize{
+#' \item{"data_selected"}{A data frame selected by the user}
+#' \item{"settings"}{Result from generateSettings() for data_selected}
+#' \item{"status"}{Result from validateSettings() for data_selected and settings}
+#'  
 dataUpload <- function(input, output, session){
 
   ns <- session$ns
diff --git a/inst/eDISH_app/modules/dataUpload/dataUploadUI.R b/inst/eDISH_app/modules/dataUpload/dataUploadUI.R
index 3b8683bd..cb5b6ccb 100644
--- a/inst/eDISH_app/modules/dataUpload/dataUploadUI.R
+++ b/inst/eDISH_app/modules/dataUpload/dataUploadUI.R
@@ -1,3 +1,16 @@
+#' Data upload module - UI code
+#' 
+#' This module creates the Data tab for the Shiny app. 
+#' 
+#' The UI contains:
+#' - a file upload control
+#' - radio buttons for selecting from the available datasets
+#' - raw data preview. 
+#'
+#' @param id The module-specific ID that will get pre-pended to all element IDs
+#'
+#' @return The UI for the Data tab
+#'
 dataUploadUI <- function(id){
 
   ns <- NS(id)
diff --git a/inst/eDISH_app/modules/renderChart/renderEDishChart.R b/inst/eDISH_app/modules/renderChart/renderEDishChart.R
index 15470cca..b900e9bf 100644
--- a/inst/eDISH_app/modules/renderChart/renderEDishChart.R
+++ b/inst/eDISH_app/modules/renderChart/renderEDishChart.R
@@ -1,3 +1,19 @@
+#' Render eDISH chart - server code
+#' 
+#' This module creates the Chart tab for the Shiny app, which contains the interactive eDISH graphic. 
+#' 
+#' Workflow: 
+#' (1) A change in `data`, `settings`, or `valid` invalidates the eDISH chart output
+#' (2) Upon a change in `valid`, the export chart functionality is conditionally made available or unavailable to user
+#' (3) If "export chart" button is pressed, data and settings are passed to the parameterized report, knitted using
+#'     Rmarkdown, and downloaded to user computer.
+#' 
+#' @param input Input objects from module namespace
+#' @param output Output objects from module namespace
+#' @param session An environment that can be used to access information and functionality relating to the session
+#' @param data A data frame 
+#' @param valid A logical indicating whether data/settings combination is valid for chart
+ 
 renderEDishChart <- function(input, output, session, data, settings, valid){
   
   ns <- session$ns
diff --git a/inst/eDISH_app/modules/renderChart/renderEDishChartUI.R b/inst/eDISH_app/modules/renderChart/renderEDishChartUI.R
index 8751609c..62a8fe14 100644
--- a/inst/eDISH_app/modules/renderChart/renderEDishChartUI.R
+++ b/inst/eDISH_app/modules/renderChart/renderEDishChartUI.R
@@ -1,3 +1,11 @@
+#' Render eDISH chart - UI code
+#' 
+#' This module creates the Chart tab for the Shiny app, which contains the interactive eDISH graphic.  
+
+#' @param id The module-specific ID that will get pre-pended to all element IDs
+#'
+#' @return The UI for the Chart tab
+#'
 renderEDishChartUI <- function(id){
   
   ns <- NS(id)
diff --git a/inst/eDISH_app/modules/renderSettings/renderSettings.R b/inst/eDISH_app/modules/renderSettings/renderSettings.R
index 0820440c..998cf506 100644
--- a/inst/eDISH_app/modules/renderSettings/renderSettings.R
+++ b/inst/eDISH_app/modules/renderSettings/renderSettings.R
@@ -1,8 +1,49 @@
+# Functions to include
 source("modules/renderSettings/util/createSettingLabel.R")
 source("modules/renderSettings/util/createControl.R")
 source("modules/renderSettings/util/createSettingsUI.R")
 source("modules/renderSettings/util/updateSettingStatus.R")
 
+#' Render Settings module - Server code
+#' 
+#' This module creates the Settings tab for the Shiny app. 
+#'  
+#' Workflow:
+#' (1) Reactive input_names() contains names of settings related to selected charts.  When a user changes
+#'     chart selections, input_names() is invalidated.
+#' (2) A change in input_names(), `data`, or `settings` invalidates the following:
+#'      - renderUI associated with data mapping settings
+#'      - renderUI associated with measure settings
+#'      - renderUI associated with appearance settings
+#' (3) These renderUI's call upon the createSettingsUI() function and will update
+#'     even when settings tab not in view.  They will create and populate the UI for all related settings.
+#' (4) Field-level inputs are updated upon any of the following events:
+#'      - a change in selected data
+#'      - change in selected chart(s)
+#'      - change in column-level input selection
+#'     update includes:
+#'      - Deactivate/activate field-level selector based on whether column-level input has been selected
+#'      - Data choices for field-level inputs based on selected column-level input
+#'  (5) A reactive representing the new settings object (settings_new()) is created based on UI selections. This object is invalidated
+#'      when ANY input changes.
+#'  (6) A reactive representing the new data/settings validation (status_new()) is created based on data and updated settings object.  
+#'      A change in data OR updated settings object invalidated this reactive.
+#'  (7) Upon a change in the new validation (status_new() and derived status_df()), updated status messages are 
+#'      printed on UI by calling updateSettingStatus().  ALL messages are re-printed at once.
+#'     
+#' @param input Input objects from module namespace
+#' @param output Output objects from module namespace
+#' @param session An environment that can be used to access information and functionality relating to the session
+#' @param data A data frame
+#' @param settings Settings object that corresponds to data's standard - result of generateSettings().
+#' @param status A list describing the validation state for data/settings - result of validateSettings().
+#'
+#' @return A list of reactive values, including: 
+#' \itemize{
+#' \item{"charts"}{A vector of chart(s) selected by the user}
+#' \item{"settings"}{Upadted settings object based on UI/user selections}
+#' \item{"status"}{Result from validateSettings() for originally selected data + updated settings object}
+#' 
 renderSettings <- function(input, output, session, data, settings, status){
 
   ns <- session$ns
@@ -199,14 +240,14 @@ renderSettings <- function(input, output, session, data, settings, status){
   # print validation messages
   ######################################################################
  observe({
-   for (name in isolate(input_names())){
+   for (key in isolate(input_names())){
 
-     if(name %in% status_df()$text_key){
+     if(key %in% status_df()$text_key){
 
-       status_short <- status_df()[status_df()$text_key==name, "message_short"]
-       status_long <- status_df()[status_df()$text_key==name, "message_long"]
+       status_short <- status_df()[status_df()$text_key==key, "message_short"]
+       status_long <- status_df()[status_df()$text_key==key, "message_long"]
 
-       updateSettingStatus(ns=ns, name=name, status_short=status_short, status_long=status_long)
+       updateSettingStatus(ns=ns, key=key, status_short=status_short, status_long=status_long)
      }
 
    }
diff --git a/inst/eDISH_app/modules/renderSettings/renderSettingsUI.R b/inst/eDISH_app/modules/renderSettings/renderSettingsUI.R
index df8f910d..e2a34290 100644
--- a/inst/eDISH_app/modules/renderSettings/renderSettingsUI.R
+++ b/inst/eDISH_app/modules/renderSettings/renderSettingsUI.R
@@ -1,4 +1,18 @@
-
+#' Render Settings module - UI code
+#' 
+#' This module creates the Settings tab for the Shiny app. The UI is dynamically populated from the server side. 
+#' 
+#' The UI contains:
+#' - Chart selector 
+#' - Settings customizations for the selected charts:
+#'      - Data mapping
+#'      - Measure settings
+#'      - Appearance settings
+#'
+#' @param id The module-specific ID that will get pre-pended to all element IDs
+#'
+#' @return The UI for the Settings tab
+#'
 renderSettingsUI <- function(id){
   
   ns <- NS(id)
diff --git a/inst/eDISH_app/modules/renderSettings/util/createControl.R b/inst/eDISH_app/modules/renderSettings/util/createControl.R
index b1af014d..b958f647 100644
--- a/inst/eDISH_app/modules/renderSettings/util/createControl.R
+++ b/inst/eDISH_app/modules/renderSettings/util/createControl.R
@@ -1,3 +1,21 @@
+#' Create setting control 
+#'
+#' Workflow:
+#' (1) Get setting label and description from metadata
+#' (2) Get setting value from settings object
+#' (3) Get choices and placeholder text for the selectors based on metadata, data, and settings
+#' (4) Create HTML code for the selector based on the following metadata:
+#'     - whether the option is a column or field-level input
+#'     - data type of the setting (e.g. character/numeric/logical, vector of length 1 vs >1) 
+#'     - label, description, choices, selected value, placeholder text
+#' 
+#' @param key A character key representing the setting of interest  
+#' @param metadata Metadata data frame to be queried for information about the setting
+#' @param data A data frame to be used to populate control options
+#' @param settings A settings list to be used to populate control options
+#' @param ns  The namespace of the current module
+#'
+#' @return HTML code for the div containing the setting of interest
 createControl <- function(key, metadata, data, settings, ns){
   
   sm_key <- filter(metadata, text_key==key)
diff --git a/inst/eDISH_app/modules/renderSettings/util/createSettingLabel.R b/inst/eDISH_app/modules/renderSettings/util/createSettingLabel.R
index b127f9ec..c496ae53 100644
--- a/inst/eDISH_app/modules/renderSettings/util/createSettingLabel.R
+++ b/inst/eDISH_app/modules/renderSettings/util/createSettingLabel.R
@@ -1,3 +1,10 @@
+#' Create label for chart setting selector
+#'
+#' @param key A character key representing the setting of interest.
+#'
+#' @return A character string containing full HTML text to be used for input label. Contains info icon to 
+#' indicate that description is available upon mouseover, setting label, and asterisk if setting is required.
+#' 
 createSettingLabel <- function(key){
   sm <- getSettingsMetadata(text_keys=key)
   setting_label <- sm$label
diff --git a/inst/eDISH_app/modules/renderSettings/util/createSettingsUI.R b/inst/eDISH_app/modules/renderSettings/util/createSettingsUI.R
index 8a7e955e..086a5940 100644
--- a/inst/eDISH_app/modules/renderSettings/util/createSettingsUI.R
+++ b/inst/eDISH_app/modules/renderSettings/util/createSettingsUI.R
@@ -1,3 +1,12 @@
+#' Create UI for specified section of settings tab
+#'
+#' @param data A data frame to be used to populate control options
+#' @param settings A settings list to be used to populate control options
+#' @param setting_cat_val Settings category. One of "data","measure","appearance"
+#' @param charts A character vector containing names of charts of interest
+#' @param ns The namespace of the current module
+#'
+#' @return A list containing the UI code for all selectors in the specified settings category.
 createSettingsUI <- function(data, settings, setting_cat_val, charts, ns){
   
   sm <- getSettingsMetadata(charts=charts) %>% 
diff --git a/inst/eDISH_app/modules/renderSettings/util/flagSetting.R b/inst/eDISH_app/modules/renderSettings/util/flagSetting.R
deleted file mode 100644
index eb0b6542..00000000
--- a/inst/eDISH_app/modules/renderSettings/util/flagSetting.R
+++ /dev/null
@@ -1,8 +0,0 @@
-flagSetting<-function(session, name, originalLabel){
-  
-  originalLabel <- paste("<i class='fa fa-info-circle' style='color:gray'></i>", originalLabel)
-  
-  shinyjs::html(id = paste0("lbl_", name),
-                html = paste0(originalLabel, "<strong>*</strong>"),
-                add = FALSE)
-}
diff --git a/inst/eDISH_app/modules/renderSettings/util/labelSetting.R b/inst/eDISH_app/modules/renderSettings/util/labelSetting.R
deleted file mode 100644
index cf0f4cf7..00000000
--- a/inst/eDISH_app/modules/renderSettings/util/labelSetting.R
+++ /dev/null
@@ -1,14 +0,0 @@
-labelSetting<-function(ns, name, label, description){
-
-  
-  label <- paste("<i class='fa fa-info-circle' style='color:gray'></i>", label)
-  
-  label_id <- paste0("lbl_", name)
-  shinyjs::html(id =  label_id,
-                html = label,
-                add = FALSE)
-  
-  tooltip_id <- paste0("tt_lbl_", name)
-
-  shinyjs::runjs(paste0('$("#',ns(tooltip_id), '").attr("title", "', description, '")'))
-}
\ No newline at end of file
diff --git a/inst/eDISH_app/modules/renderSettings/util/updateSettingStatus.R b/inst/eDISH_app/modules/renderSettings/util/updateSettingStatus.R
index c594d42b..ed3d49e2 100644
--- a/inst/eDISH_app/modules/renderSettings/util/updateSettingStatus.R
+++ b/inst/eDISH_app/modules/renderSettings/util/updateSettingStatus.R
@@ -1,7 +1,18 @@
-updateSettingStatus<-function(ns, name, status_short, status_long){
+#' Update setting validation status
+#' 
+#' Workflow:
+#' (1) Update abbreviated status for a given setting using green (valid) or red (invalid) text
+#' (2) Update long status message for a given setting to be displayed upon mouseover
+#' 
+#' @param ns The namespace of the current module
+#' @param key A character key representing the setting of interest 
+#' @param status_short Abbreviated validation message  
+#' @param status_long Detailed validation message  
+
+updateSettingStatus<-function(ns, key, status_short, status_long){
   
-  msg_id <- paste0("msg_", name)
-  tooltip_id <- paste0("tt_msg_", name)
+  msg_id <- paste0("msg_", key)
+  tooltip_id <- paste0("tt_msg_", key)
   
   if (status_short=="OK"){
     shinyjs::html(id = msg_id,
diff --git a/inst/eDISH_app/server.R b/inst/eDISH_app/server.R
index 9ee0f420..76dfae74 100644
--- a/inst/eDISH_app/server.R
+++ b/inst/eDISH_app/server.R
@@ -1,3 +1,10 @@
+# Server code for safetyGraphics App
+#   - calls dataUpload module (data tab)
+#   - calls renderSettings module (settings tab)
+#   - calls renderEDishChart (chart tab)
+#   - uses render UI to append a red X or green check on tab title, 
+#      indicating whether user has satisfied requirements of that tab
+
 function(input, output, session){
 
 
diff --git a/inst/eDISH_app/ui.R b/inst/eDISH_app/ui.R
index a6e2eea2..35f49691 100644
--- a/inst/eDISH_app/ui.R
+++ b/inst/eDISH_app/ui.R
@@ -1,3 +1,5 @@
+# UI Code for safetyGraphics App
+
 tagList(
   useShinyjs(),
   tags$style(HTML("