1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
|
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/utils.R
\name{validate}
\alias{need}
\alias{validate}
\title{Validate input values and other conditions}
\usage{
validate(..., errorClass = character(0))
need(expr, message = paste(label, "must be provided"), label)
}
\arguments{
\item{...}{A list of tests. Each test should equal \code{NULL} for success,
\code{FALSE} for silent failure, or a string for failure with an error
message.}
\item{errorClass}{A CSS class to apply. The actual CSS string will have
\code{shiny-output-error-} prepended to this value.}
\item{expr}{An expression to test. The condition will pass if the expression
meets the conditions spelled out in Details.}
\item{message}{A message to convey to the user if the validation condition is
not met. If no message is provided, one will be created using \code{label}.
To fail with no message, use \code{FALSE} for the message.}
\item{label}{A human-readable name for the field that may be missing. This
parameter is not needed if \code{message} is provided, but must be provided
otherwise.}
}
\description{
For an output rendering function (e.g. \code{\link{renderPlot}()}), you may
need to check that certain input values are available and valid before you
can render the output. \code{validate} gives you a convenient mechanism for
doing so.
}
\details{
The \code{validate} function takes any number of (unnamed) arguments, each of
which represents a condition to test. If any of the conditions represent
failure, then a special type of error is signaled which stops execution. If
this error is not handled by application-specific code, it is displayed to
the user by Shiny.
An easy way to provide arguments to \code{validate} is to use the \code{need}
function, which takes an expression and a string; if the expression is
considered a failure, then the string will be used as the error message. The
\code{need} function considers its expression to be a failure if it is any of
the following:
\itemize{
\item{\code{FALSE}}
\item{\code{NULL}}
\item{\code{""}}
\item{An empty atomic vector}
\item{An atomic vector that contains only missing values}
\item{A logical vector that contains all \code{FALSE} or missing values}
\item{An object of class \code{"try-error"}}
\item{A value that represents an unclicked \code{\link{actionButton}}}
}
If any of these values happen to be valid, you can explicitly turn them to
logical values. For example, if you allow \code{NA} but not \code{NULL}, you
can use the condition \code{!is.null(input$foo)}, because \code{!is.null(NA)
== TRUE}.
If you need validation logic that differs significantly from \code{need}, you
can create other validation test functions. A passing test should return
\code{NULL}. A failing test should return an error message as a
single-element character vector, or if the failure should happen silently,
\code{FALSE}.
Because validation failure is signaled as an error, you can use
\code{validate} in reactive expressions, and validation failures will
automatically propagate to outputs that use the reactive expression. In
other words, if reactive expression \code{a} needs \code{input$x}, and two
outputs use \code{a} (and thus depend indirectly on \code{input$x}), it's
not necessary for the outputs to validate \code{input$x} explicitly, as long
as \code{a} does validate it.
}
\examples{
## Only run examples in interactive R sessions
if (interactive()) {
options(device.ask.default = FALSE)
ui <- fluidPage(
checkboxGroupInput('in1', 'Check some letters', choices = head(LETTERS)),
selectizeInput('in2', 'Select a state', choices = state.name),
plotOutput('plot')
)
server <- function(input, output) {
output$plot <- renderPlot({
validate(
need(input$in1, 'Check at least one letter!'),
need(input$in2 != '', 'Please choose a state.')
)
plot(1:10, main = paste(c(input$in1, input$in2), collapse = ', '))
})
}
shinyApp(ui, server)
}
}
|
