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)character, the name of a defined handler-body,
or the text of the body of a handler-function
object with S3 class vw_handler
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.
# 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;