========================
Tours
========================

.. include:: ../incomplete.rst

Enabling stack tours
====================

For tours to be displayed :ref:`has_tour` needs to be ``true`` in
:ref:`stacks`.

Building stack tours
====================

Tours are defined in yaml files in a stack's ``help/`` directory. These tours
get loaded and displayed for a stack on the top of the stack page.

.. image:: ./images/stack_tour.png


A Tour yaml file holds a definition for a Hopscotch tour. Hopscotch is a
framework created by LinkedIn to help create tours (http://linkedin.github
.io/hopscotch/).

.. code-block:: none

  # A unique id for a tour. Feature tours should start with 'feature-', stack tours should start with 'stack-'
  id: "stack-ranked-list-2-guide-me"
  # The name for the tour. Appears in the drop-down list of tours
  name: "Welcome to the new Ranked List slice"
  # Set this to the current time when saving changes to the tour which would warrant a user seeing it again.
  updated: 2017-10-31 17:34:47.702913+00:00
  # If false, tour will only appear when new or updated for the user.
  show_all_the_time: true
  # JSON definition for Hopscotch tour
  definition:
  - "yOffset": 20
    "content": "Welcome to the new Ranked List slice!"
    "placement": "top"
    "target": ".slug-rl2"
    "title": "Ranked List Tour"

id (tours)
----------

An unique id for a tour. All stack tour ids must start with the
string 'stack-'.

:Optional: No
:Values: An up to 70 character string that must start with 'stack-'
:Example:
    .. code-block:: none

        id: "stack-welcome-tour"

name (tours)
------------

The name of the tour. This name will appear in the drop-down list of tours if the stack has more than one tour.

:Optional: No
:Values: An up to 200 character string
:Example:
    .. code-block:: none

        name: "Take this tour to see all the cool features of this stack"

updated
-------

A timestamp for when the tour was updated. Set this to the current time when saving changes to the
tour which would warrant a user seeing it again.

:Optional: No
:Values: A timestamp in the format YYYY-MM-DD HH:MM:SS
:Example:
    .. code-block:: none

        updated: 2017-10-31 00:00:00

show_all_the_time
-----------------

A flag that indicates if the tour should always show up in the drop down list of tours. If ``false``, the
tour will only appear when new or updated.

:Optional: Yes, default is true
:Values: boolean, true or false
:Example:
    .. code-block:: none

        show_all_the_time: false

definition
----------

The JSON definition for the Hopscotch tour. The most basic tour has the following definition:

:Optional: No
:Values: A JSON definition of the tour.
:Example:
    .. code-block:: none

      # JSON definition for Hopscotch tour
      definition:
      - "content": "Welcome to the new Ranked List slice!"
        "placement": "top"
        "target": ".slug-rl2"
        "title": "Ranked List Tour"


Triggering tours from slices
============================

Sometimes users want more explanation when they're directly looking at a slice.
We now provide a way to launch a specific tour from a slice.

.. image:: ./images/slice_guide_me.png

This is provided by adding a link called "GUIDE ME" in the top-left corner of
the slice (next to where the legend shows up). The link is enabled by providing
the id of a tour as the ``guide`` for a slice.:

.. code-block:: none

  - slice_type: "free-form"
    slug: "overview"
    title: "Overview"
    guide: "stack-welcome-tour"

The location of the link can be changed with the slice's :ref:`layout` config
option in :ref:`slice-options`.

.. code-block:: yaml

  - slice_type: "free-form"
    slug: "overview"
    title: "Overview"
    guide: "stack-welcome-tour"
    config:
      layout:
        "top-right": ["guide", "search"]

The default label of the link ("GUIDE ME") can be also be changed with the
``guideLabel`` option:

.. code-block:: yaml

  - slice_type: "free-form"
    slug: "overview"
    title: "Overview"
    guide: "stack-welcome-tour"
    guideLabel: "Take a tour"