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.
Callbacks for tour events: onStart, onEnd, onShow, onNext, onPrev, onClose, onError
Take your tour across pages! GWT-Tour saves state using HTML5 sessionStorage if available and falls back to using cookies as a default.
Create tours in all the languages of the world. GWT-Tour supports customizing the language of your tour controls.
Create single instance callouts for those times when one is enough.
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:
setTarget[STRING/ELEMENT/ARRAY] - id of the target DOM element or DOM element itself. It is also possible to define an array of several targets. If an array is provided, Hopscotch will use the first target that exists on the page and disregard the rest.
setPlacement[PLACEMENT] - specifies where the bubble should appear in relation to the target. Valid values are "top", "bottom", "right", "left".
setTitle[STRING] - step title
setContent[STRING] - step content
setWidth[INT] - bubble width
setPadding[INT] - bubble padding
setXOffset[INT] - horizontal position adjustment for bubble. Default: 0.
setYOffset[INT] - vertical position adjustment for bubble. Default: 0.
setArrowOffset[INT] - offset for the bubble arrow. Default: 0.
setDelay[INT] - number in milliseconds to wait before showing step. Default: 0.
setZindex[INT] - sets the z-index of the bubble
setShowNextButton[BOOLEAN] - should show the next button. Default: true.
setShowPrevButton[BOOLEAN] - should show the prev button. Default: true.
setShowCTAButton[BOOLEAN] - should show the call-to-action button. Default: false.
setCtaLabel[STRING] - label for the call-to-action button.
setMultipage[BOOLEAN] - indicates that the next step is on a different page. Default: false.
setShowSkip[BOOLEAN] - if true, 'Next' button reads 'Skip'. Default: false.
setFixedElement[BOOLEAN] - set to true if the target element has fixed positioning. Default: false.
setNextOnTargetClick[BOOLEAN] - triggers nextStep() when the target is clicked. Default: false.
onPrev[FUNCTION] - callback for when 'Previous' button is clicked}
onNext[FUNCTION] - callback for when 'Next' button is clicked}
onShow[FUNCTION] - callback for when step is first displayed}
onCTA[FUNCTION] - callback for the optional call-to-action button}
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.
setBubbleWidth[DOUBLE] - Default bubble width. Default: 280.
setBubblePadding[DOUBLE] - Default bubble padding. Default: 15.
setSmoothScroll[BOOLEAN] - Should the page scroll smoothly to the next step? Default: true.
setScrollDuration[DOUBLE] - Duration of page scroll in milliseconds. Only relevant when smoothScroll is set to true. Default: 1000.
setScrollTopMargin[DOUBLE] - When the page scrolls, how much space should there be between the bubble/targetElement and the top of the viewport? Default: 200.
setShowCloseButton[BOOLEAN] - Should the tour bubble show a close (X) button? Default: true.
setShowPrevButton[BOOLEAN] - Should the bubble have the Previous button? Default: false.
setShowNextButton[BOOLEAN] - Should the bubble have the Next button? Default: true.
setArrowWidth[DOUBLE] - Default arrow width. (space between the bubble and the targetEl) Used for bubble position calculation. This option is provided for the case where the developer wants to use custom CSS to adjust the size of the arrow. Default: 20.
setSkipIfNoElement[BOOLEAN] - If a specified target element is not found, should we skip to the next step? Default: true.
setNextOnTargetClick[BOOLEAN] - Should we advance to the next step when the user clicks on the target? Default: false.
onNext[FUNCTION] - Invoked after every click on a "Next" button.
onPrev[FUNCTION] - Invoked after every click on a "Prev" button.
onStart[FUNCTION] - Invoked when the tour is started.
onEnd[FUNCTION] - Invoked when the tour ends.
onClose[FUNCTION] - Invoked when the user closes the tour before finishing.
onError[FUNCTION] - Invoked when the specified target element doesn't exist on the page.
setNextBtnText[STRING] - Label for next button
setPrevBtnText[STRING] - Label for prev button
setDoneBtnText[STRING] - Label for done button
setSkipBtnText[STRING] - Label for skip button
setCloseTooltip[STRING] - Text for close button tooltip
] - Provide a list of strings to be shown as the step number, based on index of array. Unicode characters are supported. (e.g., ['一', '二', '三']) If there are more steps than provided numbers, Arabic numerals ('4', '5', '6', etc.) will be used as default.
The GWT-Tour library comes with a simple set of API calls with which you can run and manage tours:
GwtTour.startTour(tour, stepNum)- Actually starts the tour. Optional stepNum argument specifies what step to start at.
GwtTour.showStep(idx)- Skips to a given step in the tour
GwtTour.prevStep()- Goes back one step in the tour
GwtTour.nextStep()- Goes forward one step in the tour
GwtTour.endTour([clearCookie])- Ends the current tour. If clearCookie is set to false, the tour state is preserved. Otherwise, if clearCookie is set to true or is not provided, the tour state is cleared.
GwtTour.configure(options)- Sets options for running the tour. See above section "Setting tour options" for a list of configuration options.
GwtTour.getCurrTour()- Returns the currently running tour.
GwtTour.getCurrStepNum()- Returns the current zero-based step number.
GwtTour.getState()- Checks for tour state saved in sessionStorage/cookies and returns the state if it exists. Use this method to determine whether or not you should resume a tour.
gwt-tour.resetDefaultI18N()- Resets i18n strings to original default values.
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);
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 & 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.
GwtTour.createCallout(options)- Creates callout referenced by an id. Options are the same as tour step options, where applicable.
GwtTour.removeCallout(id)- Removes the callout for the given id from the page.
GwtTour.removeAllCallouts()- Removes all registered callouts from the page.
This page was built using Flat UI from designmodo.
GWT-Tour is made possible by the Hopscotch Framework.