com.smartgwt.client.util.tour

Class Tour

java.lang.Object

com.smartgwt.client.core.BaseClass

com.smartgwt.client.util.workflow.Process

com.smartgwt.client.util.tour.Tour

All Implemented Interfaces:

com.google.gwt.event.shared.HasHandlers, HasFinishedHandlers, HasTraceElementHandlers

Direct Known Subclasses:

Tutorial

public class Tour
extends Process

The Tour class allows you to build tours and tutorials for end users, highlighting specific components on the page and prompting for specific user-interactions.

Tours are a specific type of Workflow Process and consist of a series of TourSteps. Typically each step refers to an element on the page, which is either being highlighted for the user, or, for a tutorial, is an element that the user is being prompted to interact with (see TourStep.clickTarget, for example).

Most steps have a TourWindow, which shows explanatory or instructional text. For tutorial steps that request a user action, the target can be highlighted and a large arrow is shown pointing at the target.

The placement of the TourWindow and arrow is automatic, and intelligently takes into account the type of interaction requested. For example, if a tutorial requires a user to change a value in a SelectItem, the TourWindow and arrow will avoid appearing underneath the select, where they could be occluded by the drop-down picklist. Similarly, for a drag and drop interaction, the TourWindow avoids overlapping both the drag source and the drop area.

Because of all this automatic behavior, a tutorial step typically consists of just:

1. explanatory text (tourStep.title and tourStep.description)
2. the target
3. the expected interaction (eg click the target, or type something in, or drag something to another widget)
4. validation of input (what was typed or chosen), if applicable

Developers may use AutoTest locators to specify specific components or elements as action targets. Using locators means that tours and tutorials will typically still work even if your application changes (for example, new controls are added). Note that we recommend making use of the locator shortcut to rapidly generate locators.

A tour is typically written as a .proc.xml document stored in the folder configured via the project.processes setting in server.properties (webroot/processes by default). They may be loaded via the loadTour() method.

The Tour feature is available with Power or better licenses only See smartclient.com/product for details.
It requires the standard DataBinding and optional Tour module.

Field Summary

Fields inherited from class com.smartgwt.client.core.BaseClass

config, configOnly, factoryCreated, factoryProperties, id, scClassName

Constructor Summary

Constructors

Constructor and Description
Tour()
Tour(com.google.gwt.core.client.JavaScriptObject jsObj)

Method Summary

