Dash: Create and configure a Dash app object

Description

A framework for building analytical web applications, Dash offers a pleasant and productive development experience. No JavaScript required.

Usage

Dash

Format

An R6::R6Class generator object

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 )

Arguments

`name`		Character. The name of the Dash application (placed in the title of the HTML page). DEPRECATED; please use `index_string()` or `interpolate_index()` instead.
`server`		The web server used to power the application. Must be a fiery::Fire object.
`assets_folder`		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`.
`assets_url_path`		Character. Specify the URL path for asset serving. Default is `assets`.
`eager_loading`		Logical. Controls whether asynchronous resources are prefetched (if `TRUE`) or loaded on-demand (if `FALSE`).
`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.
`serve_locally`		Logical. Whether to serve HTML dependencies locally or remotely (via URL).
`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`.
`meta_tags`		List of lists. HTML `<meta>`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')`.
`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`.
`routes_pathname_prefix`		Character. A prefix applied to the backend routes. Environment variable is `DASH_ROUTES_PATHNAME_PREFIX`.
`requests_pathname_prefix`		Character. A prefix applied to request endpoints made by Dash's front-end. Environment variable is `DASH_REQUESTS_PATHNAME_PREFIX`.
`external_scripts`		List. An optional list of valid URLs from which to serve JavaScript source for rendered pages.
`external_stylesheets`		List. An optional list of valid URLs from which to serve CSS for rendered pages.
`suppress_callback_exceptions`		Logical. Whether to relay warnings about possible layout mis-specifications when registering a callback.

Fields

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).
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.

Methods

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.

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.

callback(output, params, func)

The callback method has three formal arguments:

output: a named list including a component id and property
params: an unnamed list of input and state statements, each with defined id and property
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.

title("dash")

The title of the app. If no title is supplied, Dash for R will use 'dash'.

title("dash")

The title of the app. If no title is supplied, Dash for R will use 'dash'.

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.

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.

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 /.

path: Character. A path string prefixed with a leading / which directs at a path or asset directory.
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(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.

path: Character. A path string prefixed with a leading / and requests_pathname_prefix which directs at a path or asset directory.
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.

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:

{%metas%}: Optional - The registered meta tags.
{%favicon%}: Optional - A favicon link tag if found in assets.
{%css%}: Optional - Link tags to css resources.
{%config%}: Required - Config generated by dash for the renderer.
{%app_entry%}: Required - The container where dash react components are rendered.
{%scripts%}: Required - Collected dependencies scripts tags.

Example of a basic HTML index string:

"<!DOCTYPE html>
<html>
 <head>
  {%meta_tags%}
     <title>{{
     {%favicon%}
     {%css_tags%}
 </head>
  <body>
    {%app_entry%}
    <footer>
     {%config%}
     {%scripts%}
    </footer>
  </body>
</html>"

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:

    app$interpolate_index(
      template_index,
      metas = "<meta_charset='UTF-8'/>",
      renderer = renderer,
      config = config)

template_index: Character. A formatted string with the HTML index string. Defaults to the initial template
...: 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.

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:

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.
port: Integer. Specifies the port number on which the server should listen (default is 8050). Environment variable: PORT.
block: Logical. Start the server while blocking console input? Default is TRUE.
showcase: Logical. Load the Dash application into the default web browser when server starts? Default is FALSE.
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.
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.
dev_tools_ui: Logical. Show Dash's dev tools UI? Default is TRUE if debug == TRUE, FALSE otherwise. Environment variable: DASH_UI.
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.
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.
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.
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.
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.
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.
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

Run this code

# NOT RUN {
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)
# }
# NOT RUN {
# }

Run the code above in your browser using DataLab