Introduction to shinyjqui

The ui mode and server mode

These mouse interaction functions can be used in either shiny ui (ui mode) or server function (server mode)

In ui mode, the functions accept a shiny ui object (tag, tagList, input or output) and return a modified one with mouse interaction effect attached. For example:

# create a draggable textInput in shiny ui
ui <- fluidPage(
  jqui_draggable(textInput("foo", "Input"))
)

In server mode, the functions add, modify or remove the interactivity of an existing (pre-defined in ui) ui element:

# create a textInput in shiny ui without mouse interaction
ui <- fluidPage(
  textInput("foo", "Input")
)

# make the ui element with id "foo" draggable
server <- function(input, output) {
  jqui_draggable(ui = "#foo", operation = "enable")
}

The ui mode is the most straight forward way to create an ui element with mouse interactions, however, the server mode is more flexible. For example, in server mode, you can reactively control element’s interactivity through observe() or observEvent(), you can use a jQuery selector or even a JavaScript expression to locate the target element(s), and you can control the interaction effects with the operation parameter. (see introduction in the following sections).

The ui parameter

This parameter ui determine the target ui element(s) to be manipulated. The following table summarized the type of object it accepts in different context:

The operation parameter

This parameter is valid only in server mode. It determines how to manipulate the interaction, which includes:

• enable: Initiate the corresponding mouse interaction to the target(s).
• disable: Initiate the interaction if not and temporary disable it (only set the options).
• destory: Completely remove the interaction.
• save: Initiate the interaction if not and save the current interaction state.
• load: Initiate the interaction if not and restore the target(s) to an user defined interaction state or the last saved state.

enable is the default setting of the parameter. save and load can be used to save and restore the state (e.g. size, position, order) of an element. More details in the Vignette Save and restore.

The options parameter

The options parameter can be used to further specify the behavior of interaction. The full list of the available options can be found in jQuery UI’s API Documentation page. Here are some examples:

# drag only horizontally
jqui_draggable('#foo', options = list(axis = 'x'))
# make movement snapping to a 80 x 80 grid
jqui_draggable('#foo', options = list(grid = c(80, 80)))

jqui_droppable('#foo', options = list(
  accept = '#bar', # jQuery selector to define which draggable element to monitor. Accept anything if not set.
  classes = list(
    `ui-droppable-active` = 'ui-state-focus', # change class when draggable element is dragging
    `ui-droppable-hover` = 'ui-state-highlight' # change class when draggable element is dragging over
  ),
  drop = JS(
    'function(event, ui){$(this).addClass("ui-state-active");}'
  ) # a javascrip callback to change class when draggable element is dropped in
))

# keep aspect ratio when resizing
jqui_resizable('#foo', options = list(aspectRatio = TRUE))

# Limit the resizable element to a maximum or minimum height or width
jqui_resizable('#foo', options = list(minHeight = 100, maxHeight = 300,
                                      minWidth = 200, maxWidth = 400))

# make the two plotOutputs resize synchronously
jqui_resizable(plotOutput('plot1', width = '400px', height = '400px'), 
                  options = list(alsoResize = '#plot2')),
plotOutput('plot2', width = '400px', height = '400px')

# highlight the selected plotOutput
jqui_selectable(
  div(
    plotOutput('plot1', width = '400px', height = '400px'),
    plotOutput('plot2', width = '400px', height = '400px')
  ),
  options = list(classes = list(`ui-selected` = 'ui-state-highlight'))
)

# change opacity while sorting
jqui_sortable('#foo', options = list(opacity = 0.5))

# only items with class "items" inside the element become sortable
jqui_sortable('#foo', options = list(items = '> .items'))

# connect two sortable elements, so that items in one element can be dragged to another
jqui_sortable('#foo1', options = list(connectWith = '#foo2'))
jqui_sortable('#foo2', options = list(connectWith = '#foo1'))

The input values and shiny options

In shiny, the user input values are send back to server in the form of input$<id>. Similarly, once enabled, the interaction-specific state values are returned to server and can be accessed by input$<id>_<suffix>, where the id is the element id (id attribute for shiny tag, inputId for shiny inputs, outputId for shiny outputs) and the suffix depends on the type of interaction enabled. The currently deployed interaction state values are listed here:

You can even customize what value to be send back by including a shiny option in the options parameter. This option should be created in the following format. You may combine it with other interaction-specific options before passing to the options parameter:

shiny_opt = list(
  
  # define shiny input value input$id_suffix1
  suffix1 = list(
    # on event_type1 run callback1 and send the returned value to input$id_suffix1
    event_type1 = JS(callback1),
    # on event_type2 or event_type3 run callback2 and send the returned value to input$id_suffix1
    `event_type2 event_type3` = JS(callback2),
    ...
  ),
  
  # define another shiny input value input$id_suffix2
  suffix2 = list(
    ...
  ),
  
  # define more shiny input values
  
)

# pass the shiny option to draggable
jqui_draggable('#foo', options = list(
  shiny = shiny_opt, 
  #other draggable-specific options
))

The shiny option list is composed by multiple suffix definition units. The unit name is used as suffix in input$<id>_<suffix>. Within each unit, there are multiple JS() wrapped JavaScript callback functions named with corresponding event types. The event triggers the callback and the returned value is send to server in the form of input$<id>_<suffix>. The valid event types for each interactions can be found in the API Documentation of jQuery UI. The callback functions take two parameters, event and ui. The definition of the ui parameter can also be found in the document too. Here is an example:

# server
jqui_draggable('#foo', options = list(
  shiny = list(
    # By default, draggable element has a shiny input value showing the
    # element's position (relative to the parent element). Here, another shiny
    # input value (input$foo_offset) is added. It gives the element's offset
    # (position relative to the document).
    offset = list(
      # return the updated offset value when the draggable is created or dragging
      `dragcreate drag` = JS('function(event, ui) {return $(event.target).offset();}'),
    )
  )
))

When customizing shiny input values by shiny option and callbacks, you may want to get the id of certain element in JavaScript. For simple shiny tag (e.g. tags$div), element.attr("id") just works fine, however, things become more complicated for shiny inputs (e.g. textInput). The id attribute of most shiny inputs is hidden inside a div container. You may use jQuery function .find() to locate it. The shinyjqui package comes with an internal JavaScript function shinyjqui.getId() which will take care of this. You can just simply pass in any shiny element, either simple tag, shiny input or shiny output. It will use the appropriate way to find out the id.