InputValidator {shinyvalidate}R Documentation

Shiny validation object

Description

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:

  1. The InputValidator$enable() method can be called to display real-time feedback to users about what inputs are failing validation, and why.

  2. 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.

  3. 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.

Methods

Public methods

Method new()

Create a new validator object.

Usage
InputValidator$new(
  priority = 1000,
  session = shiny::getDefaultReactiveDomain()
)
Arguments
priority

When 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.

session

The Shiny session object. (You should probably just use the default.)

Method parent()

For internal use only.

Usage
InputValidator$parent(validator)
Arguments
validator

An InputValidator object.

Method 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.

Usage
InputValidator$condition(cond)
Arguments
cond

If this argument is missing, then the method returns the currently set condition function. If not missing, then cond must be either a zero-argument function that returns TRUE or FALSE; a single-sided formula that results in TRUE or FALSE; or NULL (which is equivalent to ~ TRUE).

Returns

If cond is missing, then either NULL or a zero-argument function; if cond is provided, then nothing of consequence is returned.

Method 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.

Usage
InputValidator$add_validator(validator, label = deparse(substitute(validator)))
Arguments
validator

An InputValidator object.

label

An optional label for the InputValidator object. By default, a label will be automatically generated.

Method 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.

Usage
InputValidator$add_rule(
  inputId,
  rule,
  ...,
  session. = shiny::getDefaultReactiveDomain()
)
Arguments
inputId

A 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").)

rule

A 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.)

Method 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.

Usage
InputValidator$enable()

Method 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.

Usage
InputValidator$disable()

Method fields()

Returns TRUE if all input validation rules currently pass, FALSE if not.

Usage
InputValidator$fields()

Method is_valid()

Returns TRUE if all input validation rules currently pass, FALSE if not.

Usage
InputValidator$is_valid()

Method 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.

Usage
InputValidator$validate()

Method _validate_impl()

For internal use only.

Usage
InputValidator$_validate_impl(indent)
Arguments
indent

For internal use only.

[Package shinyvalidate version 0.1.3 Index]