EVOLUTION-MANAGER
Edit File: req.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: Check for required values</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 req {shiny}"><tr><td>req {shiny}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Check for required values</h2> <h3>Description</h3> <p>Ensure that values are available ("truthy"–see Details) before proceeding with a calculation or action. If any of the given values is not truthy, the operation is stopped by raising a "silent" exception (not logged by Shiny, nor displayed in the Shiny app's UI). </p> <h3>Usage</h3> <pre> req(..., cancelOutput = FALSE) isTruthy(x) </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>...</code></td> <td> <p>Values to check for truthiness.</p> </td></tr> <tr valign="top"><td><code>cancelOutput</code></td> <td> <p>If <code>TRUE</code> and an output is being evaluated, stop processing as usual but instead of clearing the output, leave it in whatever state it happens to be in.</p> </td></tr> <tr valign="top"><td><code>x</code></td> <td> <p>An expression whose truthiness value we want to determine</p> </td></tr> </table> <h3>Details</h3> <p>The <code>req</code> function was designed to be used in one of two ways. The first is to call it like a statement (ignoring its return value) before attempting operations using the required values: </p> <pre>rv <- reactiveValues(state = FALSE) r <- reactive({ req(input$a, input$b, rv$state) # Code that uses input$a, input$b, and/or rv$state... })</pre> <p>In this example, if <code>r()</code> is called and any of <code>input$a</code>, <code>input$b</code>, and <code>rv$state</code> are <code>NULL</code>, <code>FALSE</code>, <code>""</code>, etc., then the <code>req</code> call will trigger an error that propagates all the way up to whatever render block or observer is executing. </p> <p>The second is to use it to wrap an expression that must be truthy: </p> <pre>output$plot <- renderPlot({ if (req(input$plotType) == "histogram") { hist(dataset()) } else if (input$plotType == "scatter") { qplot(dataset(), aes(x = x, y = y)) } })</pre> <p>In this example, <code>req(input$plotType)</code> first checks that <code>input$plotType</code> is truthy, and if so, returns it. This is a convenient way to check for a value "inline" with its first use. </p> <p><strong>Truthy and falsy values</strong> </p> <p>The terms "truthy" and "falsy" generally indicate whether a value, when coerced to a <code><a href="../../base/html/logical.html">base::logical()</a></code>, is <code>TRUE</code> or <code>FALSE</code>. We use the term a little loosely here; our usage tries to match the intuitive notions of "Is this value missing or available?", or "Has the user provided an answer?", or in the case of action buttons, "Has the button been clicked?". </p> <p>For example, a <code>textInput</code> that has not been filled out by the user has a value of <code>""</code>, so that is considered a falsy value. </p> <p>To be precise, <code>req</code> considers a value truthy <em>unless</em> it is one of: </p> <ul> <li><p><code>FALSE</code> </p> </li> <li><p><code>NULL</code> </p> </li> <li><p><code>""</code> </p> </li> <li><p>An empty atomic vector </p> </li> <li><p>An atomic vector that contains only missing values </p> </li> <li><p>A logical vector that contains all <code>FALSE</code> or missing values </p> </li> <li><p>An object of class <code>"try-error"</code> </p> </li> <li><p>A value that represents an unclicked <code><a href="actionButton.html">actionButton()</a></code> </p> </li></ul> <p>Note in particular that the value <code>0</code> is considered truthy, even though <code>as.logical(0)</code> is <code>FALSE</code>. </p> <p>If the built-in rules for truthiness do not match your requirements, you can always work around them. Since <code>FALSE</code> is falsy, you can simply provide the results of your own checks to <code>req</code>: </p> <p><code>req(input$a != 0)</code> </p> <p><strong>Using <code>req(FALSE)</code></strong> </p> <p>You can use <code>req(FALSE)</code> (i.e. no condition) if you've already performed all the checks you needed to by that point and just want to stop the reactive chain now. There is no advantange to this, except perhaps ease of readibility if you have a complicated condition to check for (or perhaps if you'd like to divide your condition into nested <code>if</code> statements). </p> <p><strong>Using <code>cancelOutput = TRUE</code></strong> </p> <p>When <code>req(..., cancelOutput = TRUE)</code> is used, the "silent" exception is also raised, but it is treated slightly differently if one or more outputs are currently being evaluated. In those cases, the reactive chain does not proceed or update, but the output(s) are left is whatever state they happen to be in (whatever was their last valid state). </p> <p>Note that this is always going to be the case if this is used inside an output context (e.g. <code>output$txt <- ...</code>). It may or may not be the case if it is used inside a non-output context (e.g. <code><a href="reactive.html">reactive()</a></code>, <code><a href="observe.html">observe()</a></code> or <code><a href="observeEvent.html">observeEvent()</a></code>) — depending on whether or not there is an <code>output$...</code> that is triggered as a result of those calls. See the examples below for concrete scenarios. </p> <h3>Value</h3> <p>The first value that was passed in. </p> <h3>Examples</h3> <pre> ## Only run examples in interactive R sessions if (interactive()) { ui <- fluidPage( textInput('data', 'Enter a dataset from the "datasets" package', 'cars'), p('(E.g. "cars", "mtcars", "pressure", "faithful")'), hr(), tableOutput('tbl') ) server <- function(input, output) { output$tbl <- renderTable({ ## to require that the user types something, use: `req(input$data)` ## but better: require that input$data is valid and leave the last ## valid table up req(exists(input$data, "package:datasets", inherits = FALSE), cancelOutput = TRUE) head(get(input$data, "package:datasets", inherits = FALSE)) }) } shinyApp(ui, server) } </pre> <hr /><div style="text-align: center;">[Package <em>shiny</em> version 1.5.0 <a href="00Index.html">Index</a>]</div> </body></html>