grid.garnish

This documentation may lag behind the latest version, use the documentation provided with the package for up to date information.

The function grid.garnish() allows a user to add arbitrary attributes to grid graphics objects. These attributes are then applied to the SVG element that the graphics object translates to. This is most useful for adding JavaScript event attributes to grid graphics objects. Examples of such attributes are onmouseover, onmousemove, onclick and onmouseout. The values of these attributes are often JavaScript functions that are called when the appropriate event is triggered. These functions can be defined and included with the use of grid.script().

The usage of the function is defined as follows (further parameters are available to be viewed via ?grid.garnish):

grid.garnish(path, , group=TRUE)

The key argument here is in fact ..., which allows us to provide any named argument and have it applied to the path. By providing an argument with any name or value we like, we are essentially adding attributes to the SVG that will be generated.

The application of this function is going to be demonstrated with the use of the onclick event attribute on a graphics object.

> # Loading grid and gridSVG
> library(grid)
> library(gridSVG)
> 
> # Drawing a solid black rectangle
> grid.rect(width = 0.25, height = 0.25,
+           gp = gpar(fill = "black"))
> 
> # Determining the name of the rectangle
> grid.ls()
GRID.rect.1
> 
> # Adding interactivity for the event where a mouse click occurs on GRID.rect.1
> grid.garnish("GRID.rect.1",
+              onclick = "alert('Example of interactivity with gridSVG.')")
> 
> # Drawing to SVG
> grid.export("example.svg")

When gridSVG processes GRID.rect.1, it will now attach an additional attribute to it, onclick, holding the value of alert(...);. The resulting SVG image can then be loaded into a browser. Although it appears identical to what is shown in R’s plotting window, upon clicking the rectangle we are shown a dialog box with some text. By using grid.garnish() and grid.script(), it is possible to produce complex interactive graphics with gridSVG. The resulting image produced from the above example is shown below (try clicking on the square):

While knowledge of JavaScript is required to perform interactivity, it is not an uncommon language and fortunately there is plenty of documentation available to learn it. A good resource for interacting with SVG via JavaScript is available at carto:net.

An example where grid.garnish() is demonstrated is in the Tooltips example where the SVG elements produced from a graphics object cause the name of the graphics object to appear as text in a tooltip.