rename alert to alertPanel

Merge remote-tracking branch 'origin/master' into feature/alerts

Conflicts:
	NEWS
	R/bootstrap.R

NAMESPACE

@@ -27,6 +27,7 @@ export(HTML)
 export(a)
 export(actionButton)
 export(addResourcePath)
+export(alertPanel)
 export(animationOptions)
 export(basicPage)
 export(bootstrapPage)

NEWS

@@ -39,6 +39,9 @@ shiny 0.8.0.99
 * Added `icon()` function for embedding icons from the 
 [http://fontawesome.io/](font awesome) icon library 
 
+* Added `alertPanel()` function for showing user alerts.
+
+
 shiny 0.8.0
 --------------------------------------------------------------------------------
 

R/bootstrap.R

@@ -1440,6 +1440,78 @@ downloadLink <- function(outputId, label="Download", class=NULL) {
 }
 
 
+#' Create an alert panel
+#' 
+#' Create an alert panel with warning, error, or informational content. Alert's use a
+#' distinct background color designed to gain the user's attention immediately.
+#' 
+#' @param ... Contents of the alert panel. Often a simple text value however arbitrary
+#'   formatting and UI elements can be included.
+#' @param type Type of alert (determines the background color of the panel). Can
+#'   be "warning", "error", "success", or "info" (defaults to "warning").
+#' @param closeable Allow the user to dismiss the alert panel (useful for dynamic 
+#'   alerts).
+#' @param block Provide extra padding around the alert's content (useful when 
+#'   there is a lot of alert text).
+#'   
+#' @details You can use \code{\link{renderUI}} to show an alert dynamically in
+#'   response to specific conditions (see example below).
+#'   
+#' @examples
+#' \dontrun{
+#' # Specifying a uiOutput placeholder for a dynamic alert in ui.R:
+#' mainPanel(
+#'   uiOutput("alert")
+#' )
+#' 
+#' # Generating the dynamic alert in server.R:
+#' output$alert <- renderUI(alertPanel("This might take a while..."))
+#' }
+#' 
+#' # Change the type of alert to error (red background)
+#' alertPanel("Invalid range specified", type = "error")
+#' 
+#' # Use a heading 
+#' alertPanel(h4("Warning"), 
+#'            "The uploaded dataset is very large and ",
+#'            "will take a long time to process")
+#'  
+#' @export
+alertPanel <- function(...,
+                       type = c("warning", "error", "success", "info"),
+                       closeable = TRUE,
+                       block = FALSE) {
+  
+  # build alert class
+  alertClass <- "alert"
+  
+  # add type qualifier if necessary
+  type <- match.arg(type)
+  if (type != "warning")
+    alertClass <- paste0(alertClass, " alert-", type)
+  
+  # add block style if requested
+  if (block)
+    alertClass <- paste(alertClass, "alert-block")
+  
+  # build alert div. since this is typically created in a reactiveUI block we
+  # need to generate some uniqueness so that the client re-renders the UI
+  # (otherwise it would ignore it when the same alert message is sent 
+  # consecutively). we use the data-unique attribute to do this.
+  alertDiv <- div(class = alertClass, 
+                  `data-unique` = runif(1, min=1, max=1000))
+  if (closeable) {
+    closeButton <- tags$button(type = "button",
+                               class = "close",
+                               `data-dismiss` = "alert",
+                               HTML("&times;"))
+    alertDiv <- tagAppendChild(alertDiv, closeButton) 
+  }
+  alertDiv <- tagAppendChildren(alertDiv, list = list(...))
+  alertDiv
+}
+
+
 #' Create an icon
 #' 
 #' Create an icon for use within a page. Icons can appear on their own,
@@ -1505,6 +1577,7 @@ iconClass <- function(icon) {
     icon[[2]]$attribs$class  
 }
 
+
 #' Validate proper CSS formatting of a unit
 #' 
 #' @param x The unit to validate. Will be treated as a number of pixels if a 

inst/examples/07_widgets/server.R

@@ -18,8 +18,17 @@ shinyServer(function(input, output) {
     summary(dataset)
   })
   
-  # Show the first "n" observations
+  # Show the first "n" observations. Show an alert warning if more
+  # than 25 observations are requested
   output$view <- renderTable({
-    head(datasetInput(), n = input$obs)
+    
+    # determine the number of observations and warn if there are
+    # more than 25 requested
+    n = input$obs
+    if (n > 25)
+      output$alert <- renderUI(alertPanel("That's a lot of observations!"))
+    
+    # return the requested number of observations
+    head(datasetInput(), n)
   })
 })

inst/examples/07_widgets/ui.R

@@ -28,12 +28,15 @@ shinyUI(pageWithSidebar(
   
   # 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.
+  # an additional header above each output section. Also note the 
+  # placeholder for an alert to warn the user when the requested number
+  # of observations is large.
   mainPanel(
     h4("Summary"),
     verbatimTextOutput("summary"),
     
     h4("Observations"),
+    uiOutput("alert"),
     tableOutput("view")
   )
 ))

man/alertPanel.Rd

@@ -0,0 +1,53 @@
+\name{alertPanel}
+\alias{alertPanel}
+\title{Create an alert panel}
+\usage{
+  alertPanel(...,
+    type = c("warning", "error", "success", "info"),
+    closeable = TRUE, block = FALSE)
+}
+\arguments{
+  \item{...}{Contents of the alert panel. Often a simple
+  text value however arbitrary formatting and UI elements
+  can be included.}
+
+  \item{type}{Type of alert (determines the background
+  color of the panel). Can be "warning", "error",
+  "success", or "info" (defaults to "warning").}
+
+  \item{closeable}{Allow the user to dismiss the alert
+  panel (useful for dynamic alerts).}
+
+  \item{block}{Provide extra padding around the alert's
+  content (useful when there is a lot of alert text).}
+}
+\description{
+  Create an alert panel with warning, error, or
+  informational content. Alert's use a distinct background
+  color designed to gain the user's attention immediately.
+}
+\details{
+  You can use \code{\link{renderUI}} to show an alert
+  dynamically in response to specific conditions (see
+  example below).
+}
+\examples{
+\dontrun{
+# Specifying a uiOutput placeholder for a dynamic alert in ui.R:
+mainPanel(
+  uiOutput("alert")
+)
+
+# Generating the dynamic alert in server.R:
+output$alert <- renderUI(alertPanel("This might take a while..."))
+}
+
+# Change the type of alert to error (red background)
+alertPanel("Invalid range specified", type = "error")
+
+# Use a heading
+alertPanel(h4("Warning"),
+           "The uploaded dataset is very large and ",
+           "will take a long time to process")
+}
+