Modifier and Type	Method and Description
com.google.gwt.core.client.JavaScriptObject	create()
boolean	getAllowDropOnDescendants() Default value for TourStep.allowDropOnDescendants within this tour.
java.lang.Boolean	getAutoReset() Should tour be auto-reset once it finishes in any manner so it can restarted?
ProcessElement[]	getCancelSteps() The ProcessElements representing steps that should be performed if the user cancels the tour.
java.lang.String	getDropOutlineBorder() Set the CSS border of the outline for drop targets as a CSS string including border-width, border-style, and/or color (eg "1px dashed blue").
java.lang.String	getFirstStepActionButtonTitle() Default value of TourStep.actionButtonTitle for the first step in the tour.
java.lang.String	getFirstStepCancelButtonTitle() Default value of TourStep.cancelButtonTitle for the first step in the tour.
java.lang.String	getLastStepActionButtonTitle() Default value of TourStep.actionButtonTitle for the last step in the tour.
TourMode	getMode() The tour mode allows step configuration to be simplified by using the context to apply appropriate defaults.
NotifySettings	getNotifyMessageSettings() Defaults settings for notifyType message displayed by notifyValidationMessage.
java.lang.String	getNotifyType() Category of message to use in +{notifyValidationMessage,notifyValidationMessage} by default.
static Tour	getOrCreateRef(com.google.gwt.core.client.JavaScriptObject jsObj)
java.lang.String	getOutlineBorder() Set the CSS border of the outline of non-drop targets as a CSS string including border-width, border-style, and/or color (eg "1px dashed blue").
java.lang.Boolean	getShowInputValidationMessage() Should TourStep.inputValidationNotifyMessage be shown as detailed in TourInputValidationMode for the entire tour? Set to false to suppress reporting messages to the user.
java.lang.Boolean	getShowProgress() Should a progress bar be shown in each step to indicate progress through the tour?
java.lang.Boolean	getShowProgressPercent() Show progress percent next to progress bar when showProgress is enabled?
java.lang.String	getStepActionButtonTitle() Default value for TourStep.actionButtonTitle for steps other than the first and last ones.
java.lang.String	getStepCancelButtonTitle() Default value for TourStep.cancelButtonTitle for all steps where the cancel button is shown.
ProcessElement[]	getSteps() The ProcessElements representing steps in this tour.
static Tour	getTour(java.lang.String tourId) Get a Tour instance by it's ID.
Canvas	getWindowDefaults() Defaults for each TourStep.targetView autoChild in the tour.
static void	loadTour(java.lang.String tourId, ProcessCallback callback) Loads an XML tour definition stored in XML from the server.
void	notifyValidationMessage(java.lang.String message) Notify user of expected value entry validation message.
Tour	setAllowDropOnDescendants(boolean allowDropOnDescendants) Default value for TourStep.allowDropOnDescendants within this tour.
Tour	setAutoReset(java.lang.Boolean autoReset) Should tour be auto-reset once it finishes in any manner so it can restarted?
Tour	setCancelSteps(ProcessElement... cancelSteps) The ProcessElements representing steps that should be performed if the user cancels the tour.
Tour	setDropOutlineBorder(java.lang.String dropOutlineBorder) Set the CSS border of the outline for drop targets as a CSS string including border-width, border-style, and/or color (eg "1px dashed blue").
Tour	setFirstStepActionButtonTitle(java.lang.String firstStepActionButtonTitle) Default value of TourStep.actionButtonTitle for the first step in the tour.
Tour	setFirstStepCancelButtonTitle(java.lang.String firstStepCancelButtonTitle) Default value of TourStep.cancelButtonTitle for the first step in the tour.
Tour	setLastStepActionButtonTitle(java.lang.String lastStepActionButtonTitle) Default value of TourStep.actionButtonTitle for the last step in the tour.
Tour	setMode(TourMode mode) The tour mode allows step configuration to be simplified by using the context to apply appropriate defaults.
Tour	setNotifyMessageSettings(NotifySettings notifyMessageSettings) Defaults settings for notifyType message displayed by notifyValidationMessage.
Tour	setNotifyType(java.lang.String notifyType) Category of message to use in +{notifyValidationMessage,notifyValidationMessage} by default.
Tour	setOutlineBorder(java.lang.String outlineBorder) Set the CSS border of the outline of non-drop targets as a CSS string including border-width, border-style, and/or color (eg "1px dashed blue").
Tour	setShowInputValidationMessage(java.lang.Boolean showInputValidationMessage) Should TourStep.inputValidationNotifyMessage be shown as detailed in TourInputValidationMode for the entire tour? Set to false to suppress reporting messages to the user.
Tour	setShowProgress(java.lang.Boolean showProgress) Should a progress bar be shown in each step to indicate progress through the tour?
Tour	setShowProgressPercent(java.lang.Boolean showProgressPercent) Show progress percent next to progress bar when showProgress is enabled?
Tour	setStepActionButtonTitle(java.lang.String stepActionButtonTitle) Default value for TourStep.actionButtonTitle for steps other than the first and last ones.
Tour	setStepCancelButtonTitle(java.lang.String stepCancelButtonTitle) Default value for TourStep.cancelButtonTitle for all steps where the cancel button is shown.
Tour	setSteps(ProcessElement... steps) The ProcessElements representing steps in this tour.
Tour	setWindowDefaults(Canvas windowDefaults) Defaults for each TourStep.targetView autoChild in the tour.

Methods inherited from class com.smartgwt.client.util.workflow.Process

