EVOLUTION-MANAGER
Edit File: observeEvent.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: Event handler</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link rel="stylesheet" type="text/css" href="R.css" /> </head><body> <table width="100%" summary="page for observeEvent {shiny}"><tr><td>observeEvent {shiny}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Event handler</h2> <h3>Description</h3> <p>Respond to "event-like" reactive inputs, values, and expressions. </p> <h3>Usage</h3> <pre> 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, ignoreInit = FALSE, once = FALSE ) eventReactive( eventExpr, valueExpr, event.env = parent.frame(), event.quoted = FALSE, value.env = parent.frame(), value.quoted = FALSE, label = NULL, domain = getDefaultReactiveDomain(), ignoreNULL = TRUE, ignoreInit = FALSE ) </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>eventExpr</code></td> <td> <p>A (quoted or unquoted) expression that represents the event; this can be a simple reactive value like <code>input$click</code>, a call to a reactive expression like <code>dataset()</code>, or even a complex expression inside curly braces</p> </td></tr> <tr valign="top"><td><code>handlerExpr</code></td> <td> <p>The expression to call whenever <code>eventExpr</code> is invalidated. This should be a side-effect-producing action (the return value will be ignored). It will be executed within an <code><a href="isolate.html">isolate()</a></code> scope.</p> </td></tr> <tr valign="top"><td><code>event.env</code></td> <td> <p>The parent environment for <code>eventExpr</code>. By default, this is the calling environment.</p> </td></tr> <tr valign="top"><td><code>event.quoted</code></td> <td> <p>Is the <code>eventExpr</code> expression quoted? By default, this is <code>FALSE</code>. This is useful when you want to use an expression that is stored in a variable; to do so, it must be quoted with <code>quote()</code>.</p> </td></tr> <tr valign="top"><td><code>handler.env</code></td> <td> <p>The parent environment for <code>handlerExpr</code>. By default, this is the calling environment.</p> </td></tr> <tr valign="top"><td><code>handler.quoted</code></td> <td> <p>Is the <code>handlerExpr</code> expression quoted? By default, this is <code>FALSE</code>. This is useful when you want to use an expression that is stored in a variable; to do so, it must be quoted with <code>quote()</code>.</p> </td></tr> <tr valign="top"><td><code>label</code></td> <td> <p>A label for the observer or reactive, useful for debugging.</p> </td></tr> <tr valign="top"><td><code>suspended</code></td> <td> <p>If <code>TRUE</code>, start the observer in a suspended state. If <code>FALSE</code> (the default), start in a non-suspended state.</p> </td></tr> <tr valign="top"><td><code>priority</code></td> <td> <p>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.</p> </td></tr> <tr valign="top"><td><code>domain</code></td> <td> <p>See <a href="domains.html">domains</a>.</p> </td></tr> <tr valign="top"><td><code>autoDestroy</code></td> <td> <p>If <code>TRUE</code> (the default), the observer will be automatically destroyed when its domain (if any) ends.</p> </td></tr> <tr valign="top"><td><code>ignoreNULL</code></td> <td> <p>Whether the action should be triggered (or value calculated, in the case of <code>eventReactive</code>) when the input is <code>NULL</code>. See Details.</p> </td></tr> <tr valign="top"><td><code>ignoreInit</code></td> <td> <p>If <code>TRUE</code>, then, when this <code>observeEvent</code> is first created/initialized, ignore the <code>handlerExpr</code> (the second argument), whether it is otherwise supposed to run or not. The default is <code>FALSE</code>. See Details.</p> </td></tr> <tr valign="top"><td><code>once</code></td> <td> <p>Whether this <code>observeEvent</code> should be immediately destroyed after the first time that the code in <code>handlerExpr</code> is run. This pattern is useful when you want to subscribe to a event that should only happen once.</p> </td></tr> <tr valign="top"><td><code>valueExpr</code></td> <td> <p>The expression that produces the return value of the <code>eventReactive</code>. It will be executed within an <code><a href="isolate.html">isolate()</a></code> scope.</p> </td></tr> <tr valign="top"><td><code>value.env</code></td> <td> <p>The parent environment for <code>valueExpr</code>. By default, this is the calling environment.</p> </td></tr> <tr valign="top"><td><code>value.quoted</code></td> <td> <p>Is the <code>valueExpr</code> expression quoted? By default, this is <code>FALSE</code>. This is useful when you want to use an expression that is stored in a variable; to do so, it must be quoted with <code>quote()</code>.</p> </td></tr> </table> <h3>Details</h3> <p>Shiny's reactive programming framework is primarily designed for calculated values (reactive expressions) and side-effect-causing actions (observers) that respond to <em>any</em> 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 <code><a href="actionButton.html">actionButton()</a></code>, 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 <em>event</em>. </p> <p>These situations demand a more imperative, "event handling" style of programming that is possible–but not particularly intuitive–using the reactive programming primitives <code><a href="observe.html">observe()</a></code> and <code><a href="isolate.html">isolate()</a></code>. <code>observeEvent</code> and <code>eventReactive</code> provide straightforward APIs for event handling that wrap <code>observe</code> and <code>isolate</code>. </p> <p>Use <code>observeEvent</code> whenever you want to <em>perform an action</em> in response to an event. (Note that "recalculate a value" does not generally count as performing an action–see <code>eventReactive</code> 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. </p> <p>Use <code>eventReactive</code> to create a <em>calculated value</em> that only updates in response to an event. This is just like a normal <a href="reactive.html">reactive expression</a> except it ignores all the usual invalidations that come from its reactive dependencies; it only invalidates in response to the given event. </p> <h3>Value</h3> <p><code>observeEvent</code> returns an observer reference class object (see <code><a href="observe.html">observe()</a></code>). <code>eventReactive</code> returns a reactive expression object (see <code><a href="reactive.html">reactive()</a></code>). </p> <h3>ignoreNULL and ignoreInit</h3> <p>Both <code>observeEvent</code> and <code>eventReactive</code> take an <code>ignoreNULL</code> parameter that affects behavior when the <code>eventExpr</code> evaluates to <code>NULL</code> (or in the special case of an <code><a href="actionButton.html">actionButton()</a></code>, <code>0</code>). In these cases, if <code>ignoreNULL</code> is <code>TRUE</code>, then an <code>observeEvent</code> will not execute and an <code>eventReactive</code> will raise a silent <a href="validate.html">validation</a> 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 <code>ignoreNULL=FALSE</code> is desirable if you want to initially perform the action/calculation and just let the user re-initiate it (like a "Recalculate" button). </p> <p>Likewise, both <code>observeEvent</code> and <code>eventReactive</code> also take in an <code>ignoreInit</code> argument. By default, both of these will run right when they are created (except if, at that moment, <code>eventExpr</code> evaluates to <code>NULL</code> and <code>ignoreNULL</code> is <code>TRUE</code>). But when responding to a click of an action button, it may often be useful to set <code>ignoreInit</code> to <code>TRUE</code>. For example, if you're setting up an <code>observeEvent</code> for a dynamically created button, then <code>ignoreInit = TRUE</code> will guarantee that the action (in <code>handlerExpr</code>) will only be triggered when the button is actually clicked, instead of also being triggered when it is created/initialized. Similarly, if you're setting up an <code>eventReactive</code> that responds to a dynamically created button used to refresh some data (then returned by that <code>eventReactive</code>), then you should use <code style="white-space: pre;">eventReactive([...], ignoreInit = TRUE)</code> if you want to let the user decide if/when they want to refresh the data (since, depending on the app, this may be a computationally expensive operation). </p> <p>Even though <code>ignoreNULL</code> and <code>ignoreInit</code> can be used for similar purposes they are independent from one another. Here's the result of combining these: </p> <dl> <dt><code>ignoreNULL = TRUE</code> and <code>ignoreInit = FALSE</code></dt><dd> <p>This is the default. This combination means that <code>handlerExpr</code>/ <code>valueExpr</code> will run every time that <code>eventExpr</code> is not <code>NULL</code>. If, at the time of the creation of the <code>observeEvent</code>/<code>eventReactive</code>, <code>eventExpr</code> happens to <em>not</em> be <code>NULL</code>, then the code runs. </p> </dd> <dt><code>ignoreNULL = FALSE</code> and <code>ignoreInit = FALSE</code></dt><dd> <p>This combination means that <code>handlerExpr</code>/<code>valueExpr</code> will run every time no matter what. </p> </dd> <dt><code>ignoreNULL = FALSE</code> and <code>ignoreInit = TRUE</code></dt><dd> <p>This combination means that <code>handlerExpr</code>/<code>valueExpr</code> will <em>not</em> run when the <code>observeEvent</code>/<code>eventReactive</code> is created (because <code>ignoreInit = TRUE</code>), but it will run every other time. </p> </dd> <dt><code>ignoreNULL = TRUE</code> and <code>ignoreInit = TRUE</code></dt><dd> <p>This combination means that <code>handlerExpr</code>/<code>valueExpr</code> will <em>not</em> run when the <code>observeEvent</code>/<code>eventReactive</code> is created (because <code>ignoreInit = TRUE</code>). After that, <code>handlerExpr</code>/<code>valueExpr</code> will run every time that <code>eventExpr</code> is not <code>NULL</code>. </p> </dd> </dl> <h3>See Also</h3> <p><code><a href="actionButton.html">actionButton()</a></code> </p> <h3>Examples</h3> <pre> ## Only run this example in interactive R sessions if (interactive()) { ## App 1: Sample usage shinyApp( 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() }) } ) ## App 2: Using `once` shinyApp( ui = basicPage( actionButton("go", "Go")), server = function(input, output, session) { observeEvent(input$go, { print(paste("This will only be printed once; all", "subsequent button clicks won't do anything")) }, once = TRUE) } ) ## App 3: Using `ignoreInit` and `once` shinyApp( ui = basicPage(actionButton("go", "Go")), server = function(input, output, session) { observeEvent(input$go, { insertUI("#go", "afterEnd", actionButton("dynamic", "click to remove")) # set up an observer that depends on the dynamic # input, so that it doesn't run when the input is # created, and only runs once after that (since # the side effect is remove the input from the DOM) observeEvent(input$dynamic, { removeUI("#dynamic") }, ignoreInit = TRUE, once = TRUE) }) } ) } </pre> <hr /><div style="text-align: center;">[Package <em>shiny</em> version 1.5.0 <a href="00Index.html">Index</a>]</div> </body></html>