An R6 class for adding realtime input validation to Shiny apps.
InputValidator objects are designed to be created as local variables in
Shiny server functions and Shiny module server functions. The Shiny app
author can register zero, one, or multiple validation rules for each input
field in their UI, using the InputValidator$add_rule() method.
Once an InputValidator object is created and populated with rules, it can
be used in a few ways:
The InputValidator$enable() method can be called to display real-time
feedback to users about what inputs are failing validation, and why.
The InputValidator$is_valid() method returns TRUE if and only if all
of the validation rules are passing; this can be checked before
executing actions that depend on the inputs being valid.
The InputValidator$validate() method is a lower-level feature that
directly returns information about what fields failed validation, and
why.
It's possible to have multiple InputValidator objects for each Shiny app.
One scenario where this makes sense is if an app contains multiple forms
that are completely unrelated to each other; each form would have its own
InputValidator instance with a distinct set of rules.
new()Create a new validator object.
InputValidator$new(
priority = 1000,
session = shiny::getDefaultReactiveDomain()
)priorityWhen a validator object is enabled, it creates an
internal shiny::observe() to keep validation feedback in the UI
up-to-date. This parameter controls the priority of that observer. It's
highly recommended to keep this value higher than the priorities of any
observers that do actual work, so users see validation updates quickly.
sessionThe Shiny session object. (You should probably just use
the default.)
condition()Gets or sets a condition that overrides all of the rules in
this validator. Before performing validation, this validator will
execute the cond function. If cond returns TRUE, then
validation continues as normal; if FALSE, then the validation rules
will be skipped and treated as if they are all passing.
add_validator()Add another InputValidator object to this one, as a
"child". Any time this validator object is asked for its validity, it
will only return TRUE if all of its child validators are also valid;
and when this validator object is enabled (or disabled), then all of
its child validators are enabled (or disabled) as well.
This is intended to help with validating Shiny modules. Each module can
create its own InputValidator object and populate it with rules, then
return that object to the caller.
InputValidator$add_validator(validator, label = deparse(substitute(validator)))add_rule()Add an input validation rule. Each input validation rule
applies to a single input. You can add multiple validation rules for a
single input by calling add_rule() multiple times; the first
validation rule for an input that fails will be used, and will prevent
subsequent rules for that input from executing.
InputValidator$add_rule(
inputId,
rule,
...,
session. = shiny::getDefaultReactiveDomain()
)inputIdA single-element character vector indicating the ID of the
input that this rule applies to. (Note that this name should not be
qualified by a module namespace; e.g. pass "x" and not
session$ns("x").)
ruleA function that takes (at least) one argument: the input's
value. The function should return NULL if it passes validation, and
if not, a single-element character vector or HTML tag containing an
error message to display to the user near the input. You can
alternatively provide a single-sided formula instead of a function,
using . as the variable name for the input value being validated.
...Optional: Additional arguments to pass to the rule function
whenever it is invoked.
session.The session object to which the input belongs. (There's almost never a reason to change this from the default.)
enable()Begin displaying input validation feedback in the user
interface. Once enabled, this validator object will automatically keep
the feedback up-to-date. (It's safe to call the enable() method
on an already-enabled validator.) If this validator object has been
added to another validator object using InputValidator$add_validator,
calls to enable() on this validator will be ignored.
disable()Clear existing input validation feedback in the user
interface for all inputs represented in this validator's ruleset, and
stop providing feedback going forward. Once disabled, enable() can be
called to resume input validation.
validate()Run validation rules and gather results. For advanced usage
only; most apps should use the is_valid() and enable() methods
instead. The return value of this method is a named list, where the
names are (fully namespace qualified) input IDs, and the values are
either NULL (if the input value is passing) or a single-element
character vector describing a validation problem.