addFinishedHandler, addTraceElementHandler, getContainerId, getElement, getElements, getJsObj, getLastTaskOutput, getLastTaskOutput, getMockMode, getOrCreateJsObj, getProcess, getProcessElements, getRuleScope, getSequences, getStartElement, getState, getStateVariable, getTraceContext, getWizard, isCreated, loadProcess, onInit, passThruTaskOutput, reset, reset, setAttribute, setConfig, setContainerId, setElements, setJavaScriptObject, setMockMode, setNextElement, setNextElement, setRuleScope, setSequences, setStartElement, setStartElement, setState, setStateVariable, setTaskOutput, setTraceContext, setWizard, start

Methods inherited from class com.smartgwt.client.core.BaseClass

addDynamicProperty, addDynamicProperty, addDynamicProperty, addDynamicProperty, applyFactoryProperties, asSGWTComponent, clearDynamicProperty, createJsObj, destroy, doAddHandler, doInit, error, error, errorIfNotCreated, fireEvent, getAttribute, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsElement, getAttributeAsFloat, getAttributeAsInt, getAttributeAsJavaScriptObject, getAttributeAsMap, getAttributeAsString, getAttributeAsStringArray, getClassName, getConfig, getHandlerCount, getID, getRef, getScClassName, getTestInstance, hasAutoAssignedID, hasDynamicProperty, internalSetID, internalSetID, isConfigOnly, isFactoryCreated, onBind, registerID, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setConfigOnly, setFactoryCreated, setID, setProperty, setProperty, setProperty, setProperty, setScClassName

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.google.gwt.event.shared.HasHandlers

fireEvent

Constructor Detail

Tour

public Tour()

Tour

public Tour(com.google.gwt.core.client.JavaScriptObject jsObj)

Method Detail

getOrCreateRef

public static Tour getOrCreateRef(com.google.gwt.core.client.JavaScriptObject jsObj)

create

public com.google.gwt.core.client.JavaScriptObject create()

Overrides:

create in class Process

setAllowDropOnDescendants

public Tour setAllowDropOnDescendants(boolean allowDropOnDescendants)

Default value for TourStep.allowDropOnDescendants within this tour.

Parameters:

allowDropOnDescendants - New allowDropOnDescendants value. Default value is false

Returns:

Tour instance, for chaining setter calls

getAllowDropOnDescendants

public boolean getAllowDropOnDescendants()

Default value for TourStep.allowDropOnDescendants within this tour.

Returns:

Current allowDropOnDescendants value. Default value is false

setAutoReset

public Tour setAutoReset(java.lang.Boolean autoReset)
                  throws java.lang.IllegalStateException

Should tour be auto-reset once it finishes in any manner so it can restarted?

Parameters:

autoReset - New autoReset value. Default value is true

Returns:

Tour instance, for chaining setter calls

Throws:

java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

getAutoReset

public java.lang.Boolean getAutoReset()

Should tour be auto-reset once it finishes in any manner so it can restarted?

Returns:

Current autoReset value. Default value is true

setCancelSteps

public Tour setCancelSteps(ProcessElement... cancelSteps)
                    throws java.lang.IllegalStateException

The ProcessElements representing steps that should be performed if the user cancels the tour. These steps are typically TourSteps.

Alternately, or in addition to these cancelation steps, the finished method will be called once there are no more steps to process in the tour.

Parameters:

cancelSteps - New cancelSteps value. Default value is null

Returns:

Tour instance, for chaining setter calls

Throws:

java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

getCancelSteps

public ProcessElement[] getCancelSteps()

The ProcessElements representing steps that should be performed if the user cancels the tour. These steps are typically TourSteps.

Alternately, or in addition to these cancelation steps, the finished method will be called once there are no more steps to process in the tour.

Returns:

Current cancelSteps value. Default value is null

setDropOutlineBorder

public Tour setDropOutlineBorder(java.lang.String dropOutlineBorder)

Set the CSS border of the outline for drop targets as a CSS string including border-width, border-style, and/or color (eg "1px dashed blue"). See outlineBorder for properties applied to non-drop targets.

This property applies the same border to all four sides of the outlined component(s).

Parameters:

dropOutlineBorder - New dropOutlineBorder value. Default value is "1px solid #44ff44"

