📚 add documentation, 🛃 export fns

📚 update docs for Dash class

📚 add docs for functions

📚 document and export createCallbackId

📚 document createCallbackId

📚 document createCallbackId

update namespace and add dashLogger.Rd

NAMESPACE

@@ -2,13 +2,14 @@
 
 S3method(print,dash_component)
 export(Dash)
-export(dashNoUpdate)
-export(createCallbackId)
 export(clientsideFunction)
+export(createCallbackId)
+export(dashLogger)
+export(dashNoUpdate)
+export(getEnvVar)
 export(input)
 export(output)
 export(state)
-export(dashLogger)
 import(dashCoreComponents)
 import(dashHtmlComponents)
 importFrom(R6,R6Class)

R/dash.R

@@ -12,7 +12,10 @@
 #'   assets_ignore = '',
 #'   serve_locally = TRUE,
 #'   routes_pathname_prefix = '/',
-#'   requests_pathname_prefix = '/'
+#'   requests_pathname_prefix = '/',
+#'   external_scripts = NULL,
+#'   external_stylesheets = NULL,
+#'   suppress_callback_exceptions = FALSE
 #' )
 #'
 #' @section Arguments:
@@ -88,11 +91,32 @@
 #'     The latter may offer improved performance relative to callbacks written
 #'     in R.
 #'   }
+#'   \item{`callback_context()`}{
+#'     The `callback_context` method permits retrieving the inputs which triggered 
+#'     the firing of a given callback, and allows introspection of the input/state 
+#'     values given their names. It is only available from within a callback; 
+#'     attempting to use this method outside of a callback will result in a warning.
+#'   }
 #'   \item{`run_server(host =  Sys.getenv('DASH_HOST', "127.0.0.1"),
 #'    port = Sys.getenv('DASH_PORT', 8050), block = TRUE, showcase = FALSE, ...)`}{
-#'     Launch the application. If provided, `host`/`port` set
-#'     the `host`/`port` fields of the underlying [fiery::Fire] web
-#'     server. The `block`/`showcase`/`...` arguments are passed along
+#'     The `run_server` method has 13 formal arguments, several of which are optional:
+#'     \describe{
+#'       \item{host}{Character. A string specifying a valid IPv4 address for the Fiery server, or `0.0.0.0` to listen on all addresses. Default is `127.0.0.1` Environment variable: `DASH_HOST`.}
+#'       \item{port}{Integer. Specifies the port number on which the server should listen (default is `8050`). Environment variable: `DASH_PORT`.}
+#'       \item{block}{Logical. Start the server while blocking console input? Default is `TRUE`.}
+#'       \item{showcase}{Logical. Load the Dash application into the default web browser when server starts? Default is `FALSE`.}
+#'       \item{use_viewer}{Logical. Load the Dash application into RStudio's viewer pane? Requires that `host` is either `127.0.0.1` or `localhost`, and that Dash application is started within RStudio; if `use_viewer = TRUE` and these conditions are not satsified, the user is warned and the app opens in the default browser instead. Default is `FALSE`.}
+#'       \item{debug}{Logical. Enable/disable all the dev tools unless overridden by the arguments or environment variables. Default is `FALSE` when called via `run_server`. Environment variable: `DASH_DEBUG`.}
+#'       \item{dev_tools_ui}{Logical. Show Dash's dev tools UI? Default is `TRUE` if `debug == TRUE`, `FALSE` otherwise. Environment variable: `DASH_UI`.}
+#'       \item{dev_tools_hot_reload}{Logical. Activate hot reloading when app, assets, and component files change? Default is `TRUE` if `debug == TRUE`, `FALSE` otherwise. Requires that the Dash application is loaded using `source()`, so that `srcref` attributes are available for executed code. Environment variable: `DASH_HOT_RELOAD`.}
+#'       \item{dev_tools_hot_reload_interval}{Numeric. Interval in seconds for the client to request the reload hash. Default is `3`. Environment variable: `DASH_HOT_RELOAD_INTERVAL`.}
+#'       \item{dev_tools_hot_reload_watch_interval}{Numeric. Interval in seconds for the server to check asset and component folders for changes. Default `0.5`. Environment variable: `DASH_HOT_RELOAD_WATCH_INTERVAL`.}
+#'       \item{dev_tools_props_check}{Logical. Validate the types and values of Dash component properties? Default is `TRUE` if `debug == TRUE`, `FALSE` otherwise. Environment variable: `DASH_PROPS_CHECK`.}
+#'       \item{dev_tools_prune_errors}{Logical. Reduce tracebacks to just user code, stripping out Fiery and Dash pieces? Only available with debugging. `TRUE` by default, set to `FALSE` to see the complete traceback. Environment variable: `DASH_PRUNE_ERRORS`.}
+#'       \item{dev_tools_silence_routes_logging}{Logical. Replace Fiery's default logger with `dashLogger` instead (will remove all routes logging)? Enabled with debugging by default because hot reload hash checks generate a lot of requests.}
+#'     }
+#'     Starts the Fiery server in local mode. If a parameter can be set by an environment variable, that is listed too. Values provided here take precedence over environment variables.
+#'     Launch the application. If provided, `host`/`port` set the `host`/`port` fields of the underlying [fiery::Fire] web server. The `block`/`showcase`/`...` arguments are passed along
 #'     to the `ignite()` method of the [fiery::Fire] server.
 #'   }
 #' }
