Improve documentation for submitButton and change 07_widgets example to use an action button

R/input-submit.R

@@ -4,6 +4,54 @@
 #' button do not automatically update their outputs when inputs change,
 #' rather they wait until the user explicitly clicks the submit button.
 #'
+#' @section Warning:
+#' Submit buttons are very particular shiny objects. One the weirdest
+#' things about them is they have no IDs, and there is no way to regulate
+#' which inputs they should (and which ones they should not) be applied
+#' to. This means they are very unwieldy for anything but the simplest
+#' apps (see the example below). For example, having \emph{two} submit
+#' buttons in the same app will probably not do what you'd expect because
+#' submit buttons are not isolated in any way, so activating any of the
+#' two buttons will cause all inputs in the app to fire. Another problem
+#' with submit buttons is that dynamically created submit buttons (for
+#' example, with \code{\link{renderUI}} or \code{\link{insertUI}}) will
+#' not work.
+#'
+#' For all of these reasons, \strong{our general reccomendation is to
+#' avoid submit buttons} and
+#' \href{http://shiny.rstudio.com/articles/action-buttons.html#pattern-2---delay-reactions}{
+#' use action buttons instead when you want to delay a reaction}. Any
+#' code that uses a submit button can be converted to code that uses an
+#' action button instead (while the reverse is almost never true). So,
+#' if you find your app getting increasingly complicated, opt for using
+#' an action button (or more since there is no problem with multiple
+#' action buttons in the same app). The link above shows an example of
+#' a delayed reaction using an action button. For another example, the
+#' code below converts the example in this page (at the bottom) to an
+#' equivalent app using an action button (using the same pattern
+#' described in the link above):
+#'
+#' \preformatted{
+#' shinyApp(
+#'   ui = basicPage(
+#'     numericInput("num", label = "Make changes", value = 1),
+#'     actionButton("update" ,"Update View", icon("refresh"),
+#'                  class = "btn btn-primary"),
+#'     helpText("When you click the button above, you should see",
+#'              "the output below update to reflect the value you",
+#'              "entered at the top:"),
+#'     verbatimTextOutput("value")
+#'   ),
+#'   server = function(input, output) {
+#'     currentValue <- eventReactive(input$update, {
+#'       input$num
+#'     }, ignoreNULL = FALSE)
+#'
+#'     output$value <- renderPrint({ currentValue() })
+#'   }
+#' )
+#' }
+#'
 #' @param text Button caption
 #' @param icon Optional \code{\link{icon}} to appear on the button
 #' @param width The width of the button, e.g. \code{'400px'}, or \code{'100\%'};
@@ -13,8 +61,26 @@
 #' @family input elements
 #'
 #' @examples
-#' submitButton("Update View")
-#' submitButton("Update View", icon("refresh"))
+#' if (interactive()) {
+#'
+#' shinyApp(
+#'   ui = basicPage(
+#'     numericInput("num", label = "Make changes", value = 1),
+#'     submitButton("Update View", icon("refresh")),
+#'     helpText("When you click the button above, you should see",
+#'              "the output below update to reflect the value you",
+#'              "entered at the top:"),
+#'     verbatimTextOutput("value")
+#'   ),
+#'   server = function(input, output) {
+#'
+#'     # submit buttons do not have a value of their own,
+#'     # they control when the app accesses values of other widgets.
+#'     # input$num is the value of the number widget.
+#'     output$value <- renderPrint({ input$num })
+#'   }
+#' )
+#' }
 #' @export
 submitButton <- function(text = "Apply Changes", icon = NULL, width = NULL) {
   div(

inst/examples/07_widgets/Readme.md

@@ -1 +1 @@
-This example demonstrates some additional widgets included in Shiny, such as `helpText` and `submitButton`. The latter is used to delay rendering output until the user explicitly requests it.
+This example demonstrates some additional widgets included in Shiny, such as `helpText` and `actionButton`. The latter is used to delay rendering output until the user explicitly requests it (a construct which also introduces two important server functions, `eventReactive` and `isolate`).

inst/examples/07_widgets/server.R

@@ -1,26 +1,32 @@
 library(shiny)
 library(datasets)
 
-# Define server logic required to summarize and view the 
+# Define server logic required to summarize and view the
 # selected dataset
 function(input, output) {
-
-  # Return the requested dataset
-  datasetInput <- reactive({
+
+  # Return the requested dataset. Note that we use `eventReactive()`
+  # here, which takes a dependency on input$update (the action
+  # button), so that the output is only updated when the user
+  # clicks the button.
+  datasetInput <- eventReactive(input$update, {
     switch(input$dataset,
            "rock" = rock,
            "pressure" = pressure,
            "cars" = cars)
-  })
-  
+  }, ignoreNULL = FALSE)
+
   # Generate a summary of the dataset
   output$summary <- renderPrint({
     dataset <- datasetInput()
     summary(dataset)
   })
-
-  # Show the first "n" observations
+
+  # Show the first "n" observations. The use of `isolate()` here
+  # is necessary because we don't want the table to update
+  # whenever input$obs changes (only when the user clicks the
+  # action button).
   output$view <- renderTable({
-    head(datasetInput(), n = input$obs)
+    head(datasetInput(), n = isolate(input$obs))
   })
 }

inst/examples/07_widgets/ui.R

@@ -2,40 +2,40 @@ library(shiny)
 
 # Define UI for dataset viewer application
 fluidPage(
-  
+
   # Application title.
   titlePanel("More Widgets"),
-  
+
   # Sidebar with controls to select a dataset and specify the
   # number of observations to view. The helpText function is
   # also used to include clarifying text. Most notably, the
-  # inclusion of a submitButton defers the rendering of output
+  # inclusion of an actionButton defers the rendering of output
   # until the user explicitly clicks the button (rather than
   # doing it immediately when inputs change). This is useful if
   # the computations required to render output are inordinately
   # time-consuming.
   sidebarLayout(
     sidebarPanel(
-      selectInput("dataset", "Choose a dataset:", 
+      selectInput("dataset", "Choose a dataset:",
                   choices = c("rock", "pressure", "cars")),
-      
+
       numericInput("obs", "Number of observations to view:", 10),
-      
+
       helpText("Note: while the data view will show only the specified",
                "number of observations, the summary will still be based",
                "on the full dataset."),
-      
-      submitButton("Update View")
+
+      actionButton("update", "Update View")
     ),
-    
+
     # Show a summary of the dataset and an HTML table with the
     # requested number of observations. Note the use of the h4
     # function to provide an additional header above each output
     # section.
     mainPanel(
       h4("Summary"),
       verbatimTextOutput("summary"),
-      
+
       h4("Observations"),
       tableOutput("view")
     )