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:
install.packages("shinyhelper")
To get the latest development version, you can use the devtools
package to install from GitHub directly:
devtools::install_github("cwthom/shinyhelper")
In both cases, then load the package in with:
library(shinyhelper)
There is a live demo hosted on shinyapps.io. Click here to go to the demo!
Alternatively, run the demo locally with:
library(shinyhelper)
shinyhelper_demo()
You can add help files to any shiny element, including all inputs and outputs, with a simple call to helper()
:
# 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 helper
s 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 title
and content
arguments. 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 observe_helpers
. E.g.
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 helper()
:
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 colour
.
By default, all help files are medium sized modalDialog()
boxes (size = "m"
). You can change each one though, by passing the size
argument to helper()
:
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")
The 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!
Many thanks also to Guangchang Yu for the wonderful hexSticker package!
Welcome to shinyhelper 0.3.1. This patch version introduces three new elements to the package, to fix bugs in 0.3.0.
New features:
helper
icons now work within dynamically rendered UIFixed bugs:
Thanks to GitHub user kornl for spotting and fixing the MathJax and z-index bugs.
New features:
New features:
Thanks to GitHub user kornl for both of the following:
z-index
CSS parameter of help iconsWelcome 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.
New features:
shinyjs
use_shinyhelper()
function - this has been removedtype
argument to helper()
with type = "inline"
helper()
now have easyClose = TRUE
, so can be shut by clicking anywhere or pressing ESCobserve_helpers()
now has no mandatory arguments; it can be called as-ishelper()
- 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 input
and output
directly.shinyhelperDemo()
has been renamed shinyhelper_demo()
to match other snake_case
naming convention throughout the package.Thanks:
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.
New features:
type = "inline"
use_shinyhelper()
in UIshinyjs
- this is now purely an extension of shinyinput
to observe_helpers
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.
New Features:
icon_colour
argument to helper()
- no need to use style = "color = ...;"
any moresize
argument to helper()
- no more named lists!shinyhelperDemo()
function, to run a demo app that comes installed with the packageDeprecated Features:
sizes
and default_size
arguments to 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.
New features:
helper
, not named list in observe_helpers()
Deprecated features:
sizes
and default_size
arguments to observe_helpers()
New features:
shinyhelperDemo
to run example appNew features:
colour
parameter.This is the first version of the package.