vegawidget (version 0.4.1)

vw_handler_signal: Construct a JavaScript handler

Description

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.

Usage

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

vw_handler_add_effect(), vega-view

Examples

# NOT RUN {
  # list all the available signal-handlers
  vw_handler_signal()

  # list all the available data-handlers
  vw_handler_data()

  # list all the available event-handlers
  vw_handler_event()

  # use a defined signal-handler
  vw_handler_signal("value")

  # define your own signal-handler
  vw_handler_signal("return value;")
# }