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
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
|
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/bind-event.R
\name{bindEvent}
\alias{bindEvent}
\title{Make an object respond only to specified reactive events}
\usage{
bindEvent(
x,
...,
ignoreNULL = TRUE,
ignoreInit = FALSE,
once = FALSE,
label = NULL
)
}
\arguments{
\item{x}{An object to wrap so that is triggered only when a the specified
event occurs.}
\item{...}{One or more expressions that represents the event; this can be a
simple reactive value like \code{input$click}, a call to a reactive expression
like \code{dataset()}, or even a complex expression inside curly braces. If
there are multiple expressions in the \code{...}, then it will take a dependency
on all of them.}
\item{ignoreNULL}{Whether the action should be triggered (or value
calculated) when the input is \code{NULL}. See Details.}
\item{ignoreInit}{If \code{TRUE}, then, when the eventified object is first
created/initialized, don't trigger the action or (compute the value). The
default is \code{FALSE}. See Details.}
\item{once}{Used only for observers. Whether this \code{observer} should be
immediately destroyed after the first time that the code in the observer is
run. This pattern is useful when you want to subscribe to a event that
should only happen once.}
\item{label}{A label for the observer or reactive, useful for debugging.}
}
\description{
Modify an object to respond to "event-like" reactive inputs, values, and
expressions. \code{bindEvent()} can be used with reactive expressions, render
functions, and observers. The resulting object takes a reactive dependency on
the \code{...} arguments, and not on the original object's code. This can, for
example, be used to make an observer execute only when a button is pressed.
\code{bindEvent()} was added in Shiny 1.6.0. When it is used with \code{\link[=reactive]{reactive()}} and
\code{\link[=observe]{observe()}}, it does the same thing as \code{\link[=eventReactive]{eventReactive()}} and
\code{\link[=observeEvent]{observeEvent()}}. However, \code{bindEvent()} is more flexible: it can be combined
with \code{\link[=bindCache]{bindCache()}}, and it can also be used with \code{render} functions (like
\code{\link[=renderText]{renderText()}} and \code{\link[=renderPlot]{renderPlot()}}).
}
\section{Details}{
Shiny's reactive programming framework is primarily designed for calculated
values (reactive expressions) and side-effect-causing actions (observers)
that respond to \emph{any} 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{\link[=actionButton]{actionButton()}}, 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 \emph{event}.
These situations demand a more imperative, "event handling" style of
programming that is possible--but not particularly intuitive--using the
reactive programming primitives \code{\link[=observe]{observe()}} and \code{\link[=isolate]{isolate()}}. \code{bindEvent()}
provides a straightforward API for event handling that wraps \code{observe} and
\code{isolate}.
The \code{...} arguments are captured as expressions and combined into an
\strong{event expression}. When this event expression is invalidated (when its
upstream reactive inputs change), that is an \strong{event}, and it will cause
the original object's code to execute.
Use \code{bindEvent()} with \code{observe()} whenever you want to \emph{perform an action}
in response to an event. (This does the same thing as \code{\link[=observeEvent]{observeEvent()}},
which was available in Shiny prior to version 1.6.0.) Note that
"recalculate a value" does not generally count as performing an action --
use \code{\link[=reactive]{reactive()}} for that.
Use \code{bindEvent()} with \code{reactive()} to create a \emph{calculated value} that
only updates in response to an event. This is just like a normal \link[=reactive]{reactive expression} except it ignores all the usual invalidations that
come from its reactive dependencies; it only invalidates in response to the
given event. (This does the same thing as \code{\link[=eventReactive]{eventReactive()}}, which was
available in Shiny prior to version 1.6.0.)
\code{bindEvent()} is often used with \code{\link[=bindCache]{bindCache()}}.
}
\section{ignoreNULL and ignoreInit}{
\code{bindEvent()} takes an \code{ignoreNULL} parameter that affects behavior when
the event expression evaluates to \code{NULL} (or in the special case of an
\code{\link[=actionButton]{actionButton()}}, \code{0}). In these cases, if \code{ignoreNULL} is \code{TRUE}, then it
will raise a silent \link[=validate]{validation} 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} is desirable if you want to initially
perform the action/calculation and just let the user re-initiate it (like a
"Recalculate" button).
\code{bindEvent()} also takes an \code{ignoreInit} argument. By default, reactive
expressions and observers will run on the first reactive flush after they
are created (except if, at that moment, the event expression evaluates to
\code{NULL} and \code{ignoreNULL} is \code{TRUE}). But when responding to a click of an
action button, it may often be useful to set \code{ignoreInit} to \code{TRUE}. For
example, if you're setting up an observer to respond to a dynamically
created button, then \code{ignoreInit = TRUE} will guarantee that the action
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 a reactive that responds to a dynamically created button used to
refresh some data (which is then returned by that \code{reactive}), then you
should use \code{reactive(...) \%>\% bindEvent(..., ignoreInit = TRUE)} 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).
Even though \code{ignoreNULL} and \code{ignoreInit} can be used for similar purposes
they are independent from one another. Here's the result of combining
these:
\describe{
\item{\code{ignoreNULL = TRUE} and \code{ignoreInit = FALSE}}{
This is the default. This combination means that reactive/observer code
will run every time that event expression is not
\code{NULL}. If, at the time of creation, the event expression happens
to \emph{not} be \code{NULL}, then the code runs.
}
\item{\code{ignoreNULL = FALSE} and \code{ignoreInit = FALSE}}{
This combination means that reactive/observer code will
run every time no matter what.
}
\item{\code{ignoreNULL = FALSE} and \code{ignoreInit = TRUE}}{
This combination means that reactive/observer code will
\emph{not} run at the time of creation (because \code{ignoreInit = TRUE}),
but it will run every other time.
}
\item{\code{ignoreNULL = TRUE} and \code{ignoreInit = TRUE}}{
This combination means that reactive/observer code will
\emph{not} at the time of creation (because \code{ignoreInit = TRUE}).
After that, the reactive/observer code will run every time that
the event expression is not \code{NULL}.
}
}
}
\section{Types of objects}{
\code{bindEvent()} can be used with reactive expressions, observers, and shiny
render functions.
When \code{bindEvent()} is used with \code{reactive()}, it creates a new reactive
expression object.
When \code{bindEvent()} is used with \code{observe()}, it alters the observer in
place. It can only be used with observers which have not yet executed.
}
\section{Combining events and caching}{
In many cases, it makes sense to use \code{bindEvent()} along with
\code{bindCache()}, because they each can reduce the amount of work done on the
server. For example, you could have \link{sliderInput}s \code{x} and \code{y} and a
\code{reactive()} that performs a time-consuming operation with those values.
Using \code{bindCache()} can speed things up, especially if there are multiple
users. But it might make sense to also not do the computation until the
user sets both \code{x} and \code{y}, and then clicks on an \link{actionButton} named
\code{go}.
To use both caching and events, the object should first be passed to
\code{bindCache()}, then \code{bindEvent()}. For example:
\if{html}{\out{<div class="sourceCode">}}\preformatted{r <- reactive(\{
Sys.sleep(2) # Pretend this is an expensive computation
input$x * input$y
\}) \%>\%
bindCache(input$x, input$y) \%>\%
bindEvent(input$go)
}\if{html}{\out{</div>}}
Anything that consumes \code{r()} will take a reactive dependency on the event
expression given to \code{bindEvent()}, and not the cache key expression given to
\code{bindCache()}. In this case, it is just \code{input$go}.
}
|
