diff --git a/.circleci/config.yml b/.circleci/config.yml index 677d90bf..1938c119 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -24,7 +24,6 @@ jobs: echo "RUNNING JOB: ${CIRCLE_JOB}" echo "JOB PARALLELISM: ${CIRCLE_NODE_TOTAL}" echo "CIRCLE_REPOSITORY_URL: ${CIRCLE_REPOSITORY_URL}" - export PERCY_ENABLE=0 echo $CIRCLE_JOB > circlejob.txt git rev-parse HEAD | tr -d '\n' > commit.txt diff --git a/CHANGELOG.md b/CHANGELOG.md index 31345491..f615ed22 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,18 @@ # Change Log for Dash for R All notable changes to this project will be documented in this file. +## [0.5.0 ] - 2020-05-28 +### Added +- Dash for R now depends on the `brotli` package explicitly; previously it was loaded when importing `reqres`. [#204](https://github.com/plotly/dashR/pull/204) + +### Changed +- Dash for R no longer wraps the layout in an `htmlDiv` internally, for parity with Dash for Python. Starting in v0.5.0, the `layout` method only accepts a single argument, and that argument must be a Dash component or a function that returns a Dash component. [#121](https://github.com/plotly/dashR/pull/121) +- Package documentation has been significantly refactored to use new features of `roxygen2` when documenting R6 classes +- The `title` method now specifies `Dash` as the default application title instead of `dash`. [#200](https://github.com/plotly/dashR/pull/200) + +### Fixed +- A minor bug in `validate_keys` which prevented `interpolate_index` from working as intended has been resolved + ## [0.4.1] - 2020-05-08 ### Fixed - Callbacks with multiple outputs which return one or more components are now permitted; a bug previously prevented their use, fixed in [#198](https://github.com/plotly/dashR/pull/198) diff --git a/DESCRIPTION b/DESCRIPTION index 27448c9e..f3d20aea 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,6 +1,6 @@ Package: dash Title: An Interface to the Dash Ecosystem for Authoring Reactive Web Applications -Version: 0.4.1 +Version: 0.5.0 Authors@R: c(person("Chris", "Parmer", role = c("aut"), email = "chris@plotly.com"), person("Ryan Patrick", "Kyle", role = c("aut", "cre"), comment = c(ORCID = "0000-0001-5829-9867"), email = "ryan@plotly.com"), person("Carson", "Sievert", role = c("aut"), comment = c(ORCID = "0000-0002-4958-2844")), person("Hammad", "Khan", role = c("aut"), email = "hammadkhan@plotly.com"), person(family = "Plotly Technologies", role = "cph")) Description: A framework for building analytical web applications, Dash offers a pleasant and productive development experience. No JavaScript required. Depends: @@ -20,7 +20,8 @@ Imports: digest, base64enc, mime, - crayon + crayon, + brotli Suggests: testthat Collate: @@ -38,7 +39,7 @@ License: MIT + file LICENSE Encoding: UTF-8 LazyData: true KeepSource: true -RoxygenNote: 6.1.1 +RoxygenNote: 7.1.0 Roxygen: list(markdown = TRUE) URL: https://github.com/plotly/dashR BugReports: https://github.com/plotly/dashR/issues diff --git a/NAMESPACE b/NAMESPACE index e5c7d9ec..8ac7711a 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -12,6 +12,7 @@ import(dashHtmlComponents) importFrom(R6,R6Class) importFrom(assertthat,assert_that) importFrom(base64enc,base64encode) +importFrom(brotli,brotli_compress) importFrom(digest,sha1) importFrom(fiery,Fire) importFrom(fiery,combined_log_format) diff --git a/R/dash.R b/R/dash.R index eb666d18..02899332 100644 --- a/R/dash.R +++ b/R/dash.R @@ -1,275 +1,61 @@ -#' Create and configure a Dash app object -#' -#' A framework for building analytical web applications, Dash offers a pleasant and productive development experience. No JavaScript required. -#' -#' @usage Dash -#' -#' @section Constructor: Dash$new( -#' name = NULL, -#' server = fiery::Fire$new(), -#' assets_folder = 'assets', -#' assets_url_path = '/assets', -#' eager_loading = FALSE, -#' assets_ignore = '', -#' serve_locally = TRUE, -#' meta_tags = NULL, -#' url_base_pathname = '/', -#' routes_pathname_prefix = NULL, -#' requests_pathname_prefix = NULL, -#' external_scripts = NULL, -#' external_stylesheets = NULL, -#' suppress_callback_exceptions = FALSE, -#' show_undo_redo = FALSE -#' ) -#' -#' @section Arguments: -#' \tabular{lll}{ -#' `name` \tab \tab Character. The name of the Dash application (placed in the title -#' of the HTML page). DEPRECATED; please use `index_string()` or `interpolate_index()` instead.\cr -#' `server` \tab \tab The web server used to power the application. -#' Must be a [fiery::Fire] object.\cr -#' `assets_folder` \tab \tab Character. A path, relative to the current working directory, -#' for extra files to be used in the browser. Default is "assets". All .js and -#' .css files will be loaded immediately unless excluded by `assets_ignore`, -#' and other files such as images will be served if requested. Default is `assets`. \cr -#' `assets_url_path` \tab \tab Character. Specify the URL path for asset serving. Default is `assets`. \cr -#' `eager_loading` \tab \tab Logical. Controls whether asynchronous resources are prefetched (if `TRUE`) or loaded on-demand (if `FALSE`). \cr -#' `assets_ignore` \tab \tab Character. A regular expression, to match assets to omit from -#' immediate loading. Ignored files will still be served if specifically requested. You -#' cannot use this to prevent access to sensitive files. \cr -#' `serve_locally` \tab \tab Logical. Whether to serve HTML dependencies locally or -#' remotely (via URL).\cr -#' `compress` \tab \tab Logical. Whether to try to compress files and data served by Fiery. -#' By default, `brotli` is attempted first, then `gzip`, then the `deflate` algorithm, before falling -#' back to `identity`.\cr -#' `meta_tags` \tab \tab List of lists. HTML ``tags to be added to the index page. -#' Each list element should have the attributes and values for one tag, eg: -#' `list(name = 'description', content = 'My App')`.\cr -#' `url_base_pathname` \tab \tab Character. A local URL prefix to use app-wide. Default is -#' `/`. Both `requests_pathname_prefix` and `routes_pathname_prefix` default to `url_base_pathname`. -#' Environment variable is `DASH_URL_BASE_PATHNAME`.\cr -#' `routes_pathname_prefix` \tab \tab Character. A prefix applied to the backend routes. -#' Environment variable is `DASH_ROUTES_PATHNAME_PREFIX`.\cr -#' `requests_pathname_prefix` \tab \tab Character. A prefix applied to request endpoints -#' made by Dash's front-end. Environment variable is `DASH_REQUESTS_PATHNAME_PREFIX`.\cr -#' `external_scripts` \tab \tab List. An optional list of valid URLs from which -#' to serve JavaScript source for rendered pages.\cr -#' `external_stylesheets` \tab \tab List. An optional list of valid URLs from which -#' to serve CSS for rendered pages.\cr -#' `suppress_callback_exceptions` \tab \tab Logical. Whether to relay warnings about -#' possible layout mis-specifications when registering a callback.\cr -#' `show_undo_redo` \tab \tab Logical. Set to `TRUE` to enable undo and redo buttons for -#' stepping through the history of the app state. -#' } -#' -#' @section Fields: -#' \describe{ -#' \item{`server`}{ -#' A cloned (and modified) version of the [fiery::Fire] object -#' provided to the `server` argument (various routes will be added which enable -#' Dash functionality). -#' } -#' \item{`config`}{ -#' A list of configuration options passed along to dash-renderer. -#' Users shouldn't need to alter any of these options unless they are -#' constructing their own authorization front-end or otherwise need to know -#' where the application is making API calls. -#' } -#' } -#' -#' @section Methods: -#' \describe{ -#' \item{`layout(...)`}{ -#' Set the layout (i.e., user interface). The layout should be either a -#' collection of Dash components (e.g., [dccSlider], [htmlDiv], etc) or -#' a function which returns a collection of components. -#' } -#' \item{`layout_get(render = TRUE)`}{ -#' Retrieves the layout. If render is `TRUE`, and the layout is a function, -#' the result of the function (rather than the function itself) is returned. -#' } -#' \item{`callback(output, params, func)`}{ -#' The `callback` method has three formal arguments: -#' \describe{ -#' \item{output}{a named list including a component `id` and `property`} -#' \item{params}{an unnamed list of [input] and [state] statements, each with defined `id` and `property`} -#' \item{func}{any valid R function which generates [output] provided [input] and/or [state] arguments, -#' a character string containing valid JavaScript, or a call to [clientsideFunction] including `namespace` -#' and `function_name` arguments for a locally served JavaScript function} -#' } -#' The `output` argument defines which layout component property should -#' receive the results (via the [output] object). The events that -#' trigger the callback are then described by the [input] (and/or [state]) -#' object(s) (which should reference layout components), which become -#' argument values for R callback handlers defined in `func`. Here `func` may -#' either be an anonymous R function, a JavaScript function provided as a -#' character string, or a call to `clientsideFunction()`, which describes a -#' locally served JavaScript function instead. The latter two methods define -#' a "clientside callback", which updates components without passing data to and -#' from the Dash backend. The latter may offer improved performance relative -#' to callbacks written purely in R. -#' } -#' \item{`title("Dash")`}{ -#' The title of the app. If no title is supplied, Dash for R will use 'Dash'. -#' } -#' \item{`title("Dash")`}{ -#' The title of the app. If no title is supplied, Dash for R will use 'Dash'. -#' } -#' \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{`get_asset_url(asset_path, prefix)`}{ -#' The `get_asset_url` method permits retrieval of an asset's URL given its filename. -#' For example, `app$get_asset_url('style.css')` should return `/assets/style.css` when -#' `assets_folder = 'assets'`. By default, the prefix is the value of `requests_pathname_prefix`, -#' but this is configurable via the `prefix` parameter. Note: this method will -#' present a warning and return `NULL` if the Dash app was not loaded via `source()` -#' if the `DASH_APP_PATH` environment variable is undefined. -#' } -#' \item{`get_relative_path(path, requests_pathname_prefix)`}{ -#' The `get_relative_path` method simplifies the handling of URLs and pathnames for apps -#' running locally and on a deployment server such as Dash Enterprise. It handles the prefix -#' for requesting assets similar to the `get_asset_url` method, but can also be used for URL handling -#' in components such as `dccLink` or `dccLocation`. For example, `app$get_relative_url("/page/")` -#' would return `/app/page/` for an app running on a deployment server. The path must be prefixed with -#' a `/`. -#' \describe{ -#' \item{path}{Character. A path string prefixed with a leading `/` which directs at a path or asset directory.} -#' \item{requests_pathname_prefix}{Character. The pathname prefix for the app on a deployed application. Defaults to the environment variable set by the server, or `""` if run locally.} -#' } -#' } -#' \item{`strip_relative_path(path, requests_pathname_prefix)`}{ -#' The `strip_relative_path` method simplifies the handling of URLs and pathnames for apps -#' running locally and on a deployment server such as Dash Enterprise. It acts almost opposite the `get_relative_path` -#' method, by taking a `relative path` as an input, and returning the `path` stripped of the `requests_pathname_prefix`, -#' and any leading or trailing `/`. For example, a path string `/app/homepage/`, would be returned as -#' `homepage`. This is particularly useful for `dccLocation` URL routing. -#' \describe{ -#' \item{path}{Character. A path string prefixed with a leading `/` and `requests_pathname_prefix` which directs at a path or asset directory.} -#' \item{requests_pathname_prefix}{Character. The pathname prefix for the app on a deployed application. Defaults to the environment variable set by the server, or `""` if run locally.} -#' } -#' } -#' \item{`index_string(string)`}{ -#' The `index_string` method allows the specification of a custom index by changing -#' the default `HTML` template that is generated by the Dash UI. Meta tags, CSS, Javascript, -#' are some examples of features that can be modified. -#' This method will present a warning if your HTML template is missing any necessary elements -#' and return an error if a valid index is not defined. The following interpolation keys are -#' currently supported: -#' \describe{ -#' \item{`{%metas%}`}{Optional - The registered meta tags.} -#' \item{`{%favicon%}`}{Optional - A favicon link tag if found in assets.} -#' \item{`{%css%}`}{Optional - Link tags to css resources.} -#' \item{`{%config%}`}{Required - Config generated by dash for the renderer.} -#' \item{`{%app_entry%}`}{Required - The container where dash react components are rendered.} -#' \item{`{%scripts%}`}{Required - Collected dependencies scripts tags.} -#' } -#' \describe{ -#' \item{Example of a basic HTML index string:}{ -#' \preformatted{ -#' " -#' -#' -#' \{\%meta_tags\%\} -#' \{\{%css\%\}\} -#' \{\%favicon\%\} -#' \{\%css_tags\%\} -#' -#' -#' \{\%app_entry\%\} -#' -#' -#' " -#' } -#' } -#' } -#' } -#' \item{`interpolate_index(template_index, ...)`}{ -#' With the `interpolate_index` method, we can pass a custom index with template string -#' variables that are already evaluated. We can directly pass arguments to the `template_index` -#' by assigning them to variables present in the template. This is similar to the `index_string` method -#' but offers the ability to change the default components of the Dash index as seen in the example below: -#' \preformatted{ -#' app$interpolate_index( -#' template_index, -#' metas = "", -#' renderer = renderer, -#' config = config) -#' } -#' \describe{ -#' \item{template_index}{Character. A formatted string with the HTML index string. Defaults to the initial template} -#' \item{...}{Named List. The unnamed arguments can be passed as individual named lists corresponding to the components -#' of the Dash html index. These include the same arguments as those found in the `index_string()` template.} -#' } -#' } -#' \item{`run_server(host = Sys.getenv('HOST', "127.0.0.1"), -#' port = Sys.getenv('PORT', 8050), block = TRUE, showcase = FALSE, ...)`}{ -#' 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: `HOST`.} -#' \item{port}{Integer. Specifies the port number on which the server should listen (default is `8050`). Environment variable: `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 satisfied, 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_hot_reload_max_retry}{Integer. Maximum number of failed reload hash requests before failing and displaying a pop up. Default `0.5`. Environment variable: `DASH_HOT_RELOAD_MAX_RETRY`.} -#' \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. -#' } -#' } -#' -#' @examples -#' \dontrun{ -#' library(dashCoreComponents) -#' library(dashHtmlComponents) -#' library(dash) - -#' app <- Dash$new() -#' app$layout( -#' dccInput(id = "inputID", value = "initial value", type = "text"), -#' htmlDiv(id = "outputID") -#' ) -#' -#' app$callback(output = list(id="outputID", property="children"), -#' params = list(input(id="inputID", property="value"), -#' state(id="inputID", property="type")), -#' function(x, y) -#' sprintf("You've entered: '%s' into a '%s' input control", x, y) -#' ) -#' -#' app$run_server(showcase = TRUE) -#' } +#' R6 class representing a Dash application #' #' @export #' @docType class #' @format An [R6::R6Class] generator object -#' - +#' @description +#' A framework for building analytical web applications, Dash offers a pleasant and productive development experience. No JavaScript required. Dash <- R6::R6Class( 'Dash', public = list( - # user-facing fields + #' @field server + #' A cloned (and modified) version of the [fiery::Fire] object + #' provided to the `server` argument (various routes will be added which enable + #' Dash functionality). server = NULL, + #' @field config + #' A list of configuration options passed along to dash-renderer. + #' Users shouldn't need to alter any of these options unless they are + #' constructing their own authorization front-end or otherwise need to know + #' where the application is making API calls. config = list(), - # i.e., the Dash$new() method - initialize = function(name = NULL, - server = fiery::Fire$new(), + #' @description + #' Create and configure a Dash application. + #' @param server [fiery::Fire] object. The web server used to power the application. + #' @param assets_folder Character. A path, relative to the current working directory, + #' for extra files to be used in the browser. All .js and + #' .css files will be loaded immediately unless excluded by `assets_ignore`, + #' and other files such as images will be served if requested. Default is `assets`. + #' @param assets_url_path Character. Specify the URL path for asset serving. Default is `assets`. + #' @param eager_loading Logical. Controls whether asynchronous resources are prefetched (if `TRUE`) or loaded on-demand (if `FALSE`). + #' @param assets_ignore Character. A regular expression, to match assets to omit from + #' immediate loading. Ignored files will still be served if specifically requested. You + #' cannot use this to prevent access to sensitive files. + #' @param serve_locally Logical. Whether to serve HTML dependencies locally or + #' remotely (via URL). + #' @param meta_tags List of lists. HTML `` tags to be added to the index page. + #' Each list element should have the attributes and values for one tag, eg: + #' `list(name = 'description', content = 'My App')`. + #' @param url_base_pathname Character. A local URL prefix to use app-wide. Default is + #' `/`. Both `requests_pathname_prefix` and `routes_pathname_prefix` default to `url_base_pathname`. + #' Environment variable is `DASH_URL_BASE_PATHNAME`. + #' @param routes_pathname_prefix Character. A prefix applied to the backend routes. + #' Environment variable is `DASH_ROUTES_PATHNAME_PREFIX`. + #' @param requests_pathname_prefix Character. A prefix applied to request endpoints + #' made by Dash's front-end. Environment variable is `DASH_REQUESTS_PATHNAME_PREFIX`. + #' @param external_scripts List. An optional list of valid URLs from which + #' to serve JavaScript source for rendered pages. + #' @param external_stylesheets List. An optional list of valid URLs from which + #' to serve CSS for rendered pages. + #' @param compress Logical. Whether to try to compress files and data served by Fiery. + #' By default, `brotli` is attempted first, then `gzip`, then the `deflate` algorithm, + #' before falling back to `identity`. + #' @param suppress_callback_exceptions Logical. Whether to relay warnings about + #' possible layout mis-specifications when registering a callback. + #' @param show_undo_redo Logical. Set to `TRUE` to enable undo and redo buttons for + #' stepping through the history of the app state. + initialize = function(server = fiery::Fire$new(), assets_folder = 'assets', assets_url_path = '/assets', eager_loading = FALSE, @@ -290,14 +76,6 @@ Dash <- R6::R6Class( assertthat::assert_that(is.logical(serve_locally)) assertthat::assert_that(is.logical(suppress_callback_exceptions)) - # save relevant args as private fields - if (!is.null(name)) { - warning(sprintf( - "The supplied application title, '%s', should be set using the title() method, or passed via index_string() or interpolate_index(); it has been ignored, and 'Dash' will be used instead.", - name), - call. = FALSE - ) - } private$serve_locally <- serve_locally private$eager_loading <- eager_loading # remove leading and trailing slash(es) if present @@ -768,15 +546,44 @@ Dash <- R6::R6Class( # ------------------------------------------------------------------------ # dash layout methods # ------------------------------------------------------------------------ + #' @description + #' Retrieves the Dash application layout. + #' @details + #' If render is `TRUE`, and the layout is a function, + #' the result of the function (rather than the function itself) is returned. + #' @param render Logical. If the layout is a function, should the function be + #' executed to return the layout? If `FALSE`, the function is returned as-is. + #' @return List or function, depending on the value of `render` (see above). + #' When returning an object of class `dash_component`, the default `print` + #' method for this class will display the corresponding pretty-printed JSON + #' representation of the object to the console. layout_get = function(render = TRUE) { if (render) private$layout_render() else private$layout_ }, - layout = function(...) { - private$layout_ <- if (is.function(..1)) ..1 else list(...) + + #' @description + #' Set the Dash application layout (i.e., specify its user interface). + #' @details + #' `value` should be either a + #' collection of Dash components (e.g., [dccSlider], [htmlDiv], etc) or + #' a function which returns a collection of components. The collection + #' of components must be nested, such that any additional components + #' contained within `value` are passed solely as `children` of the top-level + #' component. In all cases, `value` must be a member of the `dash_component` + #' class. + #' @param value An object of the `dash_component` class, which provides + #' a component or collection of components, specified either as a Dash + #' component or a function that returns a Dash component. + layout = function(value) { + # private$layout_ <- if (is.function(..1)) ..1 else list(...) + private$layout_ <- value # render the layout, and then return the rendered layout without printing invisible(private$layout_render()) }, + #' @description + #' Update the version of React in the list of dependencies served by dash-renderer to the client. + #' @param version Character. The version number of React to use. react_version_set = function(version) { versions <- private$react_versions() idx <- versions %in% version @@ -793,6 +600,36 @@ Dash <- R6::R6Class( # ------------------------------------------------------------------------ # callback registration # ------------------------------------------------------------------------ + #' @description + #' Define a Dash callback. + #' @details + #' Describes a server or clientside callback relating the values of one or more + #' `output` items to one or more `input` items which will trigger the callback + #' when they change, and optionally `state` items which provide additional + #' information but do not trigger the callback directly. + #' + #' The `output` argument defines which layout component property should + #' receive the results (via the [output] object). The events that + #' trigger the callback are then described by the [input] (and/or [state]) + #' object(s) (which should reference layout components), which become + #' argument values for R callback handlers defined in `func`. + #' + #' Here `func` may either be an anonymous R function, a JavaScript function + #' provided as a character string, or a call to `clientsideFunction()`, which + #' describes a locally served JavaScript function instead. The latter + #' two methods define a "clientside callback", which updates components + #' without passing data to and from the Dash backend. The latter may offer + #' improved performance relative to callbacks written purely in R. + #' @param output Named list. The `output` argument provides the component `id` + #' and `property` which will be updated by the callback; a callback can + #' target one or more outputs (i.e. multiple outputs). + #' @param params Unnamed list; provides [input] and [state] statements, each + #' with its own defined `id` and `property`. + #' @param func Function; must return [output] provided [input] or [state] + #' arguments. `func` may be any valid R function, or a character string + #' containing valid JavaScript, or a call to [clientsideFunction], + #' including `namespace` and `function_name` arguments for a locally served + #' JavaScript function. callback = function(output, params, func) { assert_valid_callbacks(output, params, func) @@ -837,6 +674,20 @@ Dash <- R6::R6Class( # ------------------------------------------------------------------------ # request and return callback context # ------------------------------------------------------------------------ + #' @description + #' Request and return the calling context of a Dash callback. + #' @details + #' 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. + #' + #' The `callback_context` method returns a list containing three elements: + #' `states`, `triggered`, `inputs`. The first and last of these correspond to + #' the values of `states` and `inputs` for the current invocation of the + #' callback, and `triggered` provides a list of changed properties. + #' + #' @return List comprising elements `states`, `triggered`, `inputs`. callback_context = function() { if (is.null(private$callback_context_)) { warning("callback_context is undefined; callback_context may only be accessed within a callback.") @@ -847,6 +698,18 @@ Dash <- R6::R6Class( # ------------------------------------------------------------------------ # return asset URLs # ------------------------------------------------------------------------ + #' @description + #' Return a URL for a Dash asset. + #' @details + #' The `get_asset_url` method permits retrieval of an asset's URL given its filename. + #' For example, `app$get_asset_url('style.css')` should return `/assets/style.css` when + #' `assets_folder = 'assets'`. By default, the prefix is the value of `requests_pathname_prefix`, + #' but this is configurable via the `prefix` parameter. Note: this method will + #' present a warning and return `NULL` if the Dash app was not loaded via `source()` + #' if the `DASH_APP_PATH` environment variable is undefined. + #' @param asset_path Character. Specifies asset filename whose URL should be returned. + #' @param prefix Character. Specifies pathname prefix; default is to use `requests_pathname_prefix`. + #' @return Character. A string representing the URL to the asset. get_asset_url = function(asset_path, prefix = self$config$requests_pathname_prefix) { app_root_path <- Sys.getenv("DASH_APP_PATH") @@ -893,7 +756,22 @@ Dash <- R6::R6Class( # ------------------------------------------------------------------------ # return relative asset URLs # ------------------------------------------------------------------------ - + #' @description + #' Return relative asset paths for Dash assets. + #' @details + #' The `get_relative_path` method simplifies the handling of URLs and pathnames for apps + #' running locally and on a deployment server such as Dash Enterprise. It handles the prefix + #' for requesting assets similar to the `get_asset_url` method, but can also be used for URL handling + #' in components such as `dccLink` or `dccLocation`. For example, `app$get_relative_url("/page/")` + #' would return `/app/page/` for an app running on a deployment server. The path must be prefixed with + #' a `/`. + #' @param path Character. A path string prefixed with a leading `/` which directs + #' at a path or asset directory. + #' @param requests_pathname_prefix Character. The pathname prefix for the application when + #' deployed. Defaults to the environment variable set by the server, + #' or `""` if run locally. + #' @return Character. A string describing a relative path to a Dash app's asset + #' given a `path` and `requests_pathname_prefix`. get_relative_path = function(path, requests_pathname_prefix = self$config$requests_pathname_prefix) { asset = get_relative_path(requests_pathname = requests_pathname_prefix, path = path) return(asset) @@ -904,6 +782,19 @@ Dash <- R6::R6Class( # return relative asset URLs # ------------------------------------------------------------------------ + #' @description + #' Return a Dash asset path without its prefix. + #' @details + #' The `strip_relative_path` method simplifies the handling of URLs and pathnames for apps + #' running locally and on a deployment server such as Dash Enterprise. It acts almost opposite to the `get_relative_path` + #' method, by taking a `relative path` as an input, and returning the `path` stripped of the `requests_pathname_prefix`, + #' and any leading or trailing `/`. For example, a path string `/app/homepage/`, would be returned as + #' `homepage`. This is particularly useful for `dccLocation` URL routing. + #' @param path Character. A path string prefixed with a leading `/` which directs + #' at a path or asset directory. + #' @param requests_pathname_prefix Character. The pathname prefix for the app on + #' a deployed application. Defaults to the environment variable set by the server, + #' or `""` if run locally. strip_relative_path = function(path, requests_pathname_prefix = self$config$requests_pathname_prefix) { asset = strip_relative_path(requests_pathname = requests_pathname_prefix, path = path) return(asset) @@ -911,15 +802,102 @@ Dash <- R6::R6Class( # specify a custom index string # ------------------------------------------------------------------------ + #' @description + #' Specify a custom index string for a Dash application. + #' @details + #' The `index_string` method allows the specification of a custom index by changing + #' the default `HTML` template that is generated by the Dash UI. #' Meta tags, CSS, and JavaScript are some examples of features + #' that can be modified. This method will present a warning if your + #' HTML template is missing any necessary elements + #' and return an error if a valid index is not defined. The following interpolation keys are + #' currently supported: + #' \describe{ + #' \item{`{%metas%}`}{Optional - The registered meta tags.} + #' \item{`{%favicon%}`}{Optional - A favicon link tag if found in assets.} + #' \item{`{%css%}`}{Optional - Link tags to CSS resources.} + #' \item{`{%config%}`}{Required - Configuration details generated by Dash for the renderer.} + #' \item{`{%app_entry%}`}{Required - The container where Dash React components are rendered.} + #' \item{`{%scripts%}`}{Required - Script tags for collected dependencies.} + #' } + #' \describe{ + #' \item{Example of a basic HTML index string:}{ + #' \preformatted{ + #' " + #' + #' + #' \{\%meta_tags\%\} + #' \{\{%css\%\}\} + #' \{\%favicon\%\} + #' \{\%css_tags\%\} + #' + #' + #' \{\%app_entry\%\} + #' + #' + #' " + #' } + #' } + #' } + #' @param string Character; the index string template, with interpolation keys included. index_string = function(string) { - private$custom_index <- validate_keys(string) + assertthat::assert_that(is.character(string)) + private$custom_index <- validate_keys(string, is_template=TRUE) }, # ------------------------------------------------------------------------ # modify the templated variables by using the `interpolate_index` method. # ------------------------------------------------------------------------ + #' @description + #' Modify index template variables for a Dash application. + #' @details + #' With the `interpolate_index` method, one can pass a custom index with template string + #' variables that are already evaluated. Directly passing arguments to the `template_index` + #' has the effect of assigning them to variables present in the template. This is similar to the `index_string` method + #' but offers the ability to change the default components of the Dash index as seen in the example below. + #' @param template_index Character. A formatted string with the HTML index string. Defaults to the initial template. + #' @param ... Named list. The unnamed arguments can be passed as individual named lists corresponding to the components of the Dash HTML index. These include the same argument as those found in the `index_string()` template. + #' @examples + #' library(dash) + #' app <- Dash$new() + #' + #' sample_template <- " + #' + #' + #' {%meta_tags%} + #' Index Template Test + #' {%favicon%} + #' {%css_tags%} + #' + #' + #' {%app_entry%} + #' + #' + #' " + #' + + #' # this is the default configuration, but custom configurations + #' # are possible -- the structure of the "config" argument is + #' # a list, in which each element is a JSON key/value pair, when + #' # reformatted as JSON from the list: + #' # e.g. {"routes_pathname_prefix":"/", "ui":false} + #' config <- sprintf("", + #' jsonlite::toJSON(app$config, auto_unbox=TRUE)) + #' + #' app$interpolate_index( + #' sample_template, + #' metas = "", + #' app_entry = "
Loading...
", + #' config = config, + #' scripts = "") interpolate_index = function(template_index = private$template_index[[1]], ...) { - template = template_index + assertthat::assert_that(is.character(template_index)) + template <- template_index kwargs <- list(...) for (name in names(kwargs)) { @@ -927,7 +905,7 @@ Dash <- R6::R6Class( template = sub(key, kwargs[[name]], template) } - invisible(validate_keys(names(kwargs))) + invisible(validate_keys(names(kwargs), is_template=FALSE)) private$template_index <- template }, @@ -935,6 +913,11 @@ Dash <- R6::R6Class( # ------------------------------------------------------------------------ # specify a custom title # ------------------------------------------------------------------------ + #' @description + #' Set the title of the Dash app + #' @details + #' If no title is supplied, Dash for R will use 'Dash'. + #' @param string Character. A string representation of the name of the Dash application. title = function(string = "Dash") { assertthat::assert_that(is.character(string)) private$name <- string @@ -943,6 +926,51 @@ Dash <- R6::R6Class( # ------------------------------------------------------------------------ # convenient fiery wrappers # ------------------------------------------------------------------------ + #' @description + #' Start the Fiery HTTP server and run a Dash application. + #' @details + #' Starts the Fiery server in local mode and launches the Dash application. If a parameter can be set by an environment variable, that is listed too. Values provided here take precedence over environment variables. + #' . 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. + #' @param 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: `HOST`. + #' @param port Integer. Specifies the port number on which the server should listen (default is `8050`). Environment variable: `PORT`. + #' @param block Logical. Start the server while blocking console input? Default is `TRUE`. + #' @param showcase Logical. Load the Dash application into the default web browser when server starts? Default is `FALSE`. + #' @param 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 satisfied, the user is warned and the app opens in the default browser instead. Default is `FALSE`. + #' @param debug Logical. Enable/disable all the Dash developer tools (and the within-browser user interface for the callback graph visualizer and stack traces) unless overridden by the arguments or environment variables. Default is `FALSE` when called via `run_server`. For more information, please visit \url{https://dashr.plotly.com/devtools}. Environment variable: `DASH_DEBUG`. + #' @param dev_tools_ui Logical. Show Dash's developer tools UI? Default is `TRUE` if `debug == TRUE`, `FALSE` otherwise. Environment variable: `DASH_UI`. + #' @param 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`. + #' @param 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`. + #' @param 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`. + #' @param dev_tools_hot_reload_max_retry Integer. Maximum number of failed reload hash requests before failing and displaying a pop up. Default `0.5`. Environment variable: `DASH_HOT_RELOAD_MAX_RETRY`. + #' @param 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`. + #' @param dev_tools_prune_errors Logical. Reduce tracebacks such that only lines relevant to user code remain, stripping out Fiery and Dash references? Only available with debugging. `TRUE` by default, set to `FALSE` to see the complete traceback. Environment variable: `DASH_PRUNE_ERRORS`. + #' @param 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. + #' @param ... Additional arguments to pass to the `start` handler; see the [fiery] documentation for relevant examples. + #' @examples + #' if (interactive() && require(dash)) { + #' library(dashCoreComponents) + #' library(dashHtmlComponents) + #' library(dash) + #' + #' app <- Dash$new() + #' app$layout(htmlDiv( + #' list( + #' dccInput(id = "inputID", value = "initial value", type = "text"), + #' htmlDiv(id = "outputID") + #' ) + #' ) + #' ) + #' + #' app$callback(output = list(id="outputID", property="children"), + #' params = list(input(id="inputID", property="value"), + #' state(id="inputID", property="type")), + #' function(x, y) + #' sprintf("You've entered: '%s' into a '%s' input control", x, y) + #' ) + #' + #' app$run_server(showcase = TRUE) + #' } run_server = function(host = Sys.getenv('HOST', "127.0.0.1"), port = Sys.getenv('PORT', 8050), block = TRUE, @@ -1186,20 +1214,11 @@ Dash <- R6::R6Class( layout_ = NULL, layout_ids = NULL, layout_render = function() { - # assuming private$layout is either a function or a list of components... layout_ <- if (is.function(private$layout_)) private$layout_() else private$layout_ - - # accommodate functions that return a single component - if (is.component(layout_)) layout_ <- list(layout_) - - # make sure we are working with a list of components - layout_ <- lapply(layout_, private$componentify) - - # Put the list of components into a container div. I'm pretty sure dash - # requires the layout to be one component, but R folks are used to - # being able to supply "components" to ... - layout_ <- dashHtmlComponents::htmlDiv(children = layout_, id = layout_container_id()) - + + # ensure that the layout is a component, or a collection of components + layout_ <- private$componentify(layout_) + # store the layout as a (flattened) vector form since we query the # vector names several times to verify ID naming (among other things) layout_flat <- rapply(layout_, I) @@ -1210,19 +1229,23 @@ Dash <- R6::R6Class( if (!length(idx)) { warning( "No ids were found in the layout. ", - "Component ids are critical for targetting callbacks in your application", + "Component ids are critical for targeting callbacks in your application", call. = FALSE ) } - private$layout_ids <- as.character(layout_flat[idx]) - duped <- anyDuplicated(private$layout_ids) + layout_ids <- as.character(layout_flat[idx]) + duped <- anyDuplicated(layout_ids) > 0 + if (duped) { + duped_ids <- paste(layout_ids[duplicated(layout_ids)], collapse = ", ") + stop( - sprintf("layout ids must be unique -- the following id was duplicated: '%s'", private$layout_ids[duped]), + sprintf("layout ids must be unique -- please check the following list of duplicated ids: '%s'", duped_ids), call. = FALSE ) } + private$layout_ids <- layout_ids # load package-level HTML dependencies from attached pkgs metadataFns <- lapply(.packages(), getDashMetadata) metadataFns <- metadataFns[lengths(metadataFns) != 0] @@ -1707,23 +1730,3 @@ Dash <- R6::R6Class( } ) ) - -validate_dependency <- function(layout_, dependency) { - if (!is.layout(layout_)) stop("`layout` must be a dash layout object", call. = FALSE) - if (!is.dependency(dependency)) stop("`dependency` must be a dash dependency object", call. = FALSE) - - valid_props <- component_props_given_id(layout_, dependency$id) - - if (!isTRUE(dependency$property %in% valid_props)) { - warning( - sprintf( - "'%s' is not a valid property for the component with id '%s'. Try one of the following: '%s'", - dependency$property, dependency$id, paste(valid_props, collapse = "', '") - ), - call. = FALSE - ) - return(FALSE) - } - - TRUE -} diff --git a/R/imports.R b/R/imports.R index 8e2e8b68..1ebd2d73 100644 --- a/R/imports.R +++ b/R/imports.R @@ -11,4 +11,5 @@ #' @importFrom utils getFromNamespace #' @importFrom stats setNames #' @importFrom tools file_ext +#' @importFrom brotli brotli_compress NULL diff --git a/R/utils.R b/R/utils.R index 71e7baf3..5577ebc4 100644 --- a/R/utils.R +++ b/R/utils.R @@ -15,15 +15,6 @@ is.event <- function(x) is.dependency(x) && inherits(x, "event") # components (TODO: this should be exported by dashRtranspile!) is.component <- function(x) inherits(x, "dash_component") -# layout is really a special type of component -is.layout <- function(x) { - is.component(x) && identical(x[["props"]][["id"]], layout_container_id()) -} - -layout_container_id <- function() { - "_dashR-layout-container" -} - # retrieve the arguments of a callback function that are dash inputs callback_inputs <- function(func) { compact(lapply(formals(func), function(x) { @@ -338,8 +329,8 @@ insertIntoCallbackMap <- function(map, inputs, output, state, func, clientside_f clientside_function=clientside_function ) if (length(map) >= 2) { - ids <- lapply(names(map), function(x) dash:::getIdProps(x)$ids) - props <- lapply(names(map), function(x) dash:::getIdProps(x)$props) + ids <- lapply(names(map), function(x) getIdProps(x)$ids) + props <- lapply(names(map), function(x) getIdProps(x)$props) outputs_as_list <- mapply(paste, ids, props, sep=".", SIMPLIFY = FALSE) @@ -1341,10 +1332,13 @@ interpolate_str <- function(index_template, ...) { return(template) } -validate_keys <- function(string) { +validate_keys <- function(string, is_template) { required_keys <- c("app_entry", "config", "scripts") - keys_present <- vapply(required_keys, function(x) grepl(x, string), logical(1)) + if (is_template) + keys_present <- vapply(required_keys, function(x) grepl(x, string), logical(1)) + else + keys_present <- vapply(required_keys, function(x) x %in% string, logical(1)) if (!all(keys_present)) { stop(sprintf("Did you forget to include %s in your index string?", diff --git a/man/Dash.Rd b/man/Dash.Rd index 57b3823c..9d8365d2 100644 --- a/man/Dash.Rd +++ b/man/Dash.Rd @@ -3,183 +3,474 @@ \docType{class} \name{Dash} \alias{Dash} -\title{Create and configure a Dash app object} -\format{An \link[R6:R6Class]{R6::R6Class} generator object} -\usage{ -Dash +\title{R6 class representing a Dash application} +\format{ +An \link[R6:R6Class]{R6::R6Class} generator object } \description{ A framework for building analytical web applications, Dash offers a pleasant and productive development experience. No JavaScript required. } -\section{Constructor}{ - Dash$new( -name = NULL, -server = fiery::Fire$new(), -assets_folder = 'assets', -assets_url_path = '/assets', -eager_loading = FALSE, -assets_ignore = '', -serve_locally = TRUE, -meta_tags = NULL, -url_base_pathname = '/', -routes_pathname_prefix = NULL, -requests_pathname_prefix = NULL, -external_scripts = NULL, -external_stylesheets = NULL, -suppress_callback_exceptions = FALSE, -show_undo_redo = FALSE -) -} - -\section{Arguments}{ - -\tabular{lll}{ -\code{name} \tab \tab Character. The name of the Dash application (placed in the title -of the HTML page). DEPRECATED; please use \code{index_string()} or \code{interpolate_index()} instead.\cr -\code{server} \tab \tab The web server used to power the application. -Must be a \link[fiery:Fire]{fiery::Fire} object.\cr -\code{assets_folder} \tab \tab Character. A path, relative to the current working directory, -for extra files to be used in the browser. Default is "assets". All .js and +\examples{ + +## ------------------------------------------------ +## Method `Dash$interpolate_index` +## ------------------------------------------------ + +library(dash) +app <- Dash$new() + +sample_template <- " + + +{\%meta_tags\%} +Index Template Test +{\%favicon\%} +{\%css_tags\%} + + +{\%app_entry\%} +
+{\%config\%} +{\%scripts\%} +
+ +" + +# this is the default configuration, but custom configurations +# are possible -- the structure of the "config" argument is +# a list, in which each element is a JSON key/value pair, when +# reformatted as JSON from the list: +# e.g. {"routes_pathname_prefix":"/", "ui":false} +config <- sprintf("", + jsonlite::toJSON(app$config, auto_unbox=TRUE)) + +app$interpolate_index( + sample_template, + metas = "", + app_entry = "
Loading...
", + config = config, + scripts = "") + +## ------------------------------------------------ +## Method `Dash$run_server` +## ------------------------------------------------ + +if (interactive() && require(dash)) { + library(dashCoreComponents) + library(dashHtmlComponents) + library(dash) + + app <- Dash$new() + app$layout(htmlDiv( + list( + dccInput(id = "inputID", value = "initial value", type = "text"), + htmlDiv(id = "outputID") + ) + ) + ) + + app$callback(output = list(id="outputID", property="children"), + params = list(input(id="inputID", property="value"), + state(id="inputID", property="type")), + function(x, y) + sprintf("You've entered: '\%s' into a '\%s' input control", x, y) + ) + + app$run_server(showcase = TRUE) +} +} +\section{Public fields}{ +\if{html}{\out{
}} +\describe{ +\item{\code{server}}{A cloned (and modified) version of the \link[fiery:Fire]{fiery::Fire} object +provided to the \code{server} argument (various routes will be added which enable +Dash functionality).} + +\item{\code{config}}{A list of configuration options passed along to dash-renderer. +Users shouldn't need to alter any of these options unless they are +constructing their own authorization front-end or otherwise need to know +where the application is making API calls.} +} +\if{html}{\out{
}} +} +\section{Methods}{ +\subsection{Public methods}{ +\itemize{ +\item \href{#method-new}{\code{Dash$new()}} +\item \href{#method-layout_get}{\code{Dash$layout_get()}} +\item \href{#method-layout}{\code{Dash$layout()}} +\item \href{#method-react_version_set}{\code{Dash$react_version_set()}} +\item \href{#method-callback}{\code{Dash$callback()}} +\item \href{#method-callback_context}{\code{Dash$callback_context()}} +\item \href{#method-get_asset_url}{\code{Dash$get_asset_url()}} +\item \href{#method-get_relative_path}{\code{Dash$get_relative_path()}} +\item \href{#method-strip_relative_path}{\code{Dash$strip_relative_path()}} +\item \href{#method-index_string}{\code{Dash$index_string()}} +\item \href{#method-interpolate_index}{\code{Dash$interpolate_index()}} +\item \href{#method-title}{\code{Dash$title()}} +\item \href{#method-run_server}{\code{Dash$run_server()}} +\item \href{#method-clone}{\code{Dash$clone()}} +} +} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-new}{}}} +\subsection{Method \code{new()}}{ +Create and configure a Dash application. +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{Dash$new( + server = fiery::Fire$new(), + assets_folder = "assets", + assets_url_path = "/assets", + eager_loading = FALSE, + assets_ignore = "", + serve_locally = TRUE, + meta_tags = NULL, + url_base_pathname = "/", + routes_pathname_prefix = NULL, + requests_pathname_prefix = NULL, + external_scripts = NULL, + external_stylesheets = NULL, + compress = TRUE, + suppress_callback_exceptions = FALSE, + show_undo_redo = FALSE +)}\if{html}{\out{
}} +} + +\subsection{Arguments}{ +\if{html}{\out{
}} +\describe{ +\item{\code{server}}{\link[fiery:Fire]{fiery::Fire} object. The web server used to power the application.} + +\item{\code{assets_folder}}{Character. A path, relative to the current working directory, +for extra files to be used in the browser. All .js and .css files will be loaded immediately unless excluded by \code{assets_ignore}, -and other files such as images will be served if requested. Default is \code{assets}. \cr -\code{assets_url_path} \tab \tab Character. Specify the URL path for asset serving. Default is \code{assets}. \cr -\code{eager_loading} \tab \tab Logical. Controls whether asynchronous resources are prefetched (if \code{TRUE}) or loaded on-demand (if \code{FALSE}). \cr -\code{assets_ignore} \tab \tab Character. A regular expression, to match assets to omit from +and other files such as images will be served if requested. Default is \code{assets}.} + +\item{\code{assets_url_path}}{Character. Specify the URL path for asset serving. Default is \code{assets}.} + +\item{\code{eager_loading}}{Logical. Controls whether asynchronous resources are prefetched (if \code{TRUE}) or loaded on-demand (if \code{FALSE}).} + +\item{\code{assets_ignore}}{Character. A regular expression, to match assets to omit from immediate loading. Ignored files will still be served if specifically requested. You -cannot use this to prevent access to sensitive files. \cr -\code{serve_locally} \tab \tab Logical. Whether to serve HTML dependencies locally or -remotely (via URL).\cr -\code{compress} \tab \tab Logical. Whether to try to compress files and data served by Fiery. -By default, \code{brotli} is attempted first, then \code{gzip}, then the \code{deflate} algorithm, before falling -back to \code{identity}.\cr -\code{meta_tags} \tab \tab List of lists. HTML \code{}tags to be added to the index page. +cannot use this to prevent access to sensitive files.} + +\item{\code{serve_locally}}{Logical. Whether to serve HTML dependencies locally or +remotely (via URL).} + +\item{\code{meta_tags}}{List of lists. HTML \verb{} tags to be added to the index page. Each list element should have the attributes and values for one tag, eg: -\code{list(name = 'description', content = 'My App')}.\cr -\code{url_base_pathname} \tab \tab Character. A local URL prefix to use app-wide. Default is +\code{list(name = 'description', content = 'My App')}.} + +\item{\code{url_base_pathname}}{Character. A local URL prefix to use app-wide. Default is \code{/}. Both \code{requests_pathname_prefix} and \code{routes_pathname_prefix} default to \code{url_base_pathname}. -Environment variable is \code{DASH_URL_BASE_PATHNAME}.\cr -\code{routes_pathname_prefix} \tab \tab Character. A prefix applied to the backend routes. -Environment variable is \code{DASH_ROUTES_PATHNAME_PREFIX}.\cr -\code{requests_pathname_prefix} \tab \tab Character. A prefix applied to request endpoints -made by Dash's front-end. Environment variable is \code{DASH_REQUESTS_PATHNAME_PREFIX}.\cr -\code{external_scripts} \tab \tab List. An optional list of valid URLs from which -to serve JavaScript source for rendered pages.\cr -\code{external_stylesheets} \tab \tab List. An optional list of valid URLs from which -to serve CSS for rendered pages.\cr -\code{suppress_callback_exceptions} \tab \tab Logical. Whether to relay warnings about -possible layout mis-specifications when registering a callback.\cr -\code{show_undo_redo} \tab \tab Logical. Set to \code{TRUE} to enable undo and redo buttons for -stepping through the history of the app state. +Environment variable is \code{DASH_URL_BASE_PATHNAME}.} + +\item{\code{routes_pathname_prefix}}{Character. A prefix applied to the backend routes. +Environment variable is \code{DASH_ROUTES_PATHNAME_PREFIX}.} + +\item{\code{requests_pathname_prefix}}{Character. A prefix applied to request endpoints +made by Dash's front-end. Environment variable is \code{DASH_REQUESTS_PATHNAME_PREFIX}.} + +\item{\code{external_scripts}}{List. An optional list of valid URLs from which +to serve JavaScript source for rendered pages.} + +\item{\code{external_stylesheets}}{List. An optional list of valid URLs from which +to serve CSS for rendered pages.} + +\item{\code{compress}}{Logical. Whether to try to compress files and data served by Fiery. +By default, \code{brotli} is attempted first, then \code{gzip}, then the \code{deflate} algorithm, +before falling back to \code{identity}.} + +\item{\code{suppress_callback_exceptions}}{Logical. Whether to relay warnings about +possible layout mis-specifications when registering a callback.} + +\item{\code{show_undo_redo}}{Logical. Set to \code{TRUE} to enable undo and redo buttons for +stepping through the history of the app state.} } +\if{html}{\out{
}} +} +} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-layout_get}{}}} +\subsection{Method \code{layout_get()}}{ +Retrieves the Dash application layout. +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{Dash$layout_get(render = TRUE)}\if{html}{\out{
}} } -\section{Fields}{ - +\subsection{Arguments}{ +\if{html}{\out{
}} \describe{ -\item{\code{server}}{ -A cloned (and modified) version of the \link[fiery:Fire]{fiery::Fire} object -provided to the \code{server} argument (various routes will be added which enable -Dash functionality). -} -\item{\code{config}}{ -A list of configuration options passed along to dash-renderer. -Users shouldn't need to alter any of these options unless they are -constructing their own authorization front-end or otherwise need to know -where the application is making API calls. +\item{\code{render}}{Logical. If the layout is a function, should the function be +executed to return the layout? If \code{FALSE}, the function is returned as-is.} } +\if{html}{\out{
}} } +\subsection{Details}{ +If render is \code{TRUE}, and the layout is a function, +the result of the function (rather than the function itself) is returned. } -\section{Methods}{ +\subsection{Returns}{ +List or function, depending on the value of \code{render} (see above). +When returning an object of class \code{dash_component}, the default \code{print} +method for this class will display the corresponding pretty-printed JSON +representation of the object to the console. +} +} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-layout}{}}} +\subsection{Method \code{layout()}}{ +Set the Dash application layout (i.e., specify its user interface). +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{Dash$layout(value)}\if{html}{\out{
}} +} +\subsection{Arguments}{ +\if{html}{\out{
}} \describe{ -\item{\code{layout(...)}}{ -Set the layout (i.e., user interface). The layout should be either a +\item{\code{value}}{An object of the \code{dash_component} class, which provides +a component or collection of components, specified either as a Dash +component or a function that returns a Dash component.} +} +\if{html}{\out{
}} +} +\subsection{Details}{ +\code{value} should be either a collection of Dash components (e.g., \link{dccSlider}, \link{htmlDiv}, etc) or -a function which returns a collection of components. +a function which returns a collection of components. The collection +of components must be nested, such that any additional components +contained within \code{value} are passed solely as \code{children} of the top-level +component. In all cases, \code{value} must be a member of the \code{dash_component} +class. } -\item{\code{layout_get(render = TRUE)}}{ -Retrieves the layout. If render is \code{TRUE}, and the layout is a function, -the result of the function (rather than the function itself) is returned. + } -\item{\code{callback(output, params, func)}}{ -The \code{callback} method has three formal arguments: +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-react_version_set}{}}} +\subsection{Method \code{react_version_set()}}{ +Update the version of React in the list of dependencies served by dash-renderer to the client. +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{Dash$react_version_set(version)}\if{html}{\out{
}} +} + +\subsection{Arguments}{ +\if{html}{\out{
}} \describe{ -\item{output}{a named list including a component \code{id} and \code{property}} -\item{params}{an unnamed list of \link{input} and \link{state} statements, each with defined \code{id} and \code{property}} -\item{func}{any valid R function which generates \link{output} provided \link{input} and/or \link{state} arguments, -a character string containing valid JavaScript, or a call to \link{clientsideFunction} including \code{namespace} -and \code{function_name} arguments for a locally served JavaScript function} +\item{\code{version}}{Character. The version number of React to use.} } +\if{html}{\out{
}} +} +} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-callback}{}}} +\subsection{Method \code{callback()}}{ +Define a Dash callback. +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{Dash$callback(output, params, func)}\if{html}{\out{
}} +} + +\subsection{Arguments}{ +\if{html}{\out{
}} +\describe{ +\item{\code{output}}{Named list. The \code{output} argument provides the component \code{id} +and \code{property} which will be updated by the callback; a callback can +target one or more outputs (i.e. multiple outputs).} + +\item{\code{params}}{Unnamed list; provides \link{input} and \link{state} statements, each +with its own defined \code{id} and \code{property}.} + +\item{\code{func}}{Function; must return \link{output} provided \link{input} or \link{state} +arguments. \code{func} may be any valid R function, or a character string +containing valid JavaScript, or a call to \link{clientsideFunction}, +including \code{namespace} and \code{function_name} arguments for a locally served +JavaScript function.} +} +\if{html}{\out{
}} +} +\subsection{Details}{ +Describes a server or clientside callback relating the values of one or more +\code{output} items to one or more \code{input} items which will trigger the callback +when they change, and optionally \code{state} items which provide additional +information but do not trigger the callback directly. + The \code{output} argument defines which layout component property should receive the results (via the \link{output} object). The events that trigger the callback are then described by the \link{input} (and/or \link{state}) object(s) (which should reference layout components), which become -argument values for R callback handlers defined in \code{func}. Here \code{func} may -either be an anonymous R function, a JavaScript function provided as a -character string, or a call to \code{clientsideFunction()}, which describes a -locally served JavaScript function instead. The latter two methods define -a "clientside callback", which updates components without passing data to and -from the Dash backend. The latter may offer improved performance relative -to callbacks written purely in R. +argument values for R callback handlers defined in \code{func}. + +Here \code{func} may either be an anonymous R function, a JavaScript function +provided as a character string, or a call to \code{clientsideFunction()}, which +describes a locally served JavaScript function instead. The latter +two methods define a "clientside callback", which updates components +without passing data to and from the Dash backend. The latter may offer +improved performance relative to callbacks written purely in R. } -\item{\code{title("dash")}}{ -The title of the app. If no title is supplied, Dash for R will use 'dash'. + } -\item{\code{title("dash")}}{ -The title of the app. If no title is supplied, Dash for R will use 'dash'. +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-callback_context}{}}} +\subsection{Method \code{callback_context()}}{ +Request and return the calling context of a Dash callback. +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{Dash$callback_context()}\if{html}{\out{
}} } -\item{\code{callback_context()}}{ + +\subsection{Details}{ The \code{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. + +The \code{callback_context} method returns a list containing three elements: +\code{states}, \code{triggered}, \code{inputs}. The first and last of these correspond to +the values of \code{states} and \code{inputs} for the current invocation of the +callback, and \code{triggered} provides a list of changed properties. +} + +\subsection{Returns}{ +List comprising elements \code{states}, \code{triggered}, \code{inputs}. +} +} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-get_asset_url}{}}} +\subsection{Method \code{get_asset_url()}}{ +Return a URL for a Dash asset. +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{Dash$get_asset_url(asset_path, prefix = self$config$requests_pathname_prefix)}\if{html}{\out{
}} +} + +\subsection{Arguments}{ +\if{html}{\out{
}} +\describe{ +\item{\code{asset_path}}{Character. Specifies asset filename whose URL should be returned.} + +\item{\code{prefix}}{Character. Specifies pathname prefix; default is to use \code{requests_pathname_prefix}.} +} +\if{html}{\out{
}} } -\item{\code{get_asset_url(asset_path, prefix)}}{ +\subsection{Details}{ The \code{get_asset_url} method permits retrieval of an asset's URL given its filename. -For example, \code{app$get_asset_url('style.css')} should return \code{/assets/style.css} when +For example, \code{app$get_asset_url('style.css')} should return \verb{/assets/style.css} when \code{assets_folder = 'assets'}. By default, the prefix is the value of \code{requests_pathname_prefix}, but this is configurable via the \code{prefix} parameter. Note: this method will present a warning and return \code{NULL} if the Dash app was not loaded via \code{source()} if the \code{DASH_APP_PATH} environment variable is undefined. } -\item{\code{get_relative_path(path, requests_pathname_prefix)}}{ + +\subsection{Returns}{ +Character. A string representing the URL to the asset. +} +} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-get_relative_path}{}}} +\subsection{Method \code{get_relative_path()}}{ +Return relative asset paths for Dash assets. +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{Dash$get_relative_path( + path, + requests_pathname_prefix = self$config$requests_pathname_prefix +)}\if{html}{\out{
}} +} + +\subsection{Arguments}{ +\if{html}{\out{
}} +\describe{ +\item{\code{path}}{Character. A path string prefixed with a leading \code{/} which directs +at a path or asset directory.} + +\item{\code{requests_pathname_prefix}}{Character. The pathname prefix for the application when +deployed. Defaults to the environment variable set by the server, +or \code{""} if run locally.} +} +\if{html}{\out{
}} +} +\subsection{Details}{ The \code{get_relative_path} method simplifies the handling of URLs and pathnames for apps running locally and on a deployment server such as Dash Enterprise. It handles the prefix for requesting assets similar to the \code{get_asset_url} method, but can also be used for URL handling in components such as \code{dccLink} or \code{dccLocation}. For example, \code{app$get_relative_url("/page/")} -would return \code{/app/page/} for an app running on a deployment server. The path must be prefixed with +would return \verb{/app/page/} for an app running on a deployment server. The path must be prefixed with a \code{/}. +} + +\subsection{Returns}{ +Character. A string describing a relative path to a Dash app's asset +given a \code{path} and \code{requests_pathname_prefix}. +} +} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-strip_relative_path}{}}} +\subsection{Method \code{strip_relative_path()}}{ +Return a Dash asset path without its prefix. +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{Dash$strip_relative_path( + path, + requests_pathname_prefix = self$config$requests_pathname_prefix +)}\if{html}{\out{
}} +} + +\subsection{Arguments}{ +\if{html}{\out{
}} \describe{ -\item{path}{Character. A path string prefixed with a leading \code{/} which directs at a path or asset directory.} -\item{requests_pathname_prefix}{Character. The pathname prefix for the app on a deployed application. Defaults to the environment variable set by the server, or \code{""} if run locally.} +\item{\code{path}}{Character. A path string prefixed with a leading \code{/} which directs +at a path or asset directory.} + +\item{\code{requests_pathname_prefix}}{Character. The pathname prefix for the app on +a deployed application. Defaults to the environment variable set by the server, +or \code{""} if run locally.} } +\if{html}{\out{
}} } -\item{\code{strip_relative_path(path, requests_pathname_prefix)}}{ +\subsection{Details}{ The \code{strip_relative_path} method simplifies the handling of URLs and pathnames for apps -running locally and on a deployment server such as Dash Enterprise. It acts almost opposite the \code{get_relative_path} -method, by taking a \code{relative path} as an input, and returning the \code{path} stripped of the \code{requests_pathname_prefix}, -and any leading or trailing \code{/}. For example, a path string \code{/app/homepage/}, would be returned as +running locally and on a deployment server such as Dash Enterprise. It acts almost opposite to the \code{get_relative_path} +method, by taking a \verb{relative path} as an input, and returning the \code{path} stripped of the \code{requests_pathname_prefix}, +and any leading or trailing \code{/}. For example, a path string \verb{/app/homepage/}, would be returned as \code{homepage}. This is particularly useful for \code{dccLocation} URL routing. +} + +} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-index_string}{}}} +\subsection{Method \code{index_string()}}{ +Specify a custom index string for a Dash application. +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{Dash$index_string(string)}\if{html}{\out{
}} +} + +\subsection{Arguments}{ +\if{html}{\out{
}} \describe{ -\item{path}{Character. A path string prefixed with a leading \code{/} and \code{requests_pathname_prefix} which directs at a path or asset directory.} -\item{requests_pathname_prefix}{Character. The pathname prefix for the app on a deployed application. Defaults to the environment variable set by the server, or \code{""} if run locally.} +\item{\code{string}}{Character; the index string template, with interpolation keys included.} } +\if{html}{\out{
}} } -\item{\code{index_string(string)}}{ +\subsection{Details}{ The \code{index_string} method allows the specification of a custom index by changing -the default \code{HTML} template that is generated by the Dash UI. Meta tags, CSS, Javascript, -are some examples of features that can be modified. -This method will present a warning if your HTML template is missing any necessary elements +the default \code{HTML} template that is generated by the Dash UI. #' Meta tags, CSS, and JavaScript are some examples of features +that can be modified. This method will present a warning if your +HTML template is missing any necessary elements and return an error if a valid index is not defined. The following interpolation keys are currently supported: \describe{ -\item{\code{{\%metas\%}}}{Optional - The registered meta tags.} -\item{\code{{\%favicon\%}}}{Optional - A favicon link tag if found in assets.} -\item{\code{{\%css\%}}}{Optional - Link tags to css resources.} -\item{\code{{\%config\%}}}{Required - Config generated by dash for the renderer.} -\item{\code{{\%app_entry\%}}}{Required - The container where dash react components are rendered.} -\item{\code{{\%scripts\%}}}{Required - Collected dependencies scripts tags.} +\item{\verb{\{\%metas\%\}}}{Optional - The registered meta tags.} +\item{\verb{\{\%favicon\%\}}}{Optional - A favicon link tag if found in assets.} +\item{\verb{\{\%css\%\}}}{Optional - Link tags to CSS resources.} +\item{\verb{\{\%config\%\}}}{Required - Configuration details generated by Dash for the renderer.} +\item{\verb{\{\%app_entry\%\}}}{Required - The container where Dash React components are rendered.} +\item{\verb{\{\%scripts\%\}}}{Required - Script tags for collected dependencies.} } \describe{ \item{Example of a basic HTML index string:}{ @@ -200,73 +491,212 @@ currently supported: " - } + } } } } -\item{\code{interpolate_index(template_index, ...)}}{ -With the \code{interpolate_index} method, we can pass a custom index with template string -variables that are already evaluated. We can directly pass arguments to the \code{template_index} -by assigning them to variables present in the template. This is similar to the \code{index_string} method -but offers the ability to change the default components of the Dash index as seen in the example below: -\preformatted{ - app$interpolate_index( - template_index, - metas = "", - renderer = renderer, - config = config) - } -\describe{ -\item{template_index}{Character. A formatted string with the HTML index string. Defaults to the initial template} -\item{...}{Named List. The unnamed arguments can be passed as individual named lists corresponding to the components -of the Dash html index. These include the same arguments as those found in the \code{index_string()} template.} + } +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-interpolate_index}{}}} +\subsection{Method \code{interpolate_index()}}{ +Modify index template variables for a Dash application. +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{Dash$interpolate_index(template_index = private$template_index[[1]], ...)}\if{html}{\out{
}} } -\item{\code{run_server(host = Sys.getenv('HOST', "127.0.0.1"), port = Sys.getenv('PORT', 8050), block = TRUE, showcase = FALSE, ...)}}{ -The \code{run_server} method has 13 formal arguments, several of which are optional: + +\subsection{Arguments}{ +\if{html}{\out{
}} \describe{ -\item{host}{Character. A string specifying a valid IPv4 address for the Fiery server, or \code{0.0.0.0} to listen on all addresses. Default is \code{127.0.0.1} Environment variable: \code{HOST}.} -\item{port}{Integer. Specifies the port number on which the server should listen (default is \code{8050}). Environment variable: \code{PORT}.} -\item{block}{Logical. Start the server while blocking console input? Default is \code{TRUE}.} -\item{showcase}{Logical. Load the Dash application into the default web browser when server starts? Default is \code{FALSE}.} -\item{use_viewer}{Logical. Load the Dash application into RStudio's viewer pane? Requires that \code{host} is either \code{127.0.0.1} or \code{localhost}, and that Dash application is started within RStudio; if \code{use_viewer = TRUE} and these conditions are not satisfied, the user is warned and the app opens in the default browser instead. Default is \code{FALSE}.} -\item{debug}{Logical. Enable/disable all the dev tools unless overridden by the arguments or environment variables. Default is \code{FALSE} when called via \code{run_server}. Environment variable: \code{DASH_DEBUG}.} -\item{dev_tools_ui}{Logical. Show Dash's dev tools UI? Default is \code{TRUE} if \code{debug == TRUE}, \code{FALSE} otherwise. Environment variable: \code{DASH_UI}.} -\item{dev_tools_hot_reload}{Logical. Activate hot reloading when app, assets, and component files change? Default is \code{TRUE} if \code{debug == TRUE}, \code{FALSE} otherwise. Requires that the Dash application is loaded using \code{source()}, so that \code{srcref} attributes are available for executed code. Environment variable: \code{DASH_HOT_RELOAD}.} -\item{dev_tools_hot_reload_interval}{Numeric. Interval in seconds for the client to request the reload hash. Default is \code{3}. Environment variable: \code{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 \code{0.5}. Environment variable: \code{DASH_HOT_RELOAD_WATCH_INTERVAL}.} -\item{dev_tools_hot_reload_max_retry}{Integer. Maximum number of failed reload hash requests before failing and displaying a pop up. Default \code{0.5}. Environment variable: \code{DASH_HOT_RELOAD_MAX_RETRY}.} -\item{dev_tools_props_check}{Logical. Validate the types and values of Dash component properties? Default is \code{TRUE} if \code{debug == TRUE}, \code{FALSE} otherwise. Environment variable: \code{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. \code{TRUE} by default, set to \code{FALSE} to see the complete traceback. Environment variable: \code{DASH_PRUNE_ERRORS}.} -\item{dev_tools_silence_routes_logging}{Logical. Replace Fiery's default logger with \code{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, \code{host}/\code{port} set the \code{host}/\code{port} fields of the underlying \link[fiery:Fire]{fiery::Fire} web server. The \code{block}/\code{showcase}/\code{...} arguments are passed along -to the \code{ignite()} method of the \link[fiery:Fire]{fiery::Fire} server. +\item{\code{template_index}}{Character. A formatted string with the HTML index string. Defaults to the initial template.} + +\item{\code{...}}{Named list. The unnamed arguments can be passed as individual named lists corresponding to the components of the Dash HTML index. These include the same argument as those found in the \code{index_string()} template.} } +\if{html}{\out{
}} } +\subsection{Details}{ +With the \code{interpolate_index} method, one can pass a custom index with template string +variables that are already evaluated. Directly passing arguments to the \code{template_index} +has the effect of assigning them to variables present in the template. This is similar to the \code{index_string} method +but offers the ability to change the default components of the Dash index as seen in the example below. } -\examples{ -\dontrun{ -library(dashCoreComponents) -library(dashHtmlComponents) -library(dash) +\subsection{Examples}{ +\if{html}{\out{
}} +\preformatted{library(dash) app <- Dash$new() -app$layout( - dccInput(id = "inputID", value = "initial value", type = "text"), - htmlDiv(id = "outputID") -) -app$callback(output = list(id="outputID", property="children"), - params = list(input(id="inputID", property="value"), - state(id="inputID", property="type")), - function(x, y) - sprintf("You've entered: '\%s' into a '\%s' input control", x, y) -) +sample_template <- " + + +{\%meta_tags\%} +Index Template Test +{\%favicon\%} +{\%css_tags\%} + + +{\%app_entry\%} +
+{\%config\%} +{\%scripts\%} +
+ +" + +# this is the default configuration, but custom configurations +# are possible -- the structure of the "config" argument is +# a list, in which each element is a JSON key/value pair, when +# reformatted as JSON from the list: +# e.g. {"routes_pathname_prefix":"/", "ui":false} +config <- sprintf("", + jsonlite::toJSON(app$config, auto_unbox=TRUE)) + +app$interpolate_index( + sample_template, + metas = "", + app_entry = "
Loading...
", + config = config, + scripts = "") +} +\if{html}{\out{
}} + +} -app$run_server(showcase = TRUE) +} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-title}{}}} +\subsection{Method \code{title()}}{ +Set the title of the Dash app +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{Dash$title(string = "Dash")}\if{html}{\out{
}} } +\subsection{Arguments}{ +\if{html}{\out{
}} +\describe{ +\item{\code{string}}{Character. A string representation of the name of the Dash application.} +} +\if{html}{\out{
}} +} +\subsection{Details}{ +If no title is supplied, Dash for R will use 'Dash'. +} + +} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-run_server}{}}} +\subsection{Method \code{run_server()}}{ +Start the Fiery HTTP server and run a Dash application. +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{Dash$run_server( + host = Sys.getenv("HOST", "127.0.0.1"), + port = Sys.getenv("PORT", 8050), + block = TRUE, + showcase = FALSE, + use_viewer = FALSE, + dev_tools_prune_errors = TRUE, + debug = Sys.getenv("DASH_DEBUG"), + dev_tools_ui = Sys.getenv("DASH_UI"), + dev_tools_props_check = Sys.getenv("DASH_PROPS_CHECK"), + dev_tools_hot_reload = Sys.getenv("DASH_HOT_RELOAD"), + dev_tools_hot_reload_interval = Sys.getenv("DASH_HOT_RELOAD_INTERVAL"), + dev_tools_hot_reload_watch_interval = Sys.getenv("DASH_HOT_RELOAD_WATCH_INTERVAL)"), + dev_tools_hot_reload_max_retry = Sys.getenv("DASH_HOT_RELOAD_MAX_RETRY"), + dev_tools_silence_routes_logging = NULL, + ... +)}\if{html}{\out{
}} +} + +\subsection{Arguments}{ +\if{html}{\out{
}} +\describe{ +\item{\code{host}}{Character. A string specifying a valid IPv4 address for the Fiery server, or \verb{0.0.0.0} to listen on all addresses. Default is \verb{127.0.0.1} Environment variable: \code{HOST}.} + +\item{\code{port}}{Integer. Specifies the port number on which the server should listen (default is \code{8050}). Environment variable: \code{PORT}.} + +\item{\code{block}}{Logical. Start the server while blocking console input? Default is \code{TRUE}.} + +\item{\code{showcase}}{Logical. Load the Dash application into the default web browser when server starts? Default is \code{FALSE}.} + +\item{\code{use_viewer}}{Logical. Load the Dash application into RStudio's viewer pane? Requires that \code{host} is either \verb{127.0.0.1} or \code{localhost}, and that Dash application is started within RStudio; if \code{use_viewer = TRUE} and these conditions are not satisfied, the user is warned and the app opens in the default browser instead. Default is \code{FALSE}.} + +\item{\code{dev_tools_prune_errors}}{Logical. Reduce tracebacks such that only lines relevant to user code remain, stripping out Fiery and Dash references? Only available with debugging. \code{TRUE} by default, set to \code{FALSE} to see the complete traceback. Environment variable: \code{DASH_PRUNE_ERRORS}.} + +\item{\code{debug}}{Logical. Enable/disable all the Dash developer tools (and the within-browser user interface for the callback graph visualizer and stack traces) unless overridden by the arguments or environment variables. Default is \code{FALSE} when called via \code{run_server}. For more information, please visit \url{https://dashr.plotly.com/devtools}. Environment variable: \code{DASH_DEBUG}.} + +\item{\code{dev_tools_ui}}{Logical. Show Dash's developer tools UI? Default is \code{TRUE} if \code{debug == TRUE}, \code{FALSE} otherwise. Environment variable: \code{DASH_UI}.} + +\item{\code{dev_tools_props_check}}{Logical. Validate the types and values of Dash component properties? Default is \code{TRUE} if \code{debug == TRUE}, \code{FALSE} otherwise. Environment variable: \code{DASH_PROPS_CHECK}.} + +\item{\code{dev_tools_hot_reload}}{Logical. Activate hot reloading when app, assets, and component files change? Default is \code{TRUE} if \code{debug == TRUE}, \code{FALSE} otherwise. Requires that the Dash application is loaded using \code{source()}, so that \code{srcref} attributes are available for executed code. Environment variable: \code{DASH_HOT_RELOAD}.} + +\item{\code{dev_tools_hot_reload_interval}}{Numeric. Interval in seconds for the client to request the reload hash. Default is \code{3}. Environment variable: \code{DASH_HOT_RELOAD_INTERVAL}.} + +\item{\code{dev_tools_hot_reload_watch_interval}}{Numeric. Interval in seconds for the server to check asset and component folders for changes. Default \code{0.5}. Environment variable: \code{DASH_HOT_RELOAD_WATCH_INTERVAL}.} + +\item{\code{dev_tools_hot_reload_max_retry}}{Integer. Maximum number of failed reload hash requests before failing and displaying a pop up. Default \code{0.5}. Environment variable: \code{DASH_HOT_RELOAD_MAX_RETRY}.} + +\item{\code{dev_tools_silence_routes_logging}}{Logical. Replace Fiery's default logger with \code{dashLogger} instead (will remove all routes logging)? Enabled with debugging by default because hot reload hash checks generate a lot of requests.} + +\item{\code{...}}{Additional arguments to pass to the \code{start} handler; see the \link{fiery} documentation for relevant examples.} +} +\if{html}{\out{
}} +} +\subsection{Details}{ +Starts the Fiery server in local mode and launches the Dash application. If a parameter can be set by an environment variable, that is listed too. Values provided here take precedence over environment variables. +. If provided, \code{host}/\code{port} set the \code{host}/\code{port} fields of the underlying \link[fiery:Fire]{fiery::Fire} web server. The \code{block}/\code{showcase}/\code{...} arguments are passed along +to the \code{ignite()} method of the \link[fiery:Fire]{fiery::Fire} server. +} + +\subsection{Examples}{ +\if{html}{\out{
}} +\preformatted{if (interactive() && require(dash)) { + library(dashCoreComponents) + library(dashHtmlComponents) + library(dash) + + app <- Dash$new() + app$layout(htmlDiv( + list( + dccInput(id = "inputID", value = "initial value", type = "text"), + htmlDiv(id = "outputID") + ) + ) + ) + + app$callback(output = list(id="outputID", property="children"), + params = list(input(id="inputID", property="value"), + state(id="inputID", property="type")), + function(x, y) + sprintf("You've entered: '\%s' into a '\%s' input control", x, y) + ) + + app$run_server(showcase = TRUE) +} +} +\if{html}{\out{
}} + +} + +} +\if{html}{\out{
}} +\if{html}{\out{}} +\if{latex}{\out{\hypertarget{method-clone}{}}} +\subsection{Method \code{clone()}}{ +The objects of this class are cloneable with this method. +\subsection{Usage}{ +\if{html}{\out{
}}\preformatted{Dash$clone(deep = FALSE)}\if{html}{\out{
}} +} + +\subsection{Arguments}{ +\if{html}{\out{
}} +\describe{ +\item{\code{deep}}{Whether to make a deep clone.} +} +\if{html}{\out{
}} +} +} } -\keyword{datasets} diff --git a/man/clientsideFunction.Rd b/man/clientsideFunction.Rd index 771be8de..6a786a79 100644 --- a/man/clientsideFunction.Rd +++ b/man/clientsideFunction.Rd @@ -20,7 +20,7 @@ In this case Dash will inline your JavaScript automatically, without needing to \details{ With this signature, Dash's front-end will call \code{window.my_clientside_library.my_function} with the current values of the \code{value} properties of the components \code{my-input} and \code{another-input} whenever those values change. -Include a JavaScript file by including it your \code{assets/} folder. The file can be named anything but you'll need to +Include a JavaScript file by including it your \verb{assets/} folder. The file can be named anything but you'll need to assign the function's namespace to the \code{window}. For example, this file might look like: \preformatted{window.my_clientside_library = \{ my_function: function(input_value_1, input_value_2) \{ @@ -48,7 +48,7 @@ app$callback( output('output-clientside', 'children'), params=list(input('input', 'value')), "function (value) { - return 'Client says \\"' + value + '\\"'; + return 'Client says \"' + value + '\"'; }" )} } diff --git a/man/dash-package.Rd b/man/dash-package.Rd index f9e96e1e..b2a3b4db 100644 --- a/man/dash-package.Rd +++ b/man/dash-package.Rd @@ -5,7 +5,7 @@ \title{An Interface to the Dash Ecosystem for Authoring Reactive Web Applications} \description{ \if{html}{\figure{logo.png}{options: width=300 align='right'}} -Dash is a productive framework for building web applications in R or Python. +Dash is a productive framework for building web applications in R, Python, and Julia. Written on top of Fiery, Plotly.js, and React.js, Dash for R is ideal for building data visualization apps with highly custom user interfaces in pure R. It's particularly suited for anyone who works with data in R. diff --git a/tests/integration/dopsa/test_dopsa.py b/tests/integration/dopsa/test_dopsa.py new file mode 100644 index 00000000..3ec150c4 --- /dev/null +++ b/tests/integration/dopsa/test_dopsa.py @@ -0,0 +1,67 @@ +app = """ +library(dash) +library(dashCoreComponents) +library(dashHtmlComponents) + +app <- Dash$new() + +app$layout( + htmlDiv( + list( + dccInput(id='input-1-state', type='text', value='Montreal'), + dccInput(id='input-2-state', type='text', value='Canada'), + htmlButton(id='submit-button', n_clicks=0, children='Submit'), + htmlDiv(id='output-state'), + dccGraph(id='graph', + figure=list( + data=list( + list( + x=list(1, 2, 3), + y=list(4, 1, 2), + type='bar', + name='SF' + ), + list( + x=list(1, 2, 3), + y=list(2, 4, 5), + type='bar', + name='Montreal' + ) + ), + layout = list(title='Dash Data Visualization') + ) + ) + ) + ) +) + + +app$callback(output(id = 'output-state', property = 'children'), + list(input(id = 'submit-button', property = 'n_clicks'), + state(id = 'input-1-state', property = 'value'), + state(id = 'input-2-state', property = 'value')), + function(n_clicks, input1, input2) { + sprintf('The Button has been pressed \\'%s\\' times, Input 1 is \\'%s\\', and Input 2 is \\'%s\\'', n_clicks, input1, input2) # noqa:E501 + }) + +app$run_server() +""" + + +# pylint: disable=c0301 +def test_rsdp001_dopsa(dashr): + dashr.start_server(app) + dashr.wait_for_text_to_equal( + "#output-state", "The Button has been pressed '0' times, Input 1 is 'Montreal', and Input 2 is 'Canada'", timeout=1 # noqa:E501 + ) + input1 = dashr.find_element("#input-2-state") + dashr.clear_input(input1) + input1.send_keys("Quebec") + dashr.wait_for_text_to_equal( + "#input-2-state", "Quebec", timeout=1 + ) + dashr.find_element("#submit-button").click() + dashr.wait_for_text_to_equal( + "#output-state", "The Button has been pressed '1' times, Input 1 is 'Montreal', and Input 2 is 'Quebec'", timeout=1 # noqa:E501 + ) + dashr.percy_snapshot("rsdp001 - dopsa") diff --git a/tests/testthat/test-dash.R b/tests/testthat/test-dash.R index e7779dc2..b764dc23 100644 --- a/tests/testthat/test-dash.R +++ b/tests/testthat/test-dash.R @@ -12,15 +12,12 @@ test_that("Can set/get layout", { d <- Dash$new() div <- htmlDiv("A div", id = "An id") - - # rendered layout has a container div d$layout(div) + l <- d$layout_get() - expect_true(dash:::is.layout(l)) - expect_identical(l$props$children[[1]], div) - + # dynamic layouts - d$layout(function() { div }) + d$layout(function() { htmlDiv("A div", id = "An id") }) l2 <- d$layout_get() expect_identical(l, l2) expect_is(d$layout_get(render = FALSE), "function") diff --git a/tests/testthat/test-index.R b/tests/testthat/test-index.R index 7e88eeb9..76c05186 100644 --- a/tests/testthat/test-index.R +++ b/tests/testthat/test-index.R @@ -41,12 +41,3 @@ test_that("Omitting required template keys produces warnings", { "Did you forget to include config in your index string?" ) }) - -test_that("Customizing title using `name` produces a warning", { - - expect_warning( - Dash$new(name="Testing"), - "The supplied application title, 'Testing', should be set using the title() method, or passed via index_string() or interpolate_index(); it has been ignored, and 'Dash' will be used instead.", - fixed=TRUE - ) -}) diff --git a/tests/testthat/test-layout.R b/tests/testthat/test-layout.R index 4bc783ff..4844c69d 100644 --- a/tests/testthat/test-layout.R +++ b/tests/testthat/test-layout.R @@ -2,11 +2,21 @@ context("layout") test_that("layout IDs must be unique", { - app <- Dash$new() + app <- Dash$new() - expect_error( - app$layout(htmlA(id = "a"), htmlA(id = "a")), - "layout ids must be unique -- the following id was duplicated: 'a'" + expect_error( + app$layout(htmlDiv(list(htmlA(id = "a"), htmlA(id = "a"), htmlP(id="b"), htmlP(id="c"), htmlA(id="c")))), + "layout ids must be unique -- please check the following list of duplicated ids: 'a, c'" ) }) + +test_that("app$layout() only accepts components, or functions that return components", { + app <- Dash$new() + + expect_error( + app$layout(htmlA(id = "a"), htmlA(id = "a")), + 'unused argument (htmlA(id = "a"))', + fixed = TRUE) + +}) diff --git a/tests/testthat/test-wildcards.R b/tests/testthat/test-wildcards.R index 5f35ab22..6d1be1ec 100644 --- a/tests/testthat/test-wildcards.R +++ b/tests/testthat/test-wildcards.R @@ -21,7 +21,7 @@ test_that("HTML `data-*` & `aria-* ` wildcards are passed along to layout approp app <- Dash$new() app$layout(htmlDiv(id = "foo", `data-foo` = 1)) x <- app$layout_get() - expect_equal(x$props$children[[1]]$props$`data-foo`, 1) + expect_equal(x$props$`data-foo`, 1) }) # TODO: test NULL values aren't rendered on the HTML div