etiennebacher / conductor

Create Tours in Shiny Apps Using Shepherd.js.

I develop, contribute to, or maintain a few R packages related to various topics.

Data manipulation

• polars: port of the Rust/Python polars to R.

• tidypolars: get the power of polars with the syntax of the tidyverse.

• datawizard: this package is part of the easystats ecosystem. It provides many functions to manipulate data (similarly to what dplyr and tidyr do) and to perform various statistical transformation on variables (standardizing, winsorizing, normalizing, etc.).

Package development

• altdoc: use docsify.js, docute, mkdocs, or quarto to build a website for your R package documentation. This is meant to be an alternative to {pkgdown}.

R Shiny applications

• conductor: create tours in Shiny apps. This uses shepherd.js under the hood and provides similar functionalities as cicerone and rintrojs.

• prompter: easily create tooltips in Shiny apps. It uses hint.css under the hood.

• shinyfullscreen: display HTML elements in fullscreen in Shiny apps. This uses screenfull.js under the hood.

---

While developing packages for R Shiny applications, I had some trouble trying to determine if a Javascript library had already been adapted in R. Therefore, I started a list of R packages that adapt Javascript libraries: awesome-R-JS-adaptation. Feel free to propose missing libraries.

conductor's Issues

shepherd.js was updated to v.10.0

https://github.com/shipshapecode/shepherd/releases/tag/v10.0.0

improve is_active

Check how cicerone works with get_highlighted_el: https://cicerone.john-coene.com/guide/events.html

remove the init() method?

Why is it useful (in this package and in cicerone)?

Interact with app inputs during tour

Hi,

Is it possible to interact with inputs during the tour, for example select a checkbox, or select a drop-down etc.. ?

Thanks

Marcus

check CSS for title and text in chromium browsers

maybe not needed to modify the css in those browsers

font is much smaller with fluidPage than semanticPage

Add more tests

make the 'el' argument easier

Automatically allow "#el" or ".el" (need to check with JS code of shepherd if this works). This would also remove the need for arg is_id.

tour goes directly to the element, no smooth scroll

see example in #16

add step events

https://shepherdjs.dev/docs/tutorial-02-usage.html

Unexpected scroll

Hi, first of all, really enjoying the features in conductor! However, I notice that when my app steps through the tour, the application scrolls, so that the info "bubble" is at the top of the screen. This seems un-intuitive as the default, since if requires the user to reorient to the app in each step. Is there a simple way to disable this? Do I have to go into the CSS file?

Thanks!!

Target of assignment expands to non-language object

Hello, I've tried searching about this issue but I'm not sure whether anyone else has had the same problem. When i introduce this step into my tour, having one of them is fine. However, if i put the second step after a few other steps, the terminal tells me this error message below. The strange thing is, if I put the first and second step right after each other, there is no problem.

Basically, I want to make the user click the tab to navigate them towards the next tab, then explain all the functions in the tab, then ask them to click the third tab. I find if I don't use advanceOn and the user clicks the next button, the tour breaks because it's trying to show something that's on the wrong tab.

