Package: jupyterlab-tour
jupyterlab-tourA JupyterLab UI Tour based onreact-joyride.InstallTo install the extension, execute:pipinstalljupyterlab-tourorcondainstall-cconda-forgejupyterlab-tourFeaturesThis extension has the following features:Default tours:Welcome tourNotebook tourUser-defined features in SettingsToast proposing to start a TourIf a Tour has already be seen by the user, this is saved in the state database. So you
can start Tour on event only if the user have not seen it; e.g. theWelcome Touris
launched at JupyterLab start except if the user have seen it.The state is cleaned if this extension is updatedTooltip are styled using JupyterLab theming systemCommands toaddandlaunchtoursThrough theTour Manager(ITourManagerextension token), add, modify or delete a
TourConnect to Tour events through signalsOverride the default style (and options) for the Tour separatelyThis extension is inspired by@cdat/jupyterlab-tutoriallicensed under
BSD 3-Clause License with Copyright (c) 2020, Lawrence Livermore National Security, LLC.RequirementsJupyterLab >= 3.6For JupyterLab 2.x, have lookthere.For developers, the API has changed between v3 (for JupyterLab 3) and v2 (for
JupyterLab 2).How to add a Tour with Advanced SettingsAs a user of JupyterLab, after you've installedjupyterlab-tour, you can create your
ownToursas data.Open the JupyterLabAdvanced SettingspanelCtrl+,SelectToursfrom list of settings groupsIn the editor, create JSON(5) compatible with thereact-joyride data modelTheTourwill be available from theHelp Menu, as well as theCommand PaletteA simple TourFor example, to show a glowing button on the Jupyter logo, which reveals an orange
overlay when pressed:// json5 can have comments
{
  tours: [
    {
      id: 'my-tour',
      label: 'My First Tour',
      // steps are required, and have many, many options
      steps: [{ target: '#jp-MainLogo', content: 'Look at this!' }],
      // below here not required!
      options: {
        styles: {
          options: {
            // you can use jupyterlab theme variables
            backgroundColor: 'var(--jp-warn-color0)'
          }
        }
      }
    }
  ]
}How to add a Tour to a NotebookThe same JSON used to create a Tour inAdvanced Settingscan be added to a Notebook.Open the NotebookOpen theProperty Inspectorsidebar (the "gears" icon)OpenAdvanced ToolsCreate a key inNotebook Metadatalike:{"jupyterlab-tour":{"tours":[]}}Now, when the notebook is opened, a "pin" icon will be visible in theNotebook Toolbarwhich will allow lauching one (or all) of the tours saved in the Notebook.Shipping a Tour to BinderOn Binder, and elsewhere, you can store the above (withoutcomments) in anoverrides.jsonfile and put it in theright place, e.g.{sys.prefix}/share/jupyter/lab/settings/overrides.json. When JupyterLab is next
opened, those overrides will become the defaults, and your Tour will be available.An exampleoverrides.jsonmight look like:{"jupyterlab-tour:user-tours":{"tours":[]}}How to add Tour for my JupyterLab extensionAs an extension developer, there are two methods to add a tour: the easiest is to use
JupyterLab commands and the advanced version is to request this extension tokenITourManager.Add a Tour with TypeScriptconst{commands}=app;// Add a Tour - returns the Tour or null if something went wrongconsttour=(awaitapp.commands.execute('jupyterlab-tour:add',{tour:{// Tour must be of type ITour - see src/tokens.tsid:'test-jupyterlab-tour:welcome',label:'Welcome Tour',hasHelpEntry:true,steps:[// Step must be of type IStep - see src/tokens.ts{content:'The following tutorial will point out some of the main UI components within JupyterLab.',placement:'center',target:'#jp-main-dock-panel',title:'Welcome to Jupyter Lab!'},{content:'This is the main content area where notebooks and other content can be viewed and edited.',placement:'left-end',target:'#jp-main-dock-panel',title:'Main Content'}]// can also define `options`}}))asITourHandler;if(tour){app.commands.execute('jupyterlab-tour:launch',{id:'test-jupyterlab-tour:welcome',force:false// Optional, if false the Tour will start only if the user have not seen or skipped it});}One example is available onMamba navigator.
Test it onbinder.If you want to react to step changes to trigger elements of the UI (like opening
sidebar), you can connect to thestepChangedsignal. Building from the previous
example, this snippet will open the filebrowser after the first step.tour.stepChanged.connect((_,data)=>{switch(data.type){case'step:after':if(data.step.target==='#jp-main-dock-panel'){commands.execute('filebrowser:activate');}break;}});datais an object of typeCallbackProps.Disabling the User, Notebook, and Default ToursIf youonlywish to see the defaultWelcomeandNotebooktours, or ones defined by
users, they can be disabled via the command line or a well-known file.The examples below disable all tours not provided by third-party extensions. Addingjupyterlab-tour:pluginto either of these will disable tours altogether!Disabling Tours from the Command LineFrom the command line, run:jupyterlabextensiondisable"jupyterlab-tour:user-tours"jupyterlabextensiondisable"jupyterlab-tour:notebook-tours"jupyterlabextensiondisable"jupyterlab-tour:default-tours"Disabling Tours withpageConfig.jsonCreate apageConfig.jsonand put it inthe right place, e.g.{sys.prefix}/etc/jupyter/labconfig/pageconfig.jsonand add the plugin IDs todisabledExtensions.{"disabledExtensions":{"jupyterlab-tour:user-tours":true,"jupyterlab-tour:notebook-tours":true,"jupyterlab-tour:default-tours":true}}UninstallTo remove the extension, execute:pipuninstalljupyterlab-tourorcondaremove-cconda-forgejupyterlab-tourContributingDevelopment installNote: You will need NodeJS to build the extension package.Thejlpmcommand is JupyterLab's pinned version ofyarnthat
is installed with JupyterLab. You may useyarnornpmin lieu ofjlpmbelow.# Clone the repo to your local environment# Change directory to the jupyterlab-tour directory# Install package in development modepipinstall-e"."# Link your development version of the extension with JupyterLabjupyterlabextensiondevelop.--overwrite# Rebuild extension Typescript source after making changesjlpmbuildYou can watch the source directory and run JupyterLab at the same time in different
terminals to watch for changes in the extension's source and automatically rebuild the
extension.# Watch the source directory in one terminal, automatically rebuilding when neededjlpmwatch# Run JupyterLab in another terminaljupyterlabWith the watch command running, every saved change will immediately be built locally and
available in your running JupyterLab. Refresh JupyterLab to load the change in your
browser (you may need to wait several seconds for the extension to be rebuilt).By default, thejlpm buildcommand generates the source maps for this extension to
make it easier to debug using the browser dev tools. To also generate source maps for
the JupyterLab core extensions, you can run the following command:jupyterlabbuild--minimize=FalseDevelopment uninstallpipuninstalljupyterlab-tourIn development mode, you will also need to remove the symlink created byjupyter labextension developcommand. To find its location, you can runjupyter labextension listto figure out where thelabextensionsfolder is located.
Then you can remove the symlink namedjupyterlab-tourwithin that folder.Testing the extensionFrontend testsThis extension is usingJestfor JavaScript code testing.To execute them, execute:jlpm
jlpmtestIntegration testsThis extension usesPlaywrightfor the integration
tests (aka user level tests). More precisely, the JupyterLab helperGalatais used to handle
testing the extension in JupyterLab.More information are provided within theui-testsREADME.Packaging the extensionSeeRELEASE