Creates a lightweight way to add markdown helpfiles to 'shiny' apps, using modal dialog boxes, with no need to observe each help button separately.
Easily add help documentation to shiny elements, using markdown files.
The advantages of using this package are:
shinyhelper 0.3.1 now on CRAN! Go to: https://cran.r-project.org/package=shinyhelper You can install the package with:
To get the latest development version, you can use the
devtools package to install from GitHub directly:
In both cases, then load the package in with:
There is a live demo hosted on shinyapps.io. Click here to go to the demo!
Alternatively, run the demo locally with:
You can add help files to any shiny element, including all inputs and outputs, with a simple call to
# load the package library(shinyhelper) ... # For elements in your ui you wish to add a help icon to helper(plotOutput(outputId = "plot")) # if you have %>% loaded, you can do plotOutput(outputId = "plot") %>% helper() ... # In your server script, include: observe_helpers() # this triggers the modal dialogs when the user clicks an icon # specify the name of your directory of help markdown files here # e.g. observe_helpers(help_dir = "help_mds") will look for a directory called help_mds # If you wish to include mathematical formulae in your markdown, use the `withMathJax` argument: # observe_helpers(withMathJax = TRUE)
Note that as of shinyhelper v0.3.1, you can define
helpers in dynamic UI elements as well! This opens up the option to display different helpfiles depending on current input settings, improving user experience. Thanks to those who flagged this issue and waited patiently for a fix!
All you need now is some content for your help page. You can specify this in 2 ways:
To specify inline content, simply set
type = "inline" in
helper, and supply the
content can be a character vector, in which case each element will be a new line. You can also use raw HTML tags to format your inline content E.g.
plotOutput(outputId = "plot") %>% helper(type = "inline", title = "Plot", content = c("This is a <b>plot</b>.", "This is on a new line."))
To use markdown, set
type = "markdown" in
helper, and supply the name of your markdown file (without the .md) in the
content argument. This file should be in the directory specified by the
help_dir argument to
plotOutput(outputId = "plot") %>% helper(type = "markdown", content = "Plot") # this will search for 'Plot.md' in the directory given in observe_helpers
You can specify a
title argument too, or leave it blank and use a
## Heading in your markdown document.
You can change the type of icon used and its colour, as well as passing CSS inline.
The icons are
shiny::icon("question-circle") icons by default, but you can change them individually using the
icon argument of
plotOutput(outputId = "plot") %>% helper(icon = "exclamation")
Please see Font Awesome for the available icons.
You can change the icon colour with the
colour argument. Pass it any valid CSS colour as a character string.
plotOutput(outputId = "plot") %>% helper(colour = "green")
You can pass a
style argument to modify CSS inline. This applies to the
<div> containing the icon.
plotOutput(outputId = "plot") %>% helper(style = "color: red;")
Note: Passing a colour in a
style argument will override
By default, all help files are medium sized
modalDialog() boxes (
size = "m"). You can change each one though, by passing the
size argument to
plotOutput(outputId = "plot") %>% helper(size = "l")
There is also a function,
create_help_files() to quickly create a directory of help files from a vector of names.
# Run this interactively, not in a shiny app create_help_files(files = c("Clusters", "Columns", "PlotHelp"), help_dir = "helpfiles")
help_dir will be "helpfiles" by default.
Obviously, this package would not be possible (or indeed meaningful) without the incredible shiny package. Full credit to the authors of shiny for doing all of the actual work!
Welcome to shinyhelper 0.3.1. This patch version introduces three new elements to the package, to fix bugs in 0.3.0.
helpericons now work within dynamically rendered UI
Thanks to GitHub user kornl for spotting and fixing the MathJax and z-index bugs.
Thanks to GitHub user kornl for both of the following:
z-indexCSS parameter of help icons
Welcome to shinyhelper 0.3.0 - this version of the package is a complete re-write of the previous version and is NOT BACKWARDS COMPATIBLE. This change has been to make the package less of a hack and more of a proper extension of
shiny. It also brings in a smoother interface for app developers, with fewer function calls necessary for the package to work, and less intrusion into the workings of your apps.
use_shinyhelper()function - this has been removed
type = "inline"
easyClose = TRUE, so can be shut by clicking anywhere or pressing ESC
observe_helpers()now has no mandatory arguments; it can be called as-is
helper()- previously it was bodged together in the ID.
create_help_files()will create a directory called "helpfiles" by default.
Non-backwards compatible changes:
helper()have been renamed or replaced.
observe_helpers()now looks at the session object rather than
shinyhelperDemo()has been renamed
shinyhelper_demo()to match other
snake_casenaming convention throughout the package.
Thanks go to Dean Attali for his feedback on v0.2.0
This will become v0.3.0 - it is a complete re-write internally, changing how the information to be displayed in the help box is conveyed from the browser to the server, and giving the user the option of specifying inline content.
The ui is also no longer cluttered with additional inputs.
type = "inline"
shinyjs- this is now purely an extension of shiny
Welcome to shinyhelper v0.2.0 - this is an improved version on the original package, with greater freedom and ease for you to customise your app UI.
helper()- no need to use
style = "color = ...;"any more
helper()- no more named lists!
shinyhelperDemo()function, to run a demo app that comes installed with the package
observe_helpers()have been deprecated. They're still there, but will give a warning message if you try to use them.
I've also improved the documentation in the man pages.
helper, not named list in
shinyhelperDemoto run example app
This is the first version of the package.