devmode: Shiny Developer Mode

Description Usage Arguments Functions Avoiding direct dependency on shiny Examples

View source: R/devmode.R

Description

\lifecycle

experimental

Developer Mode enables a number of options() to make a developer's life easier, like enabling non-minified JS and printing messages about deprecated functions and options.

Please see the function descriptions for more details.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
devmode(
  devmode = getOption("shiny.devmode", TRUE),
  verbose = getOption("shiny.devmode.verbose", TRUE)
)

in_devmode()

with_devmode(devmode, code, verbose = getOption("shiny.devmode.verbose", TRUE))

devmode_inform(
  message,
  .frequency = "regularly",
  .frequency_id = message,
  .file = stderr(),
  ...
)

register_devmode_option(name, devmode_message = NULL, devmode_default = NULL)

get_devmode_option(
  name,
  default = NULL,
  devmode_default = missing_arg(),
  devmode_message = missing_arg()
)

Arguments

devmode

Logical value which should be set to TRUE to enable Shiny Developer Mode

verbose

Logical value which should be set to TRUE display Shiny Developer messages

code

Code to execute with the temporary Dev Mode options set

message

Developer Mode message to be sent to rlang::inform()

.frequency

Frequency of the Developer Mode message used with rlang::inform(). Defaults to once every 8 hours.

.frequency_id

rlang::inform() message identifier. Defaults to message.

.file

Output connection for rlang::inform(). Defaults to stderr()

...

Parameters passed to rlang::inform()

name

Name of option to look for in options()

devmode_message

Message to display once every 8 hours when utilizing the devmode_default value. If devmode_message is missing, the registered devmode_message value be used.

devmode_default

Default value to return if in_devmode() returns TRUE. For get_devmode_option(), if devmode_default is missing, the registered devmode_default value will be used.

Functions

Avoiding direct dependency on shiny

The methods explained in this help file act independently from the rest of Shiny but are included to provide blue prints for your own packages. If your package already has (or is willing to take) a dependency on Shiny, we recommend using the exported Shiny methods for consistent behavior. Note that if you use exported Shiny methods, it will cause the Shiny package to load. This may be undesirable if your code will be used in (for example) R Markdown documents that do not have a Shiny runtime (runtime: shiny).

If your package can not take a dependency on Shiny, we recommending re-implementing these two functions:

  1. in_devmode():

    This function should return TRUE if getOption("shiny.devmode") is set. In addition, we strongly recommend that it also checks to make sure testthat is not testing.

    in_devmode <- function() {
      isTRUE(getOption("shiny.devmode", FALSE)) &&
        !identical(Sys.getenv("TESTTHAT"), "true")
    }
    
  2. get_devmode_option(name, default, devmode_default, devmode_message):

    This function is similar to getOption(name, default), but when the option is not set, the default value changes depending on the Dev Mode. get_devmode_option() should be implemented as follows:

    • If not in Dev Mode:

      • Return getOption(name, default).

    • If in Dev Mode:

      • Get the global option getOption(name) value.

      • If the global option value is set:

        • Return the value.

      • If the global option value is not set:

        • Notify the developer that the Dev Mode default value will be used.

        • Return the Dev Mode default value.

    When notifying the developer that the default value has changed, we strongly recommend displaying a message (devmode_message) to stderr() once every 8 hours using rlang::inform(). This will keep the author up to date as to which Dev Mode options are being altered. To allow developers a chance to disable Dev Mode messages, the message should be skipped if getOption("shiny.devmode.verbose", TRUE) is not TRUE.

    get_devmode_option <- function(name, default = NULL, devmode_default, devmode_message) {
      if (!in_devmode()) {
        # Dev Mode disabled, act like `getOption()`
        return(getOption(name, default = default))
      }
    
      # Dev Mode enabled, update the default value for `getOption()`
      getOption(name, default = {
        # Notify developer
        if (
          !missing(devmode_message) &&
          !is.null(devmode_message) &&
          getOption("shiny.devmode.verbose", TRUE)
        ) {
          rlang::inform(
            message = devmode_message,
            .frequency = "regularly",
            .frequency_id = devmode_message,
            .file = stderr()
          )
        }
    
        # Return Dev Mode default value `devmode_default`
        devmode_default
      })
    }
    

The remaining functions in this file are used for author convenience and are not recommended for all reimplementation situations.

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
# Enable Shiny Developer mode
devmode()

in_devmode() # TRUE/FALSE?

# Execute code in a temporary shiny dev mode
with_devmode(TRUE, in_devmode()) # TRUE

# Ex: Within shiny, we register the option "shiny.minified"
#   to default to `FALSE` when in Dev Mode
## Not run: register_devmode_option(
  "shiny.minified",
  devmode_message = paste0(
    "Using full shiny javascript file. ",
    "To use the minified version, call `options(shiny.minified = TRUE)`"
  ),
  devmode_default = FALSE
)
## End(Not run)

# Used within `shiny::runApp(launch.browser)`
get_devmode_option("shiny.minified", TRUE) # TRUE if Dev mode is off
is_minified <- with_devmode(TRUE, {
  get_devmode_option("shiny.minified", TRUE)
})
is_minified # FALSE

shiny documentation built on Jan. 26, 2021, 1:06 a.m.