| Type: | Package |
| Title: | Create Tours in 'Shiny' Apps Using 'Shepherd.js' |
| Version: | 0.1.1 |
| Description: | Enable the use of 'Shepherd.js' to create tours in 'Shiny' applications. |
| License: | MIT + file LICENSE |
| Encoding: | UTF-8 |
| Imports: | htmltools, R6, shiny |
| Suggests: | shinytest2, testthat |
| RoxygenNote: | 7.2.1 |
| URL: | https://github.com/etiennebacher/conductor |
| BugReports: | https://github.com/etiennebacher/conductor/issues |
| Config/testthat/edition: | 3 |
| NeedsCompilation: | no |
| Packaged: | 2022-08-28 09:57:39 UTC; etienne |
| Author: | Etienne Bacher [aut, cre] |
| Maintainer: | Etienne Bacher <etienne.bacher@protonmail.com> |
| Repository: | CRAN |
| Date/Publication: | 2022-08-28 10:10:01 UTC |
Create a "conductor" tour
Description
In addition to this page, you can also directly access the documentation of shepherd.js here: https://shepherdjs.dev/docs/index.html.
Methods
Public methods
Method new()
Usage
Conductor$new( exitOnEsc = TRUE, keyboardNavigation = TRUE, useModalOverlay = TRUE, classPrefix = NULL, tourName = NULL, stepsContainer = NULL, modalContainer = NULL, confirmCancel = FALSE, confirmCancelMessage = NULL, defaultStepOptions = NULL, mathjax = FALSE, progress = FALSE, onComplete = NULL, onCancel = NULL, onHide = NULL, onShow = NULL, onStart = NULL, onActive = NULL, onInactive = NULL )
Arguments
exitOnEscAllow closing the tour by pressing "Escape". Default is
TRUE.keyboardNavigationAllow navigating the tour with keyboard arrows. Default is
TRUE.useModalOverlayHighlight the tour popover and the element (if specified). Default is
TRUE.classPrefixAdd a prefix to the classes of the tour. This allows having different CSS for each tour.
tourNameAn (optional) name to give to the tour.
stepsContainerAn optional container element for the steps. If
NULL(default), the steps will be appended todocument.body.modalContainerAn optional container element for the modal. If
NULL(default), the modal will be appended todocument.body.confirmCancelAsk confirmation to cancel the tour. Default is
FALSE.confirmCancelMessageMessage in the popup that ask confirmation to close the tour (works only if
confirmCancel = TRUE).defaultStepOptionsA nested list of options to apply to the entire tour. See
Details.mathjaxEnable MathJax? Default is
FALSE. This requires importing MathJax, for example withshiny::withMathJax().progressShow a step counter in each step? Default is
FALSE.onCompleteA JavaScript code to run when the tour is completed.
onCancelA JavaScript code to run when the tour is cancelled.
onHideA JavaScript code to run when the tour is hidden.
onShowA JavaScript code to run when the tour is shown.
onStartA JavaScript code to run when the tour starts.
onActiveA JavaScript code to run when the tour is active.
onInactiveA JavaScript code to run when the tour is inactive.
Details
Create a new Conductor object.
Returns
A Conductor object.
Method init()
Usage
Conductor$init(session = NULL)
Arguments
sessionA valid Shiny session. If
NULL(default), the function attempts to get the session withshiny::getDefaultReactiveDomain().
Details
Initialise Conductor.
Method start()
Usage
Conductor$start(session = NULL)
Arguments
sessionA valid Shiny session. If
NULL(default), the function attempts to get the session withshiny::getDefaultReactiveDomain().
Details
Start Conductor.
Method step()
Usage
Conductor$step( title = NULL, text = NULL, el = NULL, position = NULL, arrow = TRUE, tabId = NULL, tab = NULL, canClickTarget = TRUE, advanceOn = NULL, scrollTo = NULL, cancelIcon = NULL, showOn = NULL, id = NULL, buttons = NULL, classes = NULL, highlightClass = NULL, onComplete = NULL, onCancel = NULL, onHide = NULL, onShow = NULL )
Arguments
titleTitle of the popover.
textText of the popover.
elThe element to highlight. It can be an id (for example
#mynav), a class (for instance.navbar), or a general tag (for examplebutton). IfNULL(default) or if the selector is not found, the popover will appear in the center of the page.positionPosition of the popover relative to the element. Possible values are: 'auto', 'auto-start', 'auto-end', 'top', 'top-start', 'top-end', 'bottom', 'bottom-start', 'bottom-end', 'right', 'right-start', 'right-end', 'left', 'left-start', 'left-end'.
arrowAdd an arrow pointing towards the highlighted element. Default is
TRUE.tabIdId of the
tabsetPanel().tabName of the tab that contains the element.
canClickTargetAllow the highlighted element to be clicked. Default is
TRUE.advanceOnAn action on the page which should advance the tour to the next step. It should be a list with a string selector and an event name.
scrollToShould the element be scrolled to when this step is shown? Default is
TRUE.cancelIconA list of two elements:
enabledis a boolean indicating whether a "close" icon should be displayed (default isTRUE);labelis the label to add foraria-label.showOnEither a boolean or a JavaScript expression that returns
trueorfalse. It indicates whether the step should be displayed in the tour.idName of the step (optional).
buttonsA list of lists. Each "sublist" contains the information for one button. There are six possible arguments for each button: action ("back" or "next"), text (name of the button), secondary (
TRUE/FALSE), disabled (TRUE/FALSE), label (aria-label of the button), and classes (for finer CSS customization).classesA character vector of extra classes to add to the step's content element.
highlightClassAn extra class to apply to
elwhen it is highlighted. Only one extra class is accepted.onCompleteSome JavaScript code to run when the step is complete (only for the last step).
onCancelSome JavaScript code to run when the step is cancelled.
onHideSome JavaScript code to run when the step is hidden.
onShowSome JavaScript code to run when the step is shown.
Details
Add a step in a Conductor tour.
Method updateStepOptions()
Usage
Conductor$updateStepOptions( step = NULL, title = NULL, text = NULL, el = NULL, position = NULL, arrow = TRUE, tabId = NULL, tab = NULL, canClickTarget = TRUE, advanceOn = NULL, scrollTo = TRUE, cancelIcon = NULL, showOn = NULL, id = NULL, buttons = NULL, classes = NULL, highlightClass = NULL, session = NULL )
Arguments
stepId of the step (optional). If
NULL(default), the current step is used.titleTitle of the popover.
textText of the popover.
elThe element to highlight. It can be an id (for example
#mynav), a class (for instance.navbar), or a general tag (for examplebutton). IfNULL(default) or if the selector is not found, the popover will appear in the center of the page.positionPosition of the popover relative to the element. Possible values are: 'auto', 'auto-start', 'auto-end', 'top', 'top-start', 'top-end', 'bottom', 'bottom-start', 'bottom-end', 'right', 'right-start', 'right-end', 'left', 'left-start', 'left-end'.
arrowAdd an arrow pointing towards the highlighted element. Default is
TRUE.tabIdId of the
tabsetPanel().tabName of the tab that contains the element.
canClickTargetAllow the highlighted element to be clicked. Default is
TRUE.advanceOnAn action on the page which should advance shepherd to the next step. It should be a list with a string selector and an event name.
scrollToShould the element be scrolled to when this step is shown? Default is
TRUE.cancelIconA list of two elements:
enabledis a boolean indicating whether a "close" icon should be displayed (default isTRUE);labelis the label to add foraria-label.showOnEither a boolean or a JavaScript expression that returns
trueorfalse. It indicates whether the step should be displayed in the tour.idName of the step (optional).
buttonsA list of lists. Each "sublist" contains the information for one button. There are six possible arguments for each button: action ("back" or "next"), text (name of the button), secondary (
TRUE/FALSE), disabled (TRUE/FALSE), label (aria-label of the button), and classes (for finer CSS customization).classesA character vector of extra classes to add to the step's content element.
highlightClassAn extra class to apply to
elwhen it is highlighted. Only one extra class is accepted.sessionA valid Shiny session. If
NULL(default), the function attempts to get the session withshiny::getDefaultReactiveDomain().onShowSome JavaScript code to run when the step is shown.
onHideSome JavaScript code to run when the step is hidden.
onCancelSome JavaScript code to run when the step is cancelled.
onCompleteSome JavaScript code to run when the step is complete (only for the last step).
Details
Modify the options of a specific step.
Method show()
Usage
Conductor$show(step = NULL, session = NULL)
Arguments
stepEither the id of the step to show (defined in
$step()) or its number.sessionA valid Shiny session. If
NULL(default), the function attempts to get the session withshiny::getDefaultReactiveDomain().
Details
Show a specific step.
Method remove()
Usage
Conductor$remove(step = NULL, session = NULL)
Arguments
stepA character vector with the id(s) of the step(s) to remove (defined in
$step()).sessionA valid Shiny session. If
NULL(default), the function attempts to get the session withshiny::getDefaultReactiveDomain().
Details
Remove specific step(s).
Method moveNext()
Usage
Conductor$moveNext(session = NULL)
Arguments
sessionA valid Shiny session. If
NULL(default), the function attempts to get the session withshiny::getDefaultReactiveDomain().
Details
Advances the tour to the next step.
Method moveBack()
Usage
Conductor$moveBack(session = NULL)
Arguments
sessionA valid Shiny session. If
NULL(default), the function attempts to get the session withshiny::getDefaultReactiveDomain().
Details
Shows the previous step.
Method cancel()
Usage
Conductor$cancel(session = NULL)
Arguments
sessionA valid Shiny session. If
NULL(default), the function attempts to get the session withshiny::getDefaultReactiveDomain().
Details
Cancels the tour.
Method complete()
Usage
Conductor$complete(session = NULL)
Arguments
sessionA valid Shiny session. If
NULL(default), the function attempts to get the session withshiny::getDefaultReactiveDomain().
Details
Completes the tour.
Method hide()
Usage
Conductor$hide(session = NULL)
Arguments
sessionA valid Shiny session. If
NULL(default), the function attempts to get the session withshiny::getDefaultReactiveDomain().
Details
Hides the current step.
Method getCurrentStep()
Usage
Conductor$getCurrentStep(session = NULL)
Arguments
sessionA valid Shiny session. If
NULL(default), the function attempts to get the session withshiny::getDefaultReactiveDomain().
Details
Get the id of the current step. If no id was specified in $step(),
a random id is generated.
Method getHighlightedElement()
Usage
Conductor$getHighlightedElement(session = NULL)
Arguments
sessionA valid Shiny session. If
NULL(default), the function attempts to get the session withshiny::getDefaultReactiveDomain().
Details
Returns the id of the highlighted element of the current step. If this element has no id, it returns its class.
Method isOpen()
Usage
Conductor$isOpen(step = NULL, session = NULL)
Arguments
stepId of the step (optional). If
NULL(default), the current step is used.sessionA valid Shiny session. If
NULL(default), the function attempts to get the session withshiny::getDefaultReactiveDomain().
Details
Returns a value TRUE or FALSE indicating whether the step is open.
Method isActive()
Usage
Conductor$isActive(session = NULL)
Arguments
sessionA valid Shiny session. If
NULL(default), the function attempts to get the session withshiny::getDefaultReactiveDomain().
Details
Returns a value TRUE or FALSE indicating whether the tour is active.
Method clone()
The objects of this class are cloneable with this method.
Usage
Conductor$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
Dependencies
Description
Include dependencies, place anywhere in the shiny UI.
Usage
useConductor()
use_conductor()
Examples
library(shiny)
library(conductor)
ui <- fluidPage(
useConductor()
# also works:
# use_conductor()
)
server <- function(input, output){}
if(interactive()) shinyApp(ui, server)