GWT-Tour

A Java API for the HopScotch Framework

Contents

What is GWT-Tour?

GWT-Tour is a GWT library that wraps the HopScotch Framework and makes it easy for developers to add product tours to their pages. GWT-Tour accepts a Tour object as input and provides an API for the developer to control rendering the tour display and managing the tour progress.

Features

Event Callbacks

Callbacks for tour events: onStart, onEnd, onShow, onNext, onPrev, onClose, onError

Multi-page tours

Take your tour across pages! GWT-Tour saves state using HTML5 sessionStorage if available and falls back to using cookies as a default.

i18n support

Create tours in all the languages of the world. GWT-Tour supports customizing the language of your tour controls.

Lightweight Callouts

Create single instance callouts for those times when one is enough.

General Usage

To get started using the GWT-Tour framework, simply inherit the GwtTour module into your GWT Application <inherits name='com.eemi.gwt.tour.GwtTour'/>. Copy the img folder into the war folder of your GWT application and your are ready to go !.


  <html>
    <head>
      <title>My First GWT-Tour</title>
    </head>
    <body>
      <h1 id="header">My First GWT-Tour</h1>
      <div id="content">
        <p>Content goes here...</p>
      </div>
    </body>
  </html>

Then in your EntryPoint file, define and start your tour.


  // Define the tour!
  Tour tour = new Tour("myTour");
  
  TourStep step = new TourStep("header", Placement.RIGHT);
  step.setContent("This is the header of my page");
  step.setTitle("My Header");
  tour.addStep(step);
  
  step = new TourStep(Document.get().getElementById("content"), Placement.LEFT);
  step.setContent("THere is where I put my content.");
  step.setTitle("My content");
  tour.addStep(step);
  
  // Start the tour!
  GwtTour.startTour(tour);

That's all there is to it!

Defining a Tour

A GWT-Tour tour consists of a tour id, an array(list) of tour steps, and a number of tour-specific options. The tour id is simply a unique identifier string. The simplest tour consists of just an id string and an array of one or more steps.

Basic step options

The step options below are the most basic options.

Note that title and content are both optional only because you can choose to have a step with only a title, only content, or both title and content.

This is an example of a tour defined with only basic steps.


     
     TourStep step1 = new TourStep("header", Placement.BOTTOM);
     step1.setTite("This is the navigation menu");
     step1.setContent("Use the links here to get around the site");
     
     TourStep step2 = new TourStep("profile-pic", Placement.RIGHT);
     step2.setTite("Your profile picture");
     step2.setContent("Upload a profile picture here.");
     
     TourStep step2 = new TourStep("inbox", Placement.BOTTOM);
     step2.setTite("Your inbox");
     step2.setContent("Messages from other users will appear here.");
     
     //create the tour
     Tour tour = new Tour("welcome-tour");
     tour.setSteps(step1,step1,step3);

IMPORTANT -- title and content are set using element.innerHTML. This allows the inclusion of very basic markup like links and lists. However, it also allows the inclusion of malicious script injections when used improperly. It is highly recommended to never show user-generated content in a GWT-Tour tour. If it is absolutely necessary, you must properly escape the input, as always.

All step options

The comprehensive list of step options are listed below:

Mandatory

Optional

Setting tour options

These options apply to the entire tour. In cases where there is both a value specified in the tour options and in a step definition, (e.g. "setShowPrevButton") the step definition takes priority. When multiple callbacks are defined in both step and tour options, step callbacks are invoked before tour-wide callbacks.

API Methods

The GWT-Tour library comes with a simple set of API calls with which you can run and manage tours:

Tour Example


            Tour tour = new Tour("gwt-tour-demo");
        tour.setScrollTopMargin(100);
        tour.setShowPrevButton(true);

        TourStep step = new TourStep(Placement.BOTTOM, "gwt-tour-title");
        step.setTitle("Welcome to GWT-Tour!");
        step.setContent("Hey there! This is an example tour. There will be plenty of time to read documentation and sample code, but let's just take some time to see how GWT-Tour actually works.");
        step.centerXOffset();
        step.centerArrowOffset();
        tour.addStep(step);

        step = new TourStep(Placement.RIGHT, "general-use-desc");
        step.setTitle("Where to begin");
        step.setContent("At the very least, you'll need to include this line in your .gwt xml to get started.");
        step.setXOffset(-550);
        tour.addStep(step);

        step = new TourStep(Placement.TOP, "my-first-tour-file");
        step.setTitle("Define and start your tour");
        step.setContent("Once you have Gwt-Tour on your page, you're ready to start making your tour! The biggest part of your tour definition will probably be the tour steps.");
        tour.addStep(step);

        step = new TourStep(Placement.RIGHT, "start-tour");
        step.setTitle("Starting your tour");
        step.setContent("After you've created your tour, pass it in to the GwtTour.startTour() method to start it.");
        step.setYOffset(-25);
        tour.addStep(step);

        step = new TourStep(Placement.TOP, "basic-options");
        step.setTitle("Basic step options");
        step.setContent("These are the most basic step options: target, placement, title, and content. For some steps, they may be all you need.");
        step.setArrowOffset(100);
        tour.addStep(step);

        step = new TourStep(Placement.TOP, "api-methods");
        step.setTitle("Gwt-Tour API methods");
        step.setContent("Control your tour programmatically using these methods.");
        tour.addStep(step);

        step = new TourStep(Placement.TOP, "demo-tour");
        step.setTitle("This tour's code");
        step.setContent("This is the Java Code for the current tour! Pretty simple, right?");
        tour.addStep(step);
        
        
        step = new TourStep(Placement.BOTTOM, "gwt-tour-title");
        step.setTitle("You're all set!");
        step.setContent("Now go and build some great tours!");
        step.centerArrowOffset();
        step.centerXOffset();
        tour.addStep(step);

        GwtTour.startTour(tour);

GWT-Tour Callouts

Sometimes all you need is a simple callout. You can use Callouts to achieve this.


      Callout callout = new Callout("attach-icon", Placement.BOTTOM);
      callout.setTitle("Now you can share images &amp; files!");
      callout.setContent("Share a project you\'re proud of, a photo from a recent event, or an interesting presentation.");
      GwtTour.createCallout(callout);

Callouts come with the same options available as tour steps, so you can specify things like width, placement, offsets, and z-index. The most important difference between tour steps and callouts is that you must supply an id when creating a callout for later reference.

All management of callouts is done through the Gwt-Tour Callout Manager. The Callout Manager's job is pretty simple and comes with only a handful of API methods.

This page was built using Flat UI from designmodo.

GWT-Tour is made possible by the Hopscotch Framework.

Fork me on GitHub