observeEvent: Event handler

Description

Respond to "event-like" reactive inputs, values, and expressions.

Usage

observeEvent(eventExpr, handlerExpr, event.env = parent.frame(), event.quoted = FALSE, handler.env = parent.frame(), handler.quoted = FALSE, label = NULL, suspended = FALSE, priority = 0, domain = getDefaultReactiveDomain(), autoDestroy = TRUE, ignoreNULL = TRUE)
eventReactive(eventExpr, valueExpr, event.env = parent.frame(), event.quoted = FALSE, value.env = parent.frame(), value.quoted = FALSE, label = NULL, domain = getDefaultReactiveDomain(), ignoreNULL = TRUE)

Arguments

eventExpr

A (quoted or unquoted) expression that represents the event; this can be a simple reactive value like input$click, a call to a reactive expression like dataset(), or even a complex expression inside curly braces

handlerExpr

The expression to call whenever eventExpr is invalidated. This should be a side-effect-producing action (the return value will be ignored). It will be executed within an isolate scope.

event.env

The parent environment for eventExpr. By default, this is the calling environment.

event.quoted

Is the eventExpr expression quoted? By default, this is FALSE. This is useful when you want to use an expression that is stored in a variable; to do so, it must be quoted with quote().

handler.env

The parent environment for handlerExpr. By default, this is the calling environment.

handler.quoted

Is the handlerExpr expression quoted? By default, this is FALSE. This is useful when you want to use an expression that is stored in a variable; to do so, it must be quoted with quote().

label

A label for the observer or reactive, useful for debugging.

suspended

If TRUE, start the observer in a suspended state. If FALSE (the default), start in a non-suspended state.

priority

An integer or numeric that controls the priority with which this observer should be executed. An observer with a given priority level will always execute sooner than all observers with a lower priority level. Positive, negative, and zero values are allowed.

domain

See domains.

autoDestroy

If TRUE (the default), the observer will be automatically destroyed when its domain (if any) ends.

ignoreNULL

Whether the action should be triggered (or value calculated, in the case of eventReactive) when the input is NULL. See Details.

valueExpr

The expression that produces the return value of the eventReactive. It will be executed within an isolate scope.

value.env

The parent environment for valueExpr. By default, this is the calling environment.

value.quoted

Is the valueExpr expression quoted? By default, this is FALSE. This is useful when you want to use an expression that is stored in a variable; to do so, it must be quoted with quote().

Value

observeEvent returns an observer reference class object (see observe). eventReactive returns a reactive expression object (see reactive).

Details

Shiny's reactive programming framework is primarily designed for calculated values (reactive expressions) and side-effect-causing actions (observers) that respond to any of their inputs changing. That's often what is desired in Shiny apps, but not always: sometimes you want to wait for a specific action to be taken from the user, like clicking an actionButton, before calculating an expression or taking an action. A reactive value or expression that is used to trigger other calculations in this way is called an event.

These situations demand a more imperative, "event handling" style of programming that is possible--but not particularly intuitive--using the reactive programming primitives observe and isolate. observeEvent and eventReactive provide straightforward APIs for event handling that wrap observe and isolate.

Use observeEvent whenever you want to perform an action in response to an event. (Note that "recalculate a value" does not generally count as performing an action--see eventReactive for that.) The first argument is the event you want to respond to, and the second argument is a function that should be called whenever the event occurs.

Use eventReactive to create a calculated value that only updates in response to an event. This is just like a normal reactive expression except it ignores all the usual invalidations that come from its reactive dependencies; it only invalidates in response to the given event.

Both observeEvent and eventReactive take an ignoreNULL parameter that affects behavior when the eventExpr evaluates to NULL (or in the special case of an actionButton, 0). In these cases, if ignoreNULL is TRUE, then an observeEvent will not execute and an eventReactive will raise a silent validation error. This is useful behavior if you don't want to do the action or calculation when your app first starts, but wait for the user to initiate the action first (like a "Submit" button); whereas ignoreNULL=FALSE is desirable if you want to initially perform the action/calculation and just let the user re-initiate it (like a "Recalculate" button).

Examples

Run this code

## Only run this example in interactive R sessions
if (interactive()) {
  ui <- fluidPage(
    column(4,
      numericInput("x", "Value", 5),
      br(),
      actionButton("button", "Show")
    ),
    column(8, tableOutput("table"))
  )
  server <- function(input, output) {
    # Take an action every time button is pressed;
    # here, we just print a message to the console
    observeEvent(input$button, {
      cat("Showing", input$x, "rows\n")
    })
    # Take a reactive dependency on input$button, but
    # not on any of the stuff inside the function
    df <- eventReactive(input$button, {
      head(cars, input$x)
    })
    output$table <- renderTable({
      df()
    })
  }
  shinyApp(ui=ui, server=server)
}