Skip to content

Commit

Permalink
📚 add documentation, 🛃 export fns
Browse files Browse the repository at this point in the history
📚 update docs for Dash class

📚 add docs for functions

📚 document and export createCallbackId

📚 document createCallbackId

📚 document createCallbackId

update namespace and add dashLogger.Rd
  • Loading branch information
Ryan Patrick Kyle committed Oct 31, 2019
1 parent 1461ee7 commit df4c737
Show file tree
Hide file tree
Showing 8 changed files with 269 additions and 18 deletions.
7 changes: 4 additions & 3 deletions NAMESPACE
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
52 changes: 48 additions & 4 deletions R/dash.R
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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.
#' }
#' }
Expand Down Expand Up @@ -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)
}
}
65 changes: 65 additions & 0 deletions R/utils.R
Original file line number Diff line number Diff line change
Expand Up @@ -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))) {
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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))
}
50 changes: 39 additions & 11 deletions man/Dash.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

43 changes: 43 additions & 0 deletions man/clientsideFunction.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

25 changes: 25 additions & 0 deletions man/createCallbackId.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

25 changes: 25 additions & 0 deletions man/dashLogger.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

20 changes: 20 additions & 0 deletions man/getEnvVar.Rd

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

0 comments on commit df4c737

Please sign in to comment.