@@ -1270,3 +1294,23 @@ validate_dependency <- function(layout_, dependency) {
 
   TRUE
 }
+
+#' Retrieve Environment Variables 
+#'
+#' This function queries an environment variable, returning the specified value when the result is undefined or an empty string.
+#' 
+#' @param env_var Character. The name of the environment variable whose value will be retrieved.
+#' @param value_if_missing Object. The value to be returned if the value of `env_var` is "", or the variable is undefined.
+#' 
+#' @export
+#' @examples
+#' # returns NULL if "FOO" does not exist
+#' getEnvVar("FOO", NULL)
+getEnvVar <- function(env_var, value_if_missing=NULL) {
+  value <- Sys.getenv(env_var)
+  if (value == "") {
+    return(value_if_missing)
+  } else {
+    return(value)
+  }
+}

R/utils.R

@@ -926,6 +926,24 @@ getDashMetadata <- function(pkgname) {
   return(metadataFn)
 }
 
+#' Construct a Callback ID
+#'
+#' Create a callback ID from a Dash output object.
+#' 
+#' @param output The result of calling `output()`; an object whose class membership includes `dash_dependency` and `output`.
+#' 
+#' @details This function is primarily used internally for inserting entries into Dash's callback map, but may also be
+#' used to construct IDs for testing purposes from either single or multiple output callbacks.
+#' 
+#' 
+#' @export
+#' 
+#' @examples 
+#' # single output context -- will create "stock-graph.figure"
+#' createCallbackId(output('stock-graph', 'figure'))
+#' 
+#' # multiple output context -- will create "..stock-graph.figure...bond-graph.figure.."
+#' createCallbackId(list(output('stock-graph', 'figure'), output('bond-graph', 'figure')))
 createCallbackId <- function(output) {
   # check if callback uses single output
   if (!any(sapply(output, is.list))) {
@@ -1060,6 +1078,20 @@ changedAssets <- function(before, after) {
   )
 }
 
+#' Generate a Fiery Log Which Omits Routing and Request Entries 
+#'
+#' Use a less verbose Fiery logger when debugging Dash for R applications.
+#' 
+#' @param event Character. The event type to log; options are `'error'`, `'warning'` or `'message'`.
+#' @param message Character. The message text to include immediately after the event text.
+#' @param request The request to be logged; default is `NULL`.
+#' @param time The time of the event to be logged; default is `Sys.time()`, which reports the current system time.
+#' 
+#' @details This function is specified as the logger when `dev_tools_silence_routes_logging = TRUE`. It is not
+#' intended to be called directly.
+#' 
+#'
+#' @export
 dashLogger <- function(event = NULL,
                        message = NULL,
                        request = NULL,
@@ -1099,6 +1131,39 @@ dashLogger <- function(event = NULL,
   }
 }
 
+#' Define a clientside callback
+#'
+#' Create a callback that updates the output by calling a clientside (JavaScript) function instead of an R function.
+#' 
+#' @param namespace Character. Describes where the JavaScript function resides (Dash will look
+#' for the function at `window[namespace][function_name]`.)
+#' @param function_name Character. Provides the name of the JavaScript function to call.
+#' 
+#' @details With this signature, Dash's front-end will call `window.my_clientside_library.my_function` with the current
+#' values of the `value` properties of the components `my-input` and `another-input` whenever those values change.
+#' Include a JavaScript file by including it your `assets/` folder. The file can be named anything but you'll need to
+#' assign the function's namespace to the `window`. For example, this file might look like:
+#' \preformatted{window.my_clientside_library = \{
+#' my_function: function(input_value_1, input_value_2) \{
+#'    return (
+#'      parseFloat(input_value_1, 10) +
+#'        parseFloat(input_value_2, 10)
+#'    );
+#' \}
+#'\}
+#'}
+#' 
+#' 
+#' @export
+#' @examples \dontrun{
+#' app$callback(
+#'   output('output-clientside', 'children'),
+#'   params=list(input('input', 'value')),
+#'   clientsideFunction(
+#'   namespace = 'my_clientside_library',
+#'   function_name = 'my_function'
+#'   ) 
+#' )}
 clientsideFunction <- function(namespace, function_name) {
   return(list(namespace=namespace, function_name=function_name))
 }