create teal user guide using intro.js

[donyunardi]

Feature description

Continuation of #1010

As mentioned here, we want to try using intro.js to create guided tour on how to use teal app.

intro.js written in JS and targeting css element.

Acceptance Criteria:

• Create a very simple guided tour on how to use the teal app (i.e. explain the layout, what each button do, how to add a filter, etc.).

Code

library(teal)
library(shiny)

app <- init(
  data = teal_data(
    iris = iris[1:10, ]
  ),
  modules = modules(
    example_module(label = "my module")
  )
) |>
  modify_title(
    title = "my teal app"
  ) |>
  modify_header(
    tags$head(
      tags$link(
        rel = "stylesheet",
        href = "https://cdnjs.cloudflare.com/ajax/libs/intro.js/8.3.2/intro.min.css"
      ),
      tags$link(
        rel = "stylesheet",
        href = "https://cdnjs.cloudflare.com/ajax/libs/intro.js/8.3.2/introjs.min.css"
      ),
      tags$style(HTML("
      .introjs-tooltip {
        background-color: white !important;
        border: 1px solid #ccc !important;
        border-radius: 5px !important;
        padding: 15px !important;
        box-shadow: 0 4px 6px rgba(0,0,0,0.3) !important;
        min-width: 250px !important;
        max-width: 400px !important;
      }

      .introjs-tooltip {
        z-index: 10000000 !important;
        display: block !important;
        visibility: visible !important;
        opacity: 1 !important;
        position: absolute !important;
      }
      .introjs-overlay {
        z-index: 9999999 !important;
        opacity: 0.8 !important;
      }
      .introjs-helperLayer {
        z-index: 9999998 !important;
      }
      .introjs-tooltipbuttons {
        display: block !important;
      }
      .introjs-button {
        display: inline-block !important;
      }
    ")),
      tags$script(
        src = "https://cdnjs.cloudflare.com/ajax/libs/intro.js/8.3.2/intro.min.js"
      ),
      tags$script(HTML('
      $(document).on("shiny:connected", function() {
        setTimeout(function() {
          console.log("Starting intro.js tour");
          introJs.tour().setOptions({
            steps: [
              {x
                intro: "Welcome to my Teal app! Click Next to continue."
              },
              {
                element: document.querySelector(".teal-navbar"),
                intro: "This is the teal navigation bar."
              },
              {
                element: document.querySelector(".teal-sidebar"),
                intro: "This is the filter panel."
              },
              {
                element: document.querySelector("#teal-teal_modules-nav-my_module-teal_module_ui"),
                intro: "This is the analysis output area."
              }
            ],
            showProgress: true,
            showBullets: false,
            exitOnOverlayClick: false,
            doneLabel: "Done",
            nextLabel: "Next →",
            prevLabel: "← Back"
          }).start();
        }, 2000);
      });
    '))
    )
  )

shinyApp(app$ui, app$server)

Code of Conduct

• I agree to follow this project's Code of Conduct.

Contribution Guidelines

• I agree to follow this project's Contribution Guidelines.

Security Policy

• I agree to follow this project's Security Policy.

[llrs-roche]

I found there is an R package wrapping introjs: rintrojs.

We could add that package on Suggests and create a intro for it on a demo.
I think this could work well on a vignette or on the README as the shinylive should be able to run this and we don't need to then wrap all classes with the introBox() function if rintrojs exists.

@donyunardi, What is the acceptance criteria?

Should I create a video or just an app with some explanations or both?

[donyunardi]

We don't need video, just an app with the guided intro on how to use teal app.
I am aware of rintrojs but the last commit is 3 years ago and I'm not sure if it has the new feature that introjs has.
If you think rintrojs is enough for our use case, then I support it.

[llrs-roche]

I can create the following app with more details:

• It uses the latest version directly.
• I removed some css duplication

App

library(teal)
library(shiny)

app <- init(
  data = teal_data(
    iris = iris[1:10, ]
  ),
  modules = modules(
    example_module(label = "my module")
  )
) |>
  modify_title(
    title = "my teal app"
  ) |>
  modify_header(
    tags$head(
      tags$link(
        rel = "stylesheet",
        href = "https://unpkg.com/intro.js/introjs.css"
      ),
      tags$style(HTML("
      .introjs-tooltip {
        background-color: white !important;
        border: 1px solid #ccc !important;
        border-radius: 5px !important;
        padding: 15px !important;
        box-shadow: 0 4px 6px rgba(0,0,0,0.3) !important;
        min-width: 250px !important;
        max-width: 400px !important;
      }

      .introjs-tooltip {
        z-index: 10000000 !important;
        display: block !important;
        visibility: visible !important;
        opacity: 1 !important;
        position: absolute !important;
      }
      .introjs-overlay {
        z-index: 9999999 !important;
        opacity: 0.8 !important;
      }
      .introjs-helperLayer {
        z-index: 9999998 !important;
      }
      .introjs-tooltipbuttons {
        display: block !important;
      }
      .introjs-button {
        display: inline-block !important;
      }
    ")),
      tags$script(
        src = "https://unpkg.com/intro.js/intro.js"
      ),
      tags$script(HTML('
      $(document).on("shiny:connected", function() {
        setTimeout(function() {
          console.log("Starting intro.js tour");
          introJs.tour().setOptions({
            steps: [
              {
                intro: "Welcome! This tour will guide you through the key features of this Teal application."
              },
              {
                element: document.querySelector("#teal-teal_modules-nav-my_module-data_summary_accordion > div"),
                intro: "Data Summary: An overview of the datasets currently loaded in the application."
              },
              {
                element: document.querySelector("#teal-teal_modules-nav-my_module-filter_panel-filters-main_filter_accordion > div"),
                intro: "Filter Panel: Use this area to subset your data and refine the analysis data."
              },
              {
                element: document.querySelector("#teal-teal_modules-nav-my_module-teal_module_ui"),
                intro: "Analysis input: Input parameters for the analysis will be shown here."
              },
              {
                element: document.querySelector("#teal-teal_modules-nav-my_module-teal_module_ui"),
                intro: "Analysis output: Plots, tables, and statistics will be rendered here."
              },
              {
                element: document.querySelector("#teal-snapshot_manager_panel-show_snapshot_manager > span.icon"),
                intro: "Snapshot Manager: Save your current inputs and settings to easily recreate a specific analysis later."
              },
              {
                element: document.querySelector("#teal-teal_modules-nav-my_module-filter_panel-filters-iris-add_filter_icon"),
                intro: "Add Filters: Incorporate additional variables to your filter criteria to dynamically update your results."
              },
              {
                element: document.querySelector("#teal-filter_manager_panel-show_filter_manager > span.icon"), 
                intro: "Filter Manager: View a matrix of all active filters and see which modules they are currently affecting."
              },
              {
                element: document.querySelector(".teal.dropdown-button"),
                intro: "Module Navigation: Click here to switch between different analysis types and modules."
              },
              {
                element: document.querySelector("#teal-teal_modules-active_module_id > div.dropdown.nav-item-custom > div"),
                intro: "Breadcrumbs: This indicator tracks your location and shows which analysis is currently active."
              },
              {
                element: document.querySelector("#teal-teal_modules-nav-my_module-add_reporter_wrapper-report_add_wrapper"),
                intro: "Report Previewer: Add the current analysis to your report for later export."
              },
              {
                element: document.querySelector("#teal-reporter_menu_container"),
                intro: "Reporting Pane: Access, edit, organize and export all the analyses added to your custom report."
              },
              {
                element: document.querySelector("#teal-teal_modules-nav-my_module-source_code_wrapper-source_code-button"),
                intro: "Show Source Code: Review the underlying R code used to generate this specific output of the active analysis."
              },
              {
                element: document.querySelector("#teal-footer-session_info-sessionInfo-button"),
                intro: "Session Info: View technical details regarding the R version and package environment."
              },
              {
                element: document.querySelector("#teal-footer-session_info-identifier"),
                intro: "App Identifier: These helps support teams identify this specific application instance and environment.",
                dontShowAgain: true
              }
            ],
            showProgress: true,
            showBullets: false,
            exitOnOverlayClick: false,
            doneLabel: "Done",
            nextLabel: "Next →",
            prevLabel: "← Back"
          }).start();
        }, 2000);
      });
    '))
    )
  ) |> runApp()

Adding an interactive tour to be triggered whenever the user wants is a bit more complicated, but might be something to consider.

# Inside your Teal UI definition or a sidebar
actionButton(
  inputId = "start_tour", 
  label = "Take a Tour", 
  icon = icon("info-circle"),
  class = "btn-info" # Optional: gives it a blue/teal professional look
)
# Inside server side
observeEvent(input$start_tour, {
  shinyjs::runjs("startTealTour();")
})

The disadvantage is that this might change depending on what the users is doing at any given moment. For example I was playing with generating a hint that showed the snapshots but as I can't easily click in the middle of the tour it won't be easy. Depending on how much we would like rintrojs could (probably) handle that for us, but at the cost of more delay. I'll need to explore it a bit more this

Last question is where this app will be hosted, on teal.gallery? On a vignette and rendered with shinylive?

[donyunardi]

I'll need to explore it a bit more this

Yes, please do. It would be cool if we can allow interaction.

Last question is where this app will be hosted, on teal.gallery? On a vignette and rendered with shinylive?

I think vignette and shinylive idea would be a good idea!