Easily Add Markdown Help Files to 'shiny' App Elements

Creates a lightweight way to add markdown helpfiles to 'shiny' apps, using modal dialog boxes, with no need to observe each help button separately.


CRAN_Status_Badge CRAN_Downloads Travis-CI Build Status

Easily add help documentation to shiny elements, using markdown files.

The advantages of using this package are:

  • add help files with a single extra function call
  • leverage the formatting power of markdown to go beyond simple tooltips
  • customise the appearance and positioning of the help icons, and the size of help pages
  • additional function to quickly create a suitable directory of markdown files

Installation

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)

Demo

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()

Usage

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 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!

Content

All you need now is some content for your help page. You can specify this in 2 ways:

inline

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."))

markdown

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.

Changing the Icon Appearance

You can change the type of icon used and its colour, as well as passing CSS inline.

Icon

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.

Colour

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")

Inline CSS

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.

Changing the Help Page Size

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")

Creating your Help Files

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.

Credits

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!

News

shinyhelper 0.3.1

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 UI
  • inline content now supports HTML strings for formatting
  • mathematical formulae can be rendered in help files, using MathJax

Fixed bugs:

  • help icons now no longer overlie drop down lists (lower z-index)

Thanks to GitHub user kornl for spotting and fixing the MathJax and z-index bugs.

shinyhelper 0.3.0.9001

New features:

  • helper icons now work in dynamically rendered UI

shinyhelper 0.3.0.9000

New features:

Thanks to GitHub user kornl for both of the following:

  • fix to z-index CSS parameter of help icons
  • add withMathJax parameter to allow formulae to render
  • support inline raw html

shinyhelper 0.3.0

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.

New features:

  • No longer dependent on package shinyjs
  • No need for the use_shinyhelper() function - this has been removed
  • Can now pass inline content as well as markdown files to your shiny app. This means that short help dialog boxes can be defined entirely within the UI of your app, where they should be. Just use the type argument to helper() with type = "inline"
  • The modals created by helper() now have 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
  • Information such as the size and content of help pages is now stored in data-* attributes of the HTML tags created by helper() - previously it was bodged together in the ID.
  • create_help_files() will create a directory called "helpfiles" by default.

Non-backwards compatible changes:

  • Various arguments to 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

shinyhelper 0.2.0.9000

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:

  • can now specify inline content, with type = "inline"
  • no longer need to do use_shinyhelper() in UI
  • removed dependency on shinyjs - this is now purely an extension of shiny
  • modals now close by clicking anywhere, or pressing ESC
  • no longer need to pass input to observe_helpers
  • uses data-* attributes from HTML5 to store information, not non-standard attributes
  • published demo to shinyapps.io

shinyhelper 0.2.0

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:

  • dedicated icon_colour argument to helper() - no need to use style = "color = ...;" any more
  • set size of each help page individually with the size argument to helper() - no more named lists!
  • use a file name of your choice for your markdown help pages - no longer need to have the same as the shiny.tag input and output IDs
  • new shinyhelperDemo() function, to run a demo app that comes installed with the package

Deprecated Features:

  • the 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.

shinyhelper 0.1.1.9003

New features:

  • can set sizes of help pages in helper, not named list in observe_helpers()
  • can set custom filename for help pages - no longer need to use inputId and outputId although that's still the default.

Deprecated features:

  • sizes and default_size arguments to observe_helpers()

shinyhelper 0.1.1.9002

New features:

  • example app installed with package
  • better documentation of functions
  • dedicated function shinyhelperDemo to run example app

shinyhelper 0.1.1.9000

New features:

  • Set colour of help icon with dedicated colour parameter.

shinyhelper 0.1.1

This is the first version of the package.

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.

install.packages("shinyhelper")

0.3.1 by Chris Mason-Thom, 6 months ago


Report a bug at https://github.com/cwthom/shinyhelper/issues


Browse source code at https://github.com/cran/shinyhelper


Authors: Chris Mason-Thom [aut, cre]


Documentation:   PDF Manual  


GPL-3 license


Imports shiny, markdown


See at CRAN