Error in Conductor$new()$step(title = "Welcome to DataCops! (1/11)", text = "This is a tour to introduce you to our application. You can exit out of the tour at any time by pressing the Esc key, and you can control the tour with your arrow keys. Click next to continue the tour! ",  : 
  target of assignment expands to non-language object

First step

step(
    el = "#tabs",
    title = "Information tabs",
    text = "This is where you can view all the different tabs to see different visualizations! Please click the second tab to continue.",
    canClickTarget = TRUE,
    advanceOn = list(selector = "#tabs li:nth-child(2)", event = "click"), 
    buttons = list()
  )$

Second step

step(
    el = "#tabs",
    title = "Information tabs",
    text = "This is where you can view all the different tabs to see different visualizations! Please click the third tab to continue.",
    canClickTarget = TRUE,
    advanceOn = list(selector = "#tabs li:nth-child(3)", event = "click"), 
    buttons = list()
  )$

This order returns me the problem

conductor <- Conductor$
  new()$
  step(
    title = "Welcome to DataCops! (1/11)",
    text = "This is a tour to introduce you to our application. You can exit out of the tour at any time by pressing the Esc key, and you can control the tour with your arrow keys. Click next to continue the tour! ",
    tab = "General Overview/Trend Visualiser",
    buttons = list(list(action = "next", text = "Next")),
  )$
  step(
    el = "#tabs",
    title = "Information tabs",
    text = "This is where you can view all the different tabs to see different visualizations! Please click the second tab to continue.",
    canClickTarget = TRUE,
    advanceOn = list(selector = "#tabs li:nth-child(2)", event = "click"), 
    buttons = list()
  )$
  step(
    title = "Trend Visualiser",
    text = "This is where you can see a heatmap and histogram of the selected timeframe.",
    tab = "General Overview/Trend Visualiser"
  )$
  step(
    el = "#view",
    title = "Filter Data",
    text = "These buttons allow you to filter the data by day, month, year, or view all data. It's recommended to filter the data when using large datasets as the application may lag!",
    tab = "General Overview/Trend Visualiser",
    canClickTarget = FALSE
  )$
step(
    el = "#tabs",
    title = "Information tabs",
    text = "This is where you can view all the different tabs to see different visualizations! Please click the third tab to continue.",
    canClickTarget = TRUE,
    advanceOn = list(selector = "#tabs li:nth-child(3)", event = "click"), 
    buttons = list()
  )$

This order doesn't

conductor <- Conductor$
  new()$
  step(
    title = "Welcome to DataCops! (1/11)",
    text = "This is a tour to introduce you to our application. You can exit out of the tour at any time by pressing the Esc key, and you can control the tour with your arrow keys. Click next to continue the tour! ",
    tab = "General Overview/Trend Visualiser",
    buttons = list(list(action = "next", text = "Next")),
  )$
  step(
    el = "#tabs",
    title = "Information tabs",
    text = "This is where you can view all the different tabs to see different visualizations! Please click the second tab to continue.",
    canClickTarget = TRUE,
    advanceOn = list(selector = "#tabs li:nth-child(2)", event = "click"), 
    buttons = list()
  )$
step(
    el = "#tabs",
    title = "Information tabs",
    text = "This is where you can view all the different tabs to see different visualizations! Please click the third tab to continue.",
    canClickTarget = TRUE,
    advanceOn = list(selector = "#tabs li:nth-child(3)", event = "click"), 
    buttons = list()
  )$
  step(
    title = "Trend Visualiser",
    text = "This is where you can see a heatmap and histogram of the selected timeframe.",
    tab = "General Overview/Trend Visualiser"
  )$

This is the id of the tabsetpanel.

ui <- fluidPage(
  useConductor(),
  tabsetPanel(
  id = 'tabs',
  tabPanel("About DataCops", div(

fix 'el' to take ns() into account

In modules, the user can add a step whose 'el' is wrapped in ns(). I would need to add # automatically after ns().

Example (first one works because I manually add #, second one doesn't work):

library(shiny)
library(bs4Dash)

# Cicerone guide ----

guide <- Conductor$new()

# Module for box 1 ----

mod_box1_ui <- function(id){
  ns <- NS(id)
  box(
    id = ns("box1"),
    title = "Box 1",
    numericInput(ns("num"), label = "Enter a number", value = 5, min = 0, max = 10)
  )
}

mod_box1_server <- function(input, output, session){
  ns <- session$ns
  guide$
    step(
      el = paste0("#", ns("box1")), # use namespace
      title = "Step 1",
      text = "This is box 1."
    )
}

# Module for box 2 ----

mod_box2_ui <- function(id){
  ns <- NS(id)
  box(
    id = ns("box2"),
    title = "Box 2",
    sliderInput(ns("slide"), label = "Choose a number", value = 5, min = 0, max = 10)
  )
}

mod_box2_server <- function(input, output, session){
  ns <- session$ns
  guide$
    step(
      el = ns("box2"),
      title = "Step 2",
      text = "This is box 2."
    )
}

# Main app ----

ui <- dashboardPage(
  dashboardHeader(title = "Basic dashboard"),
  dashboardSidebar(),
  dashboardBody(
    useConductor(),
    fluidRow(
      mod_box1_ui("box1"),
      mod_box2_ui("box2")
    )
  ),
  dashboardControlbar(),
  dashboardFooter()
)



server <- function(input, output, session){
  
  callModule(mod_box1_server, "box1")
  callModule(mod_box2_server, "box2")
  
  # launch after module called
  guide$init()$start()
}

shinyApp(ui = ui, server = server)

Update to shepherd.js 0.11

TODO: arguments for step

List: https://shepherdjs.dev/docs/Step.html

• arrow
• attachTo
  • element
  • on
• advanceOn
• beforeShowPromise
• buttons
  • button.action
  • button.classes
  • button.disabled
  • button.label
  • button.secondary
  • button.text
• canClickTarget
• cancelIcon
• classes
• highlightClass
• id
• popperOptions
• scrollTo
• scrollToHandler
• showOn
• text
• when
• title

WON'T DO:

• modalOverlayOpeningPadding
• modalOverlayOpeningRadius

decide on snakecase or camelCase

deal with tabs

TODO: methods for tour

• addStep
• addSteps
• back
• cancel
• complete
• getById
• getCurrentStep
• hide
• isActive
• next
• removeStep
• show
• start

add a general example that retakes several global features

this example takes into account:

• different el types
• customizing
• tabs
• buttons

library(conductor)
library(DT)
library(shiny)

conductor <- Conductor$
  new()$
  step(
    title = "Welcome on this app!",
    text = knitr::kable(mtcars[1:5, 1:3], format = "html"),
    buttons = list(
      list(
        action = "next",
        text = "Next"
      )
    )
  )$
  step(
    el = "[data-value='Analysis']",
    title = "On this tab, you can see plots and tables."
  )$
  step(
    el = ".selectize-input",
    "Choose the variable to plot",
    "You can only pick one variable."
  )$
  step(
    "The chosen variable will be plotted here",
    el = "#plot_iris"
  )$
  step(
    el = ".irs--shiny",
    "Same thing for mtcars",
    "Slide this to filter the dataset 'mtcars' based on 'mpg' value."
  )$
  step(
    el = "#mtcars_table",
    "This is the filtered table"
  )$
  step(
    el = "#DataTables_Table_0_filter",
    "This allows you to search the table."
  )$
  step(
    el = "[data-value='About']",
    "Get more info about the app",
    "This tab is less important: it contains technical info about the app.",
    tab = "Analysis",
    tabId = "main-tabset"
  )$
  step(
    el = "p.description",
    "This is the technical info",
    tab = "About",
    tabId = "main-tabset"
  )$
  step(
    "I hope this was useful. Enjoy!",
    tab = "Analysis",
    tabId = "main-tabset",
    buttons = list(
      list(
        action = "back",
        secondary = TRUE,
        text = "Previous"
      ),
      list(
        action = "next",
        text = "Finish"
      )
    )
  )

ui <- fluidPage(
  useConductor(),
  tabsetPanel(
    id = "main-tabset",
    tabPanel(
      title = "Analysis",
      selectizeInput("iris_names", "Pick a variable", names(iris)),
      plotOutput("plot_iris"),
      sliderInput("mtcars_values", "Filter mpg values", min = min(mtcars$mpg),
                  max = max(mtcars$mpg), value = median(mtcars$mpg)),
      dataTableOutput("mtcars_table")
    ),
    tabPanel(
      title = "About",
      br(),
      br(),
      p("Hi this is the description of the app.", class = "description")
    )
  ),
  tags$head(
    tags$style(
      HTML(
        "
        .shepherd-header {
          background-color: #2d5986 !important;
        }
        .shepherd-element {
          background-color: #2d5986;
        }
        .shepherd-title {
          color: white
        }
        .shepherd-text {
          color: white
        }
        .shepherd-button {
          background-color: #4080bf 
        }
        
        .shepherd-button-secondary {
          background-color: #204060 !important;
          color: white !important;
        }
        
        .shepherd-footer {
          margin-top: 2rem;
          display: flex;
          justify-content: space-between;
        }
        
        .shepherd-arrow:before {
          background-color: #2d5986 !important;
        }
        "
      )
    )
  )
)

server <- function(input, output, session){
  conductor$init()$start()
  
  output$plot_iris <- renderPlot({
    plot(iris[[input$iris_names]])
  })
  
  output$mtcars_table <- renderDataTable({
    subset(mtcars, mpg > input$mtcars_values)
  })
  
}

shinyApp(ui, server, options = list(launch.browser = TRUE))

TODO: arguments for tour

• options
  • confirmCancel
  • confirmCancelMessage
  • classPrefix
  • defaultStepOptions
  • exitOnEsc
  • keyboardNavigation
  • stepsContainer
  • modalContainer
  • steps
  • tourName
  • useModalOverlay

TODO: methods for step

• getTarget
• isCentered
• isOpen
• updateStepOptions

Don't see the difference with tour method

• cancel
• complete
• destroy
• show
• hide

WON'T DO:

• getElement [WON'T DO: I don't see what elements of the popover could be useful]
• getTour [WON'T DO]

Issues on JS-R communication for some methods

e.g isActive or getHighlightedElement call the JS code hundreds of time

Ex: put console.log("hi") in Shiny.addCustomMessageHandler('conductor-getHighlightedElement'