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.






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
#> arguments: name, value 
#>   body_value: value 
#>     // returns the value of the signal
#>     return value;

  # list all the available data-handlers
#> arguments: name, value 
#>   body_value: value 
#>     // returns a copy of the data
#>     return value.slice();

  # list all the available event-handlers
#> 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
#> 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;