Galaxy Interactive Tours

name: inverse
layout: true
class: center, middle, inverse

</span></div>

</span></div>

---

# Galaxy Interactive Tours

<div class="contributors-line">
		Authors: 
<a href="/training-material/hall-of-fame/bebatut/" class="contributor-badge contributor-bebatut"><img src="/training-material/assets/images/orcid.png" alt="orcid logo"/><img src="https://avatars.githubusercontent.com/bebatut?s=27" alt="Avatar">Bérénice Batut</a>

<a href="/training-material/hall-of-fame/bgruening/" class="contributor-badge contributor-bgruening"><img src="/training-material/assets/images/orcid.png" alt="orcid logo"/><img src="https://avatars.githubusercontent.com/bgruening?s=27" alt="Avatar">Björn Grüning</a>

</div>

<div class="footnote" style="bottom: 8em;"><i class="far fa-calendar" aria-hidden="true"></i><span class="visually-hidden">last_modification</span> Updated: Jul 9, 2021</div>

<div class="footnote" style="bottom: 6em;">

<i class="fas fa-file-alt" aria-hidden="true"></i><span class="visually-hidden">text-document</span><a href="slides-plain.html"> Plain-text slides</a>
</div>

<div class="footnote" style="bottom: 2em;">
    <strong>Tip: </strong>press <kbd>P</kbd> to view the presenter notes
    | <i class="fa fa-arrows" aria-hidden="true"></i><span class="visually-hidden">arrow-keys</span> Use arrow keys to move between slides

</div>

???
Presenter notes contain extra information which might be useful if you intend to use these slides for teaching.

Press `P` again to switch presenter notes off

Press `C` to create a new window where the same presentation will be displayed.
This window is linked to the main window. Changing slides on one will cause the
slide to change on the other.

Useful when presenting.

---

### <i class="far fa-question-circle" aria-hidden="true"></i><span class="visually-hidden">question</span> Questions

- What is a Galaxy Interactive Tour?

- How to create a Galaxy Interactive Tour?

---

### <i class="fas fa-bullseye" aria-hidden="true"></i><span class="visually-hidden">objectives</span> Objectives

- Discover what is a Galaxy Interactive Tour

- Be able to create a Galaxy Interactive Tour

- Be able to add a Galaxy Interactive Tour in a Galaxy instance

---

### What are Galaxy Interactive Tours?

![Gif showing an interactive tour. The interface goes through uploading a dataset and several popups show up on the UI to help guide the user in a simple analysis.](../../images/galaxy_tour_demo.gif)

An awesome way to learn how to use Galaxy or a specific tool, isn't it?

---

### How does it work?

![Screenshot of part of a tour, the tour is written in YAML and has a steps section with the various steps.](../../images/galaxy_tour_yml.png)

A single YAML file: [core.galaxy_ui.yaml](https://raw.githubusercontent.com/galaxyproject/galaxy/097300ea6219e14b66b23a0e05f2808b16f10015/config/plugins/tours/core.galaxy_ui.yaml)

---

### At the top of the YAML:<br>Metadata related to the Tour

```
id: galaxy_ui
name: Galaxy UI
description: A gentle introduction to the Galaxy User Interface
title_default: "Welcome to Galaxy"
```

---

### Content of the YAML:<br>Steps of the Tour

```
# A tour is made of several steps, each of them beginning with a dash '-'
steps:
    - title: "Welcome to Galaxy"
      content: "This short tour will guide you through Galaxy's user interface.<br>
                You can navigate with your arrow keys and leave the tour at any
                time point with 'Escape' or the 'End tour' button."
      backdrop: true

- title: "Upload your data"
      element: ".upload-button"
      content: "Galaxy supports many ways to get in your data.<br>
               Use this button to upload your data."
      placement: "right"
      postclick:
        - ".upload-button"
```

---

### Definition of a step

Argument | Description
---  | ---
`title`  | Header of each step-container
`content` | Text that is shown to the user
`element` | [JQuery Selector](https://api.jquery.com/category/selectors/) of the element you want to describe / click
`placement` | Placement of the text box relative to the selected element
`preclick` or `postclick` | Elements that receive a click() event before (`preclick`) or after (`postclick`) the step is shown
`textinsert` | Text to insert if element is a text box (e.g. tool search or upload)
`backdrop` | `true/false`: 	Show a dark backdrop behind the popover and its element, highlighting the current step

.footnote[[Full reference of the properties](https://bootstraptour.com/api/)]

---

### How to obtain the JQuery Selector of the element?

![A gif showing the 'inspect element' tool in the browser being used to find the ID of an element.](../../images/interactive_tour_element_grabbing.gif)

---

### Want to integrate Interactive Tours in your Galaxy instance?

- Select a YAML file
  - [From our community collection of Interactive Tours](https://github.com/galaxyproject/galaxy-tours)
  - Create one by yourself
- Copy it to your tours directory or your Galaxy instance
  - default: `config/plugins/tours`
  - configurable via `tour_config_dir` in `galaxy.yml`
- Restart Galaxy or reload the tour with the API, e.g.:
  - `curl GALAXY_URL/api/tours/TOUR_FILE_NAME -d key=ADMIN_API_KEY`

---

### Want to contribute?

- Create Tours and share them with the world!
  - on the [community collection of Interactive Tours](https://github.com/galaxyproject/galaxy-tours) or
  - add them to the [Galaxy Training Network](https://training.galaxyproject.org/training-material)
- Improve the Tours implementation
- Improve creating of Tours
  - by enhancing the [Galaxy Tour Builder](https://github.com/dannon/tourbuilder) web extension

---

### Developing the Tours logic

- Tours initialisation: `lib/galaxy/tours/__init__.py`
- JavaScript logic: `client/galaxy/scripts/mvc/tours.js`
- Tour styles: `client/galaxy/style/less/tour.less`
- API: `lib/galaxy/webapps/galaxy/api/tours.py`
  - `lib/galaxy/webapps/galaxy/buildapp.py`
- bootstrap-tour library: `client/galaxy/scripts/libs/bootstrap-tour.js`

---
### <i class="fas fa-key" aria-hidden="true"></i><span class="visually-hidden">keypoints</span> Key points

- An Interactive Tour is easy to create: just a yaml file to fill

- Use the Developper Tools of find the JQuery Selector

- Help yourself by using the available web plugins and record an interactive tour

---

## Thank You!

This material is the result of a collaborative work. Thanks to the [Galaxy Training Network](https://training.galaxyproject.org) and all the contributors!

</div>

</div>

<a rel="license" href="https://creativecommons.org/licenses/by/4.0/">
This material is licensed under the Creative Commons Attribution 4.0 International License</a>.