Returns:

Tour instance, for chaining setter calls

See Also:

setOutlineBorder(java.lang.String)

getDropOutlineBorder

public java.lang.String getDropOutlineBorder()

Set the CSS border of the outline for drop targets as a CSS string including border-width, border-style, and/or color (eg "1px dashed blue"). See outlineBorder for properties applied to non-drop targets.

This property applies the same border to all four sides of the outlined component(s).

Returns:

Current dropOutlineBorder value. Default value is "1px solid #44ff44"

See Also:

getOutlineBorder()

setFirstStepActionButtonTitle

public Tour setFirstStepActionButtonTitle(java.lang.String firstStepActionButtonTitle)
                                   throws java.lang.IllegalStateException

Default value of TourStep.actionButtonTitle for the first step in the tour.

Default titles for the middle and last steps are configured by stepActionButtonTitle and lastStepActionButtonTitle respectively.

Parameters:

firstStepActionButtonTitle - New firstStepActionButtonTitle value. Default value is "Let's go!"

Returns:

Tour instance, for chaining setter calls

Throws:

java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

getFirstStepActionButtonTitle

public java.lang.String getFirstStepActionButtonTitle()

Default value of TourStep.actionButtonTitle for the first step in the tour.

Default titles for the middle and last steps are configured by stepActionButtonTitle and lastStepActionButtonTitle respectively.

Returns:

Current firstStepActionButtonTitle value. Default value is "Let's go!"

setFirstStepCancelButtonTitle

public Tour setFirstStepCancelButtonTitle(java.lang.String firstStepCancelButtonTitle)
                                   throws java.lang.IllegalStateException

Default value of TourStep.cancelButtonTitle for the first step in the tour.

Default title for the middle steps is configured by stepCancelButtonTitle. No cancel button is shown for the last step.

Parameters:

firstStepCancelButtonTitle - New firstStepCancelButtonTitle value. Default value is "Skip this tour"

Returns:

Tour instance, for chaining setter calls

Throws:

java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

getFirstStepCancelButtonTitle

public java.lang.String getFirstStepCancelButtonTitle()

Default value of TourStep.cancelButtonTitle for the first step in the tour.

Default title for the middle steps is configured by stepCancelButtonTitle. No cancel button is shown for the last step.

Returns:

Current firstStepCancelButtonTitle value. Default value is "Skip this tour"

setLastStepActionButtonTitle

public Tour setLastStepActionButtonTitle(java.lang.String lastStepActionButtonTitle)
                                  throws java.lang.IllegalStateException

Default value of TourStep.actionButtonTitle for the last step in the tour.

Default titles for the first and middle steps are configured by firstStepActionButtonTitle and stepActionButtonTitle respectively.

Parameters:

lastStepActionButtonTitle - New lastStepActionButtonTitle value. Default value is "Done"

Returns:

Tour instance, for chaining setter calls

Throws:

java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

getLastStepActionButtonTitle

public java.lang.String getLastStepActionButtonTitle()

Default value of TourStep.actionButtonTitle for the last step in the tour.

Default titles for the first and middle steps are configured by firstStepActionButtonTitle and stepActionButtonTitle respectively.

Returns:

Current lastStepActionButtonTitle value. Default value is "Done"

setMode

public Tour setMode(TourMode mode)

The tour mode allows step configuration to be simplified by using the context to apply appropriate defaults.

Parameters:

mode - New mode value. Default value is "tour"

Returns:

Tour instance, for chaining setter calls

getMode

public TourMode getMode()

The tour mode allows step configuration to be simplified by using the context to apply appropriate defaults.

Returns:

Current mode value. Default value is "tour"

setNotifyMessageSettings

public Tour setNotifyMessageSettings(NotifySettings notifyMessageSettings)
                              throws java.lang.IllegalStateException

Defaults settings for notifyType message displayed by notifyValidationMessage.

Parameters:

notifyMessageSettings - New notifyMessageSettings value. Default value is null

Returns:

Tour instance, for chaining setter calls

Throws:

java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

