Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add user tours in Advanced Settings #17

Merged
merged 13 commits into from
May 9, 2021
Merged

Add user tours in Advanced Settings #17

Show file tree
Hide file tree
Changes from 10 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
4da61b9
add user tours
bollwyvl May 7, 2021
8778e6c
fix settings package name
bollwyvl May 7, 2021
f336b09
unify types, split steps/options
bollwyvl May 7, 2021
eda3576
refactor into mutiple plugins
bollwyvl May 7, 2021
bff1634
revert some signature changes
bollwyvl May 7, 2021
6213e36
update tests for multiple plugins
bollwyvl May 8, 2021
6958a0a
update react-joyride to 2.3, fix some typing issues
bollwyvl May 8, 2021
a085136
refactor new user stuff into separate manager, expose token
bollwyvl May 8, 2021
8cf1d21
typos
bollwyvl May 8, 2021
d0a07c6
rename ExtendedPlacement to StepPlacement
bollwyvl May 8, 2021
5c5e75c
Update src/userTourManager.ts
bollwyvl May 9, 2021
66b0f95
add cli docs
bollwyvl May 9, 2021
cefa2d7
fix rejection
bollwyvl May 9, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -111,3 +111,6 @@ dmypy.json
# OSX files
.DS_Store
coverage/

# logs
*.log
108 changes: 98 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,11 +10,26 @@ A JupyterLab UI Tour based on [react-joyride](https://docs.react-joyride.com).

![demo](https://raw.githubusercontent.com/jupyterlab-contrib/jupyterlab-tour/master/doc/tourDemo.gif)

## Install

```bash
pip install jupyterlab-tour
```

or

```bash
conda install -c conda-forge jupyterlab-tour
```

## Features

This extension has the following features:

- Default tours:
- Welcome tour
- Notebook tour
- User-defined features in Settings
- Toast proposing to start a tour - to experienced users the need to exit each time the tour.
- If 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. the welcome tour is launched at JupyterLab start except if the user have seen it.

Expand All @@ -36,9 +51,70 @@ For JupyterLab 2.x, have look [there](https://github.com/jupyterlab-contrib/jupy

> For developers, the API has changed between v3 (for JupyterLab 3) and v2 (for JupyterLab 2).

## How to add a tour with Advanced Settings

As a user of JupyterLab, after you've installed `jupyterlab-tour`, you can create
your own _Tours_ as data.

- Open the JupyterLab _Advanced Settings_ panel <kbd>Ctrl+,</kbd>
- Select _Tours_ from list of settings groups
- In the editor, create JSON(5) compatible with the
[react-joyride data model](https://docs.react-joyride.com/props)
- The _Tour_ will be available from the _Help Menu_, as well as the _Command Palette_

### A simple Tour

For example, to show a glowing button on the Jupyter logo, which reveals an orange
overlay when pressed:

```json5
// 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)"
}
}
}
}
]
}
```

### Shipping a Tour to Binder

On Binder, and elsewhere, you can store the above (_without_ comments) in
an [overrides.json] file and put it in the _right 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 example `overrides.json` might look like:
```json5
{
"jupyterlab-tour:user-tours": {
"tours": [
// that tour up there!
]
}
}
```

[overrides.json]: https://jupyterlab.readthedocs.io/en/stable/user/directories.html#overrides-json

## How to add tour for my JupyterLab extension

There are two methods to add a tour: the easiest is to use JupyterLab commands and the advanced version is to request this
As 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 token `ITourManager`.

### Add easily a tour
Expand All @@ -49,7 +125,7 @@ const { commands } = app;
const tour = (await app.commands.execute('jupyterlab-tour:add', {
tour: { // Tour must be of type ITour - see src/tokens.ts
id: 'test-jupyterlab-tour:welcome',
label: 'Welcome Tour',
label: 'Welcome Tour',
hasHelpEntry: true,
steps: [ // Step must be of type IStep - see src/tokens.ts
{
Expand All @@ -66,7 +142,8 @@ const tour = (await app.commands.execute('jupyterlab-tour:add', {
target: '#jp-main-dock-panel',
title: 'Main Content'
}
]
],
// can also define `options`
}
})) as ITour;
if ( tour ) {
Expand All @@ -80,18 +157,29 @@ if ( tour ) {
> One example is available on [Mamba navigator](https://github.com/mamba-org/gator/blob/master/packages/labextension/src/index.ts#L76).
> Test it on [binder](https://mybinder.org/v2/gh/mamba-org/gator/master?urlpath=lab).

## Install
## Disabling the User and Default Tours

```bash
pip install jupyterlab-tour
```
If you _only_ wish to see the default _Welcome_ and _Notebook_ tours, or ones
defined by users, create a [pageConfig.json] and put it in _the right place_, e.g.
`{sys.prefix}/etc/jupyter/labconfig/pageconfig.json` and add the plugin IDs to
`disabledExtensions`.

or
For example, to disable all tours not provided by other extensions:

```bash
conda install -c conda-forge jupyterlab-tour
```json
{
"disabledExtensions": {
"jupyterlab-tour:user-tours": true,
"jupyterlab-tour:default-tours": true,
}
}
```

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What about adding the alternative with the command line. Something like

Alternatively, you can also use the following commands:

jupyter labextension disable "jupyterlab-tour:user-tours"
jupyter labextension disable "jupyterlab-tour:default-tours"

To enable the extension, use jupyter labextension enable ....

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

good call, 66b0f95

Adding `"jupyterlab-tour:plugin": true` will disable _all_ tours!

[pageConfig.json]: https://jupyterlab.readthedocs.io/en/stable/user/directories.html#labconfig-directories


## Uninstall

```bash
Expand Down
8 changes: 5 additions & 3 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,8 @@
"files": [
"lib/**/*.{d.ts,eot,gif,html,jpg,js,js.map,json,png,svg,woff2,ttf}",
"style/**/*.{css,eot,gif,html,jpg,json,png,svg,woff2,ttf}",
"style/index.js"
"style/index.js",
"schema/*.json"
],
"main": "lib/index.js",
"types": "lib/index.d.ts",
Expand Down Expand Up @@ -49,6 +50,7 @@
"@jupyterlab/apputils": "^3.0.0",
"@jupyterlab/mainmenu": "^3.0.0",
"@jupyterlab/notebook": "^3.0.0",
"@jupyterlab/settingregistry": "^3.0.0",
"@jupyterlab/statedb": "^3.0.0",
"@lumino/coreutils": "^1.5.3",
"@lumino/disposable": "^1.4.3",
Expand All @@ -57,7 +59,7 @@
"jupyterlab_toastify": "^4.1.2",
"react": "^17.0.1",
"react-dom": "^17.0.1",
"react-joyride": "^2.2.1"
"react-joyride": "^2.3.0"
},
"devDependencies": {
"@babel/core": "^7.11.0",
Expand All @@ -67,7 +69,6 @@
"@types/jest": "^26.0.0",
"@types/react": "^17.0.0",
"@types/react-dom": "^17.0.0",
"@types/react-joyride": "^2.0.5",
"@typescript-eslint/eslint-plugin": "^2.27.0",
"@typescript-eslint/parser": "^2.27.0",
"eslint": "^7.5.0",
Expand All @@ -89,6 +90,7 @@
],
"jupyterlab": {
"extension": true,
"schemaDir": "schema",
"outputDir": "jupyterlab_tour/labextension",
"sharedPackages": {
"jupyterlab_toastify": {
Expand Down
Loading