Defining a visit scenario

In order to offer a welcome visit to a user, it is necessary to define this in the site skin . This is done in several stages:

  1. Loading resources on the page
  2. Scenario definition (the sequence of elements to be presented with associated text)
  3. Definition of transitions (optional)

Loading resources on the page

A number of javascript and css files need to be loaded into the page for the tour. To do this, you need to import the XSL helper provided by the plugin and call the two templates "css" and "welcome-tour-js".

<xsl:import href="plugin:welcome-tour://stylesheets/helper.xsl"/>

<xsl:template name="additionnal-css">
    <xsl:call-template name="welcome-tour-css"/>
</xsl:template>

<xsl:template name="additionnal-script">
    <xsl:call-template name="welcome-tour-js"/>
</xsl:template>

Rather than directly loading the SCSS provided by the plugin, you can override it with your own SCSS file, which imports the plugin's SCSS. The plugin 's SCSS provides a number of variables that make it easy to override the main elements.
You'll then need to load your SCSS directly, taking care to load it only if the site parameter is enabled.

Defining the scenario

The tour will highlight a series of elements on the page by displaying an explanatory tooltip.

The scenario is defined using a JSON table in the file"skins/MASKIN/conf/tour-scenario.json".

[{
  "title": "Bienvenue dans votre nouvel intranet.",
  "description": "Nous vous proposons une visite guidée pour vous <a href=\"#\">familiariser</a> avec ce nouvel outil."
}, {
    "selector": "#ametys-cms-zone-documents .events-calendar",
  "title": "Agenda",
    "description": "Par défaut, l’agenda affiche  les événements du jour.<br/>S’il n’y en a pas, il affichera les 4 prochains.<br/><strong>Cliquez sur une date</strong> pour voir tous les événements associés à cette journée."
}]

Each step of the tour is a JSON Object accepting the following fields:

  • title: tooltip title (may contain html)
  • iconCls : si présent, un élement <span class="icon $iconCls"></span> sera ajouté devant le titre
  • description: the description of the tooltip (may contain html)
  • selector: a CSS selector used to target the element to be highlighted. If no selector is present, the tooltip will be positioned in the middle of the screen and no element will be highlighted. If a selector is present but does not correspond to any element on the page, the step will be skipped.
  • selectorFn: rather than a CSS selector, it's possible to provide a JS function that takes the step definition as a parameter and returns the element to be highlighted. This function will be called before each display of the step, allowing dynamic information (such as screen size, for example) to be taken into account.

Defining transitions

Some elements of a skin may be hidden behind an interaction (e.g. a click to open a menu). To include these hidden elements in your tour, you'll need to simulate these interactions. To do this, you can redefine the "AmetysFront.WelcomeTour.transitionFunction" method. This method is called at each transition between two stages and takes as parameters the definition of the current stage and the definition of the target stage, and must return the delay to wait before displaying the next stage. This delay allows you to wait for an animation, for example.

AmetysFront.WelcomeTour.transitionFunction = function(currentStep, nextStep)
{
  // implémentez ici les logiques dont vous avez besoin comme transition
// n'oubliez pas que cette méthode est appelée entre chaque étape.

return 0; // le délai avant de passer à l'étape suivante
}
Back to top