A Vega listener needs a JavaScript handler-function to call when the object-being-listened-to changes. For instance, shiny-getters and add-listeners functions each have an argument called body_value, which these functions help you build.

vw_handler_signal(body_value)

vw_handler_data(body_value)

vw_handler_event(body_value)

Arguments

body_value

character, the name of a defined handler-body, or the text of the body of a handler-function

Value

object with S3 class vw_handler

Details

There are two types of handlers defined in this package's handler-library. To see the handlers that are defined for each, call the function without any arguments:

  • vw_handler_signal()

  • vw_handler_data()

  • vw_handler_event()

With a JavaScript handler, you are trying to do two types of things:

  • calculate a value based on the handler's arguments

  • produce a side-effect based on that calculated value

Let's look at a concrete example. A signal handler will take arguments name and value. Let's say that we want to return the value. We could do this two ways:

  • vw_handler_signal("value"): use this package's handler library

  • vw_handler_signal("return value;"): supply the body of the handler-function yourself

In the list above, the two calls do exactly the same thing, they build a JavaScript function that returns the value provided by whatever is calling the signal-handler. This will be a valid signal-handler, however, we will likely want a signal-handler to do something with that value, which is why we may wish to add a side-effect.

Let's say we want the handler to print the value to the JavaScript console. We would create the signal-handler, then add an effect to print the result to the console.

vw_handler_signal("value") %>% vw_handler_add_effect("console")

We can add as many effects as we like; for more information, please see the documentation for vw_handler_add_effect().

Please be aware that these functions do not check for the correctness of JavaScript code you supply - any errors you make will not be apparent until your visualization is rendered in a browser.

One last note, if body_value is already a vw_handler, these functions are no-ops; they will return the body_value unchanged.

See also

Examples

# list all the available signal-handlers vw_handler_signal()
#> arguments: name, value #> #> body_value: value #> #> // returns the value of the signal #> return value;
# list all the available data-handlers vw_handler_data()
#> arguments: name, value #> #> body_value: value #> #> // returns a copy of the data #> return value.slice();
# list all the available event-handlers vw_handler_event()
#> arguments: event, item #> #> body_value: item #> #> // returns the item #> return item; #> #> body_value: datum #> #> // if there is no item or no datum, return null #> if (item === null || item === undefined || item.datum === undefined) { #> return null; #> } #> #> // returns the datum behind the mark associated with the event #> return item.datum;
# use a defined signal-handler vw_handler_signal("value")
#> arguments: name, value #> body_value: #> // returns the value of the signal #> return value;
# define your own signal-handler vw_handler_signal("return value;")
#> arguments: name, value #> body_value: #> return value;