getNotifyMessageSettings

public NotifySettings getNotifyMessageSettings()

Defaults settings for notifyType message displayed by notifyValidationMessage.

Returns:

Current notifyMessageSettings value. Default value is null

setNotifyType

public Tour setNotifyType(java.lang.String notifyType)
                   throws java.lang.IllegalStateException

Category of message to use in +{notifyValidationMessage,notifyValidationMessage} by default.

If this category has not been configured in Notify it will be automatically configured using +{notifyMessageSettings,notifyMessageSettings}.

Parameters:

notifyType - New notifyType value. Default value is "tourExpectedValue"

Returns:

Tour instance, for chaining setter calls

Throws:

java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

See Also:

NotifyType

getNotifyType

public java.lang.String getNotifyType()

Category of message to use in +{notifyValidationMessage,notifyValidationMessage} by default.

If this category has not been configured in Notify it will be automatically configured using +{notifyMessageSettings,notifyMessageSettings}.

Returns:

Current notifyType value. Default value is "tourExpectedValue"

See Also:

NotifyType

setOutlineBorder

public Tour setOutlineBorder(java.lang.String outlineBorder)

Set the CSS border of the outline of non-drop targets as a CSS string including border-width, border-style, and/or color (eg "1px dashed blue"). See dropOutlineBorder for properties applied to drop targets.

This property applies the same border to all four sides of the outlined component(s).

Parameters:

outlineBorder - New outlineBorder value. Default value is "1px solid red"

Returns:

Tour instance, for chaining setter calls

See Also:

setDropOutlineBorder(java.lang.String)

getOutlineBorder

public java.lang.String getOutlineBorder()

Set the CSS border of the outline of non-drop targets as a CSS string including border-width, border-style, and/or color (eg "1px dashed blue"). See dropOutlineBorder for properties applied to drop targets.

This property applies the same border to all four sides of the outlined component(s).

Returns:

Current outlineBorder value. Default value is "1px solid red"

See Also:

getDropOutlineBorder()

setShowInputValidationMessage

public Tour setShowInputValidationMessage(java.lang.Boolean showInputValidationMessage)
                                   throws java.lang.IllegalStateException

Should TourStep.inputValidationNotifyMessage be shown as detailed in TourInputValidationMode for the entire tour? Set to false to suppress reporting messages to the user. notifyValidationMessage will not be called.

This setting can be overridden for individual tourSteps.

Parameters:

showInputValidationMessage - New showInputValidationMessage value. Default value is null

Returns:

Tour instance, for chaining setter calls

Throws:

java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

getShowInputValidationMessage

public java.lang.Boolean getShowInputValidationMessage()

Should TourStep.inputValidationNotifyMessage be shown as detailed in TourInputValidationMode for the entire tour? Set to false to suppress reporting messages to the user. notifyValidationMessage will not be called.

This setting can be overridden for individual tourSteps.

Returns:

Current showInputValidationMessage value. Default value is null

setShowProgress

public Tour setShowProgress(java.lang.Boolean showProgress)
                     throws java.lang.IllegalStateException

Should a progress bar be shown in each step to indicate progress through the tour?

Parameters:

showProgress - New showProgress value. Default value is null

Returns:

Tour instance, for chaining setter calls

Throws:

java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

getShowProgress

public java.lang.Boolean getShowProgress()

Should a progress bar be shown in each step to indicate progress through the tour?

Returns:

Current showProgress value. Default value is null

setShowProgressPercent

public Tour setShowProgressPercent(java.lang.Boolean showProgressPercent)
                            throws java.lang.IllegalStateException

Show progress percent next to progress bar when showProgress is enabled?

Parameters:

showProgressPercent - New showProgressPercent value. Default value is null

Returns:

Tour instance, for chaining setter calls

Throws:

java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

getShowProgressPercent

public java.lang.Boolean getShowProgressPercent()

Show progress percent next to progress bar when showProgress is enabled?

Returns:

Current showProgressPercent value. Default value is null

setStepActionButtonTitle

