R: Create a button to summon a shinyFiles dialog

shinyFiles-buttons {shinyFiles}

R Documentation

Create a button to summon a shinyFiles dialog

Description

This function adds the required html markup for the client to access the file system. The end result will be the appearance of a button on the webpage that summons one of the shinyFiles dialog boxes. The last position in the file system is automatically remembered between instances, but not shared between several shinyFiles buttons. For a button to have any functionality it must have a matching observer on the server side. shinyFilesButton() is matched with shinyFileChoose() and shinyDirButton with shinyDirChoose(). The id argument of two matching calls must be the same. See shinyFiles-observers() on how to handle client input on the server side.

Usage

shinyFilesButton(
  id,
  label,
  title,
  multiple,
  buttonType = "default",
  class = NULL,
  icon = NULL,
  style = NULL,
  viewtype = "detail",
  ...
)

shinyFilesLink(
  id,
  label,
  title,
  multiple,
  class = NULL,
  icon = NULL,
  style = NULL,
  viewtype = "detail",
  ...
)

shinyDirButton(
  id,
  label,
  title,
  buttonType = "default",
  class = NULL,
  icon = NULL,
  style = NULL,
  ...
)

shinyDirLink(id, label, title, class = NULL, icon = NULL, style = NULL, ...)

shinySaveButton(
  id,
  label,
  title,
  filename = "",
  filetype,
  buttonType = "default",
  class = NULL,
  icon = NULL,
  style = NULL,
  viewtype = "detail",
  ...
)

shinySaveLink(
  id,
  label,
  title,
  filename = "",
  filetype,
  class = NULL,
  icon = NULL,
  style = NULL,
  viewtype = "detail",
  ...
)

Arguments

`id`	The id matching the `shinyFileChoose()`
`label`	The text that should appear on the button
`title`	The heading of the dialog box that appears when the button is pressed
`multiple`	A logical indicating whether or not it should be possible to select multiple files
`buttonType`	The Bootstrap button markup used to colour the button. Defaults to 'default' for a neutral appearance but can be changed for another look. The value will be pasted with 'btn-' and added as class.
`class`	Additional classes added to the button
`icon`	An optional icon to appear on the button.
`style`	Additional styling added to the button (e.g., "margin-top: 25px;")
`viewtype`	View type to use in the file browser. One of "detail" (default), "list", or "icon"
`...`	Named attributes to be applied to the button or link (e.g., 'onclick')
`filename`	A predefined filename to be filed in. Can be modified by the user during saving.
`filetype`	A named list of file extensions. The name of each element gives the name of the filetype and the content of the element the possible extensions e.g. `list(picture=c('jpg', 'jpeg'))`. The first extension will be used as default if it is not supplied by the user.

Details

Selecting files

When a user selects one or several files the corresponding input variable is set to a list containing a character vector for each file. The character vectors gives the traversal route from the root to the selected file(s). The reason it does not give a path as a string is that the client has no knowledge of the file system on the server and can therefore not ensure proper formatting. The parseFilePaths() function can be used on the server to format the input variable into a format similar to that returned by shiny::fileInput().

Selecting folders

When a folder is selected it will also be available in its respective input variable as a list giving the traversal route to the selected folder. To properly format it, feed it into parseDirPath() and a string with the full folder path will be returned.

Creating files (saving)

When a new filename is created it will become available in the respective input variable and can be formatted with parseSavePath() into a data.frame reminiscent that returned by fileInput. There is no size column and the type is only present if the filetype argument is used in shinySaveButton. In that case it will be the name of the chosen type (not the extension).

Manual markup

For users wanting to design their html markup manually it is very easy to add a shinyFiles button. The only markup required is:

shinyFilesButton

⁠<button id="inputId" type="button" class="shinyFiles btn btn-default" data-title="title" data-selecttype="single"|"multiple">label</button>⁠

shinyDirButton

⁠<button id="inputId" type="button" class="shinyDirectories btn-default" data-title="title">label</button>⁠

shinySaveButton

<button id="inputId" type="button" class="shinySave btn-default" data-title="title" data-filetype="[{name: 'type1', ext: ['txt']}, {name: 'type2', ext: ['exe', 'bat']}]">label</button>

where the id tag matches the inputId parameter, the data-title tag matches the title parameter, the data-selecttype is either "single" or "multiple" (the non-logical form of the multiple parameter) and the internal textnode matches the label parameter. The data-filetype tag is a bit more involved as it is a json formatted array of objects with the properties 'name' and 'ext'. 'name' gives the name of the filetype as a string and 'ext' the allowed extensions as an array of strings. The non-exported formatFiletype() function can help convert from a named R list into the string representation. In the example above "btn-default" is used as button styling, but this can be changed to any other Bootstrap style.

Apart from this the html document should link to a script with the following path 'sF/shinyFiles.js' and a stylesheet with the following path 'sF/styles.css'.

The markup is bootstrap compliant so if the bootstrap css is used in the page the look will fit right in. There is nothing that hinders the developer from ignoring bootstrap altogether and designing the visuals themselves. The only caveat being that the glyphs used in the menu buttons are bundled with bootstrap. Use the css ::after pseudoclasses to add alternative content to these buttons. Additional filetype specific icons can be added with css using the following style:

.sF-file .sF-file-icon .yourFileExtension{
    content: url(path/to/16x16/pixel/png);
}
.sF-fileList.sF-icons .sF-file .sF-file-icon .yourFileExtension{
  content: url(path/to/32x32/pixel/png);
}

If no large version is specified the small version gets upscaled.

Client side events

If the shiny app uses custom Javascript it is possible to react to selections directly from the javascript. Once a selection has been made, the button will fire the event 'selection' and pass the selection data along with the event. To listen for this event you simple add:

$(button).on('selection', function(event, path) {
  // Do something with the paths here
})

In the same way, when a file is saved, the save button will fire the event 'save' and pass the file path along with the event. To listen for this event you can use:

$(button).on('save', function(event, path) {
  // Do something with the path here
})

Moreover, a 'cancel' event is fired when a user dismisses a ShinyFiles dialog box. In that case, no path is passed on.

Outside events the current selection is available as an object bound to the button and can be accessed at any time:

// For a shinyFilesButton
$(button).data('files')

// For a shinyDirButton
$(button).data('directory')

// For a shinySaveButton
$(button).data('file')

Value

This function is called for its side effects

References

The file icons used in the file system navigator is taken from FatCows Farm-Fresh Web Icons (https://www.fatcow.com/free-icons)