public Tour setStepActionButtonTitle(java.lang.String stepActionButtonTitle)
                              throws java.lang.IllegalStateException

Default value for TourStep.actionButtonTitle for steps other than the first and last ones.

Default titles for the first and last steps are configured by firstStepActionButtonTitle and lastStepActionButtonTitle respectively.

Parameters:

stepActionButtonTitle - New stepActionButtonTitle value. Default value is "Next"

Returns:

Tour instance, for chaining setter calls

Throws:

java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

See Also:

setStepCancelButtonTitle(java.lang.String)

getStepActionButtonTitle

public java.lang.String getStepActionButtonTitle()

Default value for TourStep.actionButtonTitle for steps other than the first and last ones.

Default titles for the first and last steps are configured by firstStepActionButtonTitle and lastStepActionButtonTitle respectively.

Returns:

Current stepActionButtonTitle value. Default value is "Next"

See Also:

getStepCancelButtonTitle()

setStepCancelButtonTitle

public Tour setStepCancelButtonTitle(java.lang.String stepCancelButtonTitle)
                              throws java.lang.IllegalStateException

Default value for TourStep.cancelButtonTitle for all steps where the cancel button is shown.

Default title for the first step is configured by firstStepCancelButtonTitle.

Parameters:

stepCancelButtonTitle - New stepCancelButtonTitle value. Default value is "Skip this tour"

Returns:

Tour instance, for chaining setter calls

Throws:

java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

See Also:

setStepActionButtonTitle(java.lang.String)

getStepCancelButtonTitle

public java.lang.String getStepCancelButtonTitle()

Default value for TourStep.cancelButtonTitle for all steps where the cancel button is shown.

Default title for the first step is configured by firstStepCancelButtonTitle.

Returns:

Current stepCancelButtonTitle value. Default value is "Skip this tour"

See Also:

getStepActionButtonTitle()

setSteps

public Tour setSteps(ProcessElement... steps)
              throws java.lang.IllegalStateException

The ProcessElements representing steps in this tour. These steps are typically TourSteps.

Parameters:

steps - New steps value. Default value is null

Returns:

Tour instance, for chaining setter calls

Throws:

java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

getSteps

public ProcessElement[] getSteps()

The ProcessElements representing steps in this tour. These steps are typically TourSteps.

Returns:

Current steps value. Default value is null

setWindowDefaults

public Tour setWindowDefaults(Canvas windowDefaults)
                       throws java.lang.IllegalStateException

Defaults for each TourStep.targetView autoChild in the tour. These defaults are applied before TourStep.windowDefaults if any.

Parameters:

windowDefaults - New windowDefaults value. Default value is {...}

Returns:

Tour instance, for chaining setter calls

Throws:

java.lang.IllegalStateException - this property cannot be changed after the underlying component has been created

See Also:

SGWTProperties

getWindowDefaults

public Canvas getWindowDefaults()

Defaults for each TourStep.targetView autoChild in the tour. These defaults are applied before TourStep.windowDefaults if any.

Returns:

Current windowDefaults value. Default value is {...}

notifyValidationMessage

public void notifyValidationMessage(java.lang.String message)

Notify user of expected value entry validation message. Default implementation uses the Notify system to show the message in it's default position. See notifyType for notification configuration details.

Parameters:

message - message provided by TourStep.inputValidationNotifyMessage

getTour

public static Tour getTour(java.lang.String tourId)

Get a Tour instance by it's ID.

Parameters:

tourId - tour ID to retrieve. See Identifier

Returns:

the tour, or null if not defined

See Also:

Identifier

loadTour

public static void loadTour(java.lang.String tourId,
                            ProcessCallback callback)

Loads an XML tour definition stored in XML from the server.

Tour files are stored as .proc.xml files in Component XML format, in the directory indicated by the project.processes setting in server.properties (webroot/processes by default). To load a tour saved in a file tourId.proc.xml, pass just tourId to this method.

Parameters:

tourId - tour ID or IDs to load. See Identifier

callback - called when the tour is loaded with argument "process", the first tour. Other tours can be looked up via getTour().