Constructing Tour Guides for LAE Nodes
Date of Last Save: Friday, December 06, 2013
Constructing Tour Guides for LAE Nodes
Contents
Glossary ...................................................................................................................................................... 4
Introduction ................................................................................................................................................ 5
Background ............................................................................................................................................. 5
Aim.......................................................................................................................................................... 5
Scope ...................................................................................................................................................... 5
Intended Audience .................................................................................................................................. 6
Additional Resources .............................................................................................................................. 6
Setting up a Tour......................................................................................................................................... 7
Where to Enter the Tour Guide Details ................................................................................................... 7
Tour Script Syntax ................................................................................................................................... 7
Stage Name ......................................................................................................................................... 8
Display Condition ................................................................................................................................ 8
Active Parameters ............................................................................................................................... 8
Text ..................................................................................................................................................... 8
ParamText ........................................................................................................................................... 9
Next .................................................................................................................................................... 9
Tour Inheritance ..................................................................................................................................... 9
Replace Inherited Tour...................................................................................................................... 10
Insert Before Inherited Stages .......................................................................................................... 10
Insert After Inherited Stages ............................................................................................................. 10
Examples ................................................................................................................................................... 11
Example 1.
Simple Tour ................................................................................................................... 11
Example 2.
Simple Tour Using Parameter Text ................................................................................ 12
Example 3.
Tour with "Hidden Stages" ............................................................................................ 13
Example 4.
Tour with "Hidden Parameters" with corresponding "ParamText" ............................... 13
Example 5.
DisplayCondition for Context Specific Information ....................................................... 14
Example 6.
Dynamic Tour Stages Using "DisplayCondition" ............................................................ 17
Error Handling ........................................................................................................................................... 20
Syntax Errors ......................................................................................................................................... 20
Loops in Tour Script .............................................................................................................................. 20
Example 1: Invalid Tour Stage - References Self................................................................................ 20
Date of Last Save: Friday, December 06, 2013
2
Constructing Tour Guides for LAE Nodes
Example 2: Invalid Tour Stage – Indirect Loop .................................................................................. 20
Referencing non-existent elements ...................................................................................................... 21
Reference non-existent stages .......................................................................................................... 21
Referencing non-existent parameters .............................................................................................. 23
Referencing non-active parameters .................................................................................................. 23
Stage Name Conflicts ............................................................................................................................ 23
Example 1: Simple Stage Name Conflict ............................................................................................ 23
Example 2: Inherited Stage Name Conflict ........................................................................................ 23
Appendix A.
Advanced: Evaluation and Navigation of a Tour Guide ..................................................... 25
Navigating the Tour .............................................................................................................................. 25
Split Tour Stages ............................................................................................................................... 26
Evaluated Tour Plan .......................................................................................................................... 29
Tour Stage States .............................................................................................................................. 30
Tour Guide Modes ............................................................................................................................ 30
Parameter Navigation Mode ............................................................................................................. 31
Implicit Display Condition ................................................................................................................. 32
Parameter Display Order vs. Parameter Navigation Order ............................................................... 35
Keyboard Navigation ......................................................................................................................... 35
Hop-on-hop-off ................................................................................................................................. 35
Date of Last Save: Friday, December 06, 2013
3
Glossary
Term
Tour
Guided Tour
Tour Script
Stage
Tour Planner
Tourist
Visible Parameter
Selected
Parameters
Non-Selected
Parameters
Active Parameters
Active Stage
Description
The way that BRE guides the user through the configuration of parameters and
presents the user with information about how to set the parameters.
See tour
Minimalist scripting “language” used to “plan” a tour.
A tour comprises multiple “stages” (could also be called “steps” if you were that
way inclined). Each step within a tour is referred to in this document as a “stage”
Person that writes the tour script to configure, or “plan” a tour.
Person using the node editor and being guided through a tour.
A parameter is said to be “visible” if it is possible to see the parameter in the node
editor for the current node. If the node is not on the currently selected tab, the
user will not be able to see it however from the point of view of the node, it is still
a “visible parameter”.
When a tour guide is underway, parameters that are defined to be active for the
current tour stage, which are visible on the node and not a "label" or "fieldhelper"
type parameter are “selected” parameters. These parameters will display
“normally”, with a slightly bold border. Note that parameters which are not visible
for licensing reasons are also not considered "selected" parameters.
When a tour guide is underway, parameters that are not defined to be active on
the current tour stage are “non-selected” parameters. These parameters will
display greyed out
Parameters can be defined as “active” for a given stage. This is defined within the
tour script. Active, visible parameters for the current tour stage are “selected”.
The current stage in the tour.
Date of Last Save: Friday, December 06, 2013
Constructing Tour Guides for LAE Nodes
Introduction
Background
As of LAE 5.0, "guided tour" functionality has been added. This allows for someone developing a node to
also construct a "tour" that will guide the user through the configuration of the node's parameters. The
BRE help documents the general usage of these tours. This document is focused at a more advanced
user who wants to construct such tours such that people using the nodes that they have created will be
able to easily understand the node's purpose and correctly set the parameters on the node. This
document describes the mechanism and syntax for constructing a tour and how this will be presented to
a user (or "tourist") of the node and the tour guide.
Aim
The aim of the “guided tour” is to focus the users‘ attention on the parameters that they are likely to be
interested in and provide the user with some information about how they need to configure the node.
This “guided tour” can be configured on a node by node basis, such that the tour can be optimized
depending on the node being used. The tour is dynamic in nature, such that the stages of the tour which
are presented to the user and the order in which they are presented are based on the parameters that
the user has set, the values which the user has provided for parameters and the visibility of the
parameters.
For example, consider an acquisition node, where the user has the option of specifying that the data
comes from a file, or comes from numerous files specified in a “filename” field in an input pin. It makes
no sense to guide the user through any parameters which are designed to handle multiple files if the
user has provided a single filename – it may even make sense to never have such input-based
parameters in the tour if a node can optionally take an input, but there is no input provided to the node.
Scope
The tour is only applied to a single node. When the user opens the node editor, they may be led through
a tour of the node. This is not a general wizard used to construct graphs from a template, and is not
used to configure multiple nodes.
If multiple nodes are to be configured, these all need to be placed within a composite node. The
composite node would then need to expose the parameters of interest from the various contained
nodes, and a tour would need to be designed on the composite itself which can then be used to set the
parameters which would then be populated on the composite, and inherited via composition by the
contained nodes.
Date of Last Save: Friday, December 06, 2013
5
Constructing Tour Guides for LAE Nodes
Intended Audience
Since some understanding of LAE inheritance, composition, validators, Boolean expressions and some
simple scripting are required, it is assumed that someone constructing a tour will be an advanced LAE
user.
Additional Resources
There is an example graph provided “TourGuideExamples.brg” which is referenced frequently within this
document. The “TourGuideExamples” graph can be found in the Lavastorm BRAIN\Examples
subdirectory, under the path indicated in the table below:
Operating System
Windows 7 / Vista
Windows 7 / Vista
Windows XP
Windows XP
Install Type
All Users
Single User
All Users
Single User
Location
C:\Users\Public\Documents\
C:\Users\<userName>\Documents\
C:\Documents and Settings\<userName>\My Documents\
C:\Documents and Settings\All Users\ Documents\
It is best to type these links directly into your Windows Explorer address bar as in some circumstances
(e.g. Windows 7) navigating to these via clicking on the directories will not work. The directories that
show up within Windows Explorer simply link to the locations above. If you cannot remember the exact
username, then navigate to the folder containing the <username> directory, and obtain the username
from there.
Note also that that these locations depend on that particular setup of your Windows environment. If the
Examples cannot be found in these locations, then the Example directory can be found in the same
location as the Template directory which is installed with BRE.
Provided that you have not modified the default Template directory specified in BRE, and then the
location of the Template directory is specified in Tools->Preferences->Template Directory
within BRE.
For example if the Template directory is specified as:
C:\Users\Public\Documents\Lavastorm BRAIN\Template
Date of Last Save: Friday, December 06, 2013
6
Constructing Tour Guides for LAE Nodes
Then the example directory will lie under the same “Lavastorm BRAIN” folder, and be located at:
C:\Users\Public\Documents\Lavastorm BRAIN\Example
Setting up a Tour
Where to Enter the Tour Guide Details
In order to construct a tour you first need to open the node editor of the node for which you want to
construct a guided tour. Then, on the “Documentation” tab in the node editor, you can enter the tour
plan in the “Tour Script” field.
The tour script has the format defined in the following section, and has inheritance options which are
described in the Tour Inheritance section.
Tour Script Syntax
The tour script has its own format and syntax. Any line which contains only whitespace, or where the
first non-whitespace character is the pound, or hash character (‘#’), are treated as comments and are
ignored when parsing the tour script. The keywords within a tour script are case sensitive.
Other than that distinction, the following format must be followed:
Tour Script ::=
Stage+
Stage ::=
StageStartTag
DisplayCondition? |
ActiveParameter+ |
Text+ |
ParamText* |
NextStage?
StageEndTag
StageStartTag ::=
stage:stageName
StageEndTag ::=
end:stageName
DisplayCondition ::=
displayCondition:BooleanExpr
ActiveParameter ::=
active:ParameterName
Text ::=
text:free form text
Date of Last Save: Friday, December 06, 2013
7
Constructing Tour Guides for LAE Nodes
ParamText ::=
paramText:ParameterName:free form text
NextStage ::=
next::nextStageName
The BooleanExpr follows the same rules as when entering an expression in the “Other” section of a
LAE Boolean parameter within the node editor.
The stageName in the StageStartTag and StageEndTag must be the same.
The nextStageName must match a stage that is defined in the tour.
The purpose of these elements is outlined in the following subsections.
Stage Name
This is simply the name of the stage, which can be referenced by other stage’s NextStage element in
the tour script. Stage names cannot contain the colon (‘:’) character or newline characters and must not
be blank. Any leading and trailing whitespace in the stage name is ignored. Stage names must be unique
in a tour script. When tour scripts are inherited and augmented (see Tour Inheritance) the stage name
must be unique across the entire script including the inherited stages.
Display Condition
The DisplayCondition element is an optional part of a tour stage which provides explicit
instructions as to whether or not the stage will be displayed (normally dependent on whether another
parameter is set or another parameter’s value). The stage will only be displayed when the display
condition evaluates to true.
This is the explicit display condition of the stage. There are also implicit display conditions which depend
on the mode of tour in use. These implicit display conditions are discussed in the section “Implicit
Display Condition”.
Active Parameters
For each tour stage there are a set of active parameters defined. When a tour guide is underway, for the
current stage, the visible, active, non-label, non-fieldhelper type parameters (or “selected parameters”)
are the parameters which the user is able to populate. These parameters must be specified in the
ActiveParameter element of the tour script defined above.
The parameter name cannot contain a colon (':') character. If the parameter name contains a ":" this
must be escaped using the "\" character.
Text
The Text element of a stage in the tour script specifies the text that is to be displayed to the user
during that tour stage. This normally will be to prompt them to enter the selected parameters and
provide them with some extra information about how to set the parameters. The free form text must be
on a single line. For multiple lines of text, multiple Text elements must be used.
Date of Last Save: Friday, December 06, 2013
8
Constructing Tour Guides for LAE Nodes
ParamText
The ParamText element of a stage defines the text that is to be displayed to the user during that tour
stage for the specified parameter. The parameter specified must be defined as an active parameter for
the tour stage. If the parameter is not visible, then the parameter text will not be displayed in the tour
guide.
The parameter name cannot contain a colon (':') character. If the parameter name contains a ":" this
must be escaped using the "\" character.
Next1
The Next element of the tour stage identifies the stage that is to be evaluated when the user clicks the
“Next” button. If there is no Next element defined on a stage, then the stage to be evaluated when the
user clicks on the “Next” button is the stage within the tour script that is defined immediately after the
current stage. If there is no stage defined after the current stage, and there is no Next element
defined, then the current stage is the last stage.
Note that “evaluated” does not necessarily mean “displayed”. The implicit and explicit display conditions
are evaluated when evaluating a stage to determine whether or not the stage should be displayed. If the
stage being evaluated is not to be displayed, then the same logic is applied on that stage to determine
the next stage to evaluate, until a stage can be displayed or there are no more stages to evaluate.
For example, if stage A, specified a next stage of B and stage B specifies a next stage of C, but stage B’s
display condition evaluates to false, , then clicking “Next” from stage A would result in stage C being
displayed to the user.
If any stage “S” does not have a Next element defined, then an implicit next condition is used, which
states that the stage defined immediately after “S” in the tour script is to follow from stage “S”.
If there are no subsequent stages in the tour script, and the stage does not have a Next element
specified, then this stage is the last stage in the tour.
Tour Inheritance
When a node inherits from another node, it by default also inherits the tour. Within the node editor, on
the documentation tab, there are options to change the way that the tour inheritance is handled. As
with various other inheritance related UI elements (such as the Inherited Parameter Group Overrides
tab within “Declare Parameters”, and the “Inherit API Documentation” checkbox in the Documentation
tab) the option of choosing the inheritance mode is always shown and enabled. If you choose to inherit
tour stages, and the node does not inherit from any other node, then obviously, no stages are inherited.
This tab is displayed below, and the options are outlined in the following sub-sections:
1
Note that the next syntax has two colons, rather than one, which isn’t the case in all other elements (excluding
paramText). Nothing is allowed to be entered between the first and second colon.
Date of Last Save: Friday, December 06, 2013
9
Constructing Tour Guides for LAE Nodes
Replace Inherited Tour
Anything typed into the “Tour Script” will be used as the node’s tour. No tour information is inherited
from the parent node. If this option is selected, and nothing is entered in the Tour Script, then the node
will not have a tour guide defined.
Insert Before Inherited Stages
This is the default option.
When this option is selected, whatever is inserted in the “Tour Script” will be placed prior to the
inherited script. The complete tour script is then composed of the text within the Tour Script on the
current node, followed by the evaluated parent’s tour script. This means that the first stage entered in
the “Tour Script” will be evaluated first in the tour. If this option is selected and nothing is entered in the
Tour Script, then the node will effectively have the same tour guide as defined on the parent node.
Insert After Inherited Stages
When this option is selected, whatever is inserted in the “Tour Script” will be placed after the inherited
script. The complete tour script is then composed of the evaluated parent’s tour script, followed by the
text within the Tour Script on the current node. This means that the tour guide for the parent node will
execute first. Then, when that tour guide has no more stages, the first stage entered in the “Tour Script”
of the child node will be evaluated in the tour. If this option is selected and nothing is entered in the
Tour Script, then the node will effectively have the same tour guide as defined on the parent node.
Date of Last Save: Friday, December 06, 2013
10
Examples
The following examples walk through some of the nodes and tour guides in the
"TourGuideExamples.brg" file.
Example 1. Simple Tour
Example Nodes Used:
 Library:
o Simple Tour – Perform Simple Operation
 Graph:
o Simple Tour – Example 1
Consider the library node "Simple Tour – Perform Simple Operation" in TourGuideExamples.brg and the
graph node "Simple Tour – Example 1" that inherits from this. This node which takes one input, and
computes an arithmetic operation on two fields from the input (one of addition, subtraction,
multiplication or division). The node takes three parameters:



"Field1" –A string parameter with a "Not Blank" validator, containing the name of the first field
"Operation" –A choice parameter specifying either +, -, * or /
"Field2" – A string parameter with a "Not Blank" validator, containing the name of the second
field in the operation.
A simple tour has been constructed for the node with one stage for each parameter, describing each of
the parameters using the following Tour Script:
#The stage to enter the first field
stage:firstField
#Specifies that "Field1" is active for this stage
active:Field1
#Then the text to display for the stage
text:The name of the first field in the input over which the operation
text:is to be performed
#Make sure we end the stage
end:firstField
#Now for the second stage – the operation to perform
stage:operation
active:Operation
text:The arithmetic operation to perform on the two fields
end:operation
Date of Last Save: Friday, December 06, 2013
Constructing Tour Guides for LAE Nodes
#And the final stage
stage:secondField
active:Field2
text:The name of the second field in the input over which the operation
text:is to be performed
end:secondField
Example 2. Simple Tour Using Parameter Text
Example Nodes Used:
 Library:
o Simple Tour Using Parameter Text - Perform Simple Operation
 Graph:
o Simple Tour – Example 2
Using a node with the same fields and operation in the previous example, if you wanted to have only
one tour stage, and have all of the parameters active for that stage, with information specific for each
parameter you could do this using the following tour script:
#Just one stage this time
stage:MyStage
#Specifies that "Field1", "operation" and "Field2" are active for this
#stage
active:Field1
active:Operation
active:Field2
#Then the text to display for the stage
text:Perform the specified arithmetic operation using the specified
text:fields
#Now, the specific text for each parameter
paramText:Field1:The name of the first field in the input over which
paramText:Field1:the operation is to be performed
paramText:Operation:The arithmetic operation to perform on the two
paramText:Operation:fields
paramText:Field2:The name of the second field in the input over which
paramText:Field2:the operation is to be performed
end:MyStage
This is demonstrated in the referenced nodes in the example graph.
Date of Last Save: Friday, December 06, 2013
12
Constructing Tour Guides for LAE Nodes
Example 3. Tour with "Hidden Stages"
Example Nodes Used:
 Library:
o Remove Records
o Remove NULLs
 Graph:
o Remove Records
o Remove NULLs
Consider first the library node "Remove Records". This node is designed to remove all records where a
specified field matches a certain criteria. The node has two parameters, the "Field" and the
"RemovalCondition". A tour script has been constructed as shown below to walk the user through the
setting of these parameters:
stage:RemoveField
active:Field
text:Enter the field to check to determine whether or not a record
should be removed from the output
end:RemoveField
stage:Condition
active:RemovalCondition
text:Select the condition which is used to determine if the specified
field should be removed
end:Condition
In the graph, you can see how this operates in the "Remove Records" example node.
A customization of this node is also in the library, called "Remove NULLs". This node has been
preconfigured to select "Null" as the "RemovalCondition". The "RemovalCondition" parameter is then
hidden. If you look at the "Remove NULLs" node in the graph, you will see that the second stage of the
tour does not display as the only active parameter for that tour – "RemovalCondition" is not visible in
the node.
Example 4. Tour with "Hidden Parameters" with corresponding "ParamText"
Example Nodes Used:
 Library:
o Remove Records2
o Remove NULLs2
 Graph:
o Remove Records2
Date of Last Save: Friday, December 06, 2013
13
Constructing Tour Guides for LAE Nodes
o
Remove NULLs2
In this case, a node with the same purpose as that in the previous example has been used. However
here, rather than having a separate stage per parameter, both parameters have been placed in the same
stage of the tour. The tour script is shown below.
stage:RemoveField
active:Field
active:RemovalCondition
text:Select how to determine whether a record should be removed from
the output
paramText:Field:The field to check to determine if the record should be
output
paramText:RemovalCondition:Select the condition which is used to
determine if the specified field should be removed
end:RemoveField
Again, this node is inherited by a node Remove NULLs2 that is configured to remove records containing
a NULL in the specified field. Therefore the "RemovalCondition" parameter is set to "Null" and hidden. If
you open the node editor in the graph for the "Remove NULLs2" node and start the tour guide, you will
notice that the stage described above will display correctly. However, the parameter text for the
"RemovalCondition" parameter is not displayed as this parameter has been hidden.
Example 5. DisplayCondition for Context Specific Information
Example Nodes Used:
 Library:
o Aggregate Data
 Graph:
o Aggregate Data
In this example, the "Aggregate Data" node is used. This node is used to perform either date-based (date,
time, datetime) or numeric (integer, long, double) aggregation over a specified field, using a specified
operator. The operations that can be performed are limited by the data type being used. The user first
has to enter the type of data over which the operation is to be performed. Then, depending on the
operation type being used, different text will be displayed for the stages used to specify the input field
and the operation.
The tour script used in the example is shown below:
stage:OperationType
active:OperationType
Date of Last Save: Friday, December 06, 2013
14
Constructing Tour Guides for LAE Nodes
text:Select the type of the field to be used in the operation
text:Allowable options are numeric and date
text:
text:The type of field used restricts the operations that can be
performed
text:
text:This node can only aggregate on numeric or date based data
end:OperationType
stage:NumericField
active:Field
displayCondition:"{{^OperationType^}}"=="numeric"
text:Enter the numeric field which is to be aggregated
text:
paramText:Field:An integer, long or double field in the input data
end:NumericField
stage:DateField
active:Field
displayCondition:"{{^OperationType^}}" == "date"
text:Enter the date-based field which is to be aggregated
text:
paramText:Field:A date, datetime, or time field in the input data
end:DateField
stage:NumericOperator
active:Operator
displayCondition:"{{^OperationType^}}"=="numeric"
text:Enter the Operator which is to be applied to the selected field
text:
paramText:Operator:min - The minimum value for the specified numeric
field within the specified grouping
paramText:Operator:max - The maximum value for the specified numeric
field within the specified grouping
paramText:Operator:average - The average value for the specified
numeric field within the specified grouping
Date of Last Save: Friday, December 06, 2013
15
Constructing Tour Guides for LAE Nodes
paramText:Operator:count - The number of non-null occurrences of the
specified numeric field within the specified grouping
paramText:Operator:sum - The sum of all values of the specified numeric
field within the specified grouping
end:NumericOperator
stage:DateOperator
active:Operator
displayCondition:"{{^OperationType^}}"=="date"
text:Enter the Operator which is to be applied to the selected field
text:
paramText:Operator:earliest - The earliest value for the specified date
based field within the specified grouping
paramText:Operator:latest - The latest value for the specified date
based field within the specified grouping
paramText:Operator:count - The number of non-null occurrences of the
specified date based field within the specified grouping
end:DateOperator
stage:GroupBy
active:GroupByFields
text:The field or list of fields which are used to group the data for
the aggregate
end:GroupBy
When using the node in the graph, note that if you select "date" as the operation type, the tour guide
will tell you to select a field of type date, time or datetime. Similarly, it will tell you which operations you
can select from the drop down for the Operation parameter (earliest, latest, count).
If you select "numeric", the tour guide will tell you to select a field of type integer, long or double.
Similarly, it will tell you which operations you can select from the drop down for the Operation
parameter (min, max, average, count, sum).
This text is displayed differently because of the displayCondition parameter used in the various stages. If
you select an OperationType "date", then the stage "NumericField" and "NumericOperator" will be
skipped because their displayCondition specifies:
displayCondition:"{{^OperationType^}}"=="numeric"
Date of Last Save: Friday, December 06, 2013
16
Constructing Tour Guides for LAE Nodes
Since the "OperationType" parameter is not set to numeric, the displayCondition evaluates to false, and
the stages are not displayed. Rather, the stages are displayed ("DateField" and "DateOperator") for
which the displayCondition is set to:
displayCondition:"{{^OperationType^}}"=="date"
While this is fine, we will show in the next example how this can be refined somewhat by having a
different parameter for dates and numeric operators.
Example 6. Dynamic Tour Stages Using "DisplayCondition"
Example Nodes Used:
 Library:
o Aggregate Data2
 Graph:
o Aggregate Data2
This example is very similar to the previous example in the function that the node performs. In this case,
however, there is a separate parameter for NumericOperators, and DateOperators. Based on the input
value for OperationType, the tour guide determines which stage to execute, and the stage then has
either the NumericOperator or DateOperator parameter active. The benefit of this approach is that the
dropdown choice parameter will only be populated with the values that are applicable for the type of
operation that is performed.
Similar to the previous example, the mechanism used to choose the stages to display is based on the
displayCondition. The difference here is that the active parameters within the DateOperator and
NumericOperator stages are different.
The tour script for this example is shown below.
stage:OperationType
active:OperationType
text:Select the type of the field to be used in the operation
text:Allowable options are numeric and date
text:
text:The type of field used restricts the operations that can be
performed
text:
text:This node can only aggregate on numeric or date based data
end:OperationType
Date of Last Save: Friday, December 06, 2013
17
Constructing Tour Guides for LAE Nodes
stage:NumericField
active:Field
displayCondition:"{{^OperationType^}}"=="numeric"
text:Enter the numeric field which is to be aggregated
text:
paramText:Field:An integer, long or double field in the input data
end:NumericField
stage:DateField
active:Field
displayCondition:"{{^OperationType^}}" == "date"
text:Enter the date-based field which is to be aggregated
text:
paramText:Field:A date, datetime, or time field in the input data
end:DateField
stage:NumericOperator
active:NumericOperator
displayCondition:"{{^OperationType^}}"=="numeric"
text:Enter the numeric Operator which is to be applied to the selected
field
text:
paramText:NumericOperator:min - The minimum value for the specified
numeric field within the specified grouping
paramText:NumericOperator:max - The maximum value for the specified
numeric field within the specified grouping
paramText:NumericOperator:average - The average value for the specified
numeric field within the specified grouping
paramText:NumericOperator:count - The number of non-null occurrences of
the specified numeric field within the specified grouping
paramText:NumericOperator:sum - The sum of all values of the specified
numeric field within the specified grouping
end:NumericOperator
stage:DateOperator
active:DateOperator
displayCondition:"{{^OperationType^}}"=="date"
Date of Last Save: Friday, December 06, 2013
18
Constructing Tour Guides for LAE Nodes
text:Enter the date-based Operator which is to be applied to the
selected field
text:
paramText:DateOperator:earliest - The earliest value for the specified
date based field within the specified grouping
paramText:DateOperator:latest - The latest value for the specified date
based field within the specified grouping
paramText:DateOperator:count - The number of non-null occurrences of
the specified date based field within the specified grouping
end:DateOperator
stage:GroupBy
active:GroupByFields
text:The field or list of fields which are used to group the data for
the aggregate
end:GroupBy
Date of Last Save: Friday, December 06, 2013
19
Error Handling
Any errors for Tour Scripts which are not defined on the current node, but defined on a parent of the
current node are silently ignored. If the tour script contains any such error, the tour will simply not be
displayed, and there will be no “Guided Tour” checkbox.
It is the responsibility of the tour planner to plan their tours correctly, and the tourist is never informed
of problems with the tour plan.
When editing the node where a tour is defined, however, errors are displayed on clicking “OK” to exit
the node editor if there are any problems with the tour defined on that node. These errors need to be
sufficiently detailed for the tour planner to be able to identify the problem and fix it. Since the tour
planner is assumed to be an advanced user, and is implementing a script using a custom syntax, these
errors can be of the variety you would expect as a programmer, rather than as a standard UI user.
The errors which are caught and reported are outlined below:
Syntax Errors
Syntax errors are any case where the tour script does not conform to the tour script syntax defined in
the section “Tour Script Syntax”
Loops in Tour Script
The tour guide cannot contain loops. This means that in the evaluated tour chain, there must be a single
path, with no references to previous stages in the chain. For instance, both of the following scripts
would be invalid:
Example 1: Invalid Tour Stage - References Self
stage:A
active:AParam
text:Fill in AParam
#invalid, contains reference to itself therefore loop
next:A
end:A
Example 2: Invalid Tour Stage – Indirect Loop
stage:A
active:AParam
text:Fill in AParam
next:B
end:A
stage:B
Date of Last Save: Friday, December 06, 2013
Constructing Tour Guides for LAE Nodes
active:AParam
text:Fill in AParam
next:C
end:B
stage:C
active:AParam
text:Fill in AParam
#invalid – A->B->C->A, means that there is a loop
next:A
end:C
Referencing non-existent elements
There are numerous cases whereby a tour stage may be invalid due to referencing an element which is
not defined or does not exist for a given tour stage or node. These are outlined below
Reference non-existent stages
Any next element within a tour stage must reference a tour stage that is defined within the tour. Note
that the stage does not need to exist in the script that is written specifically for this node. However, the
stage must exist within the composed script for the node. The two examples show both an invalid and a
valid tour script with regards to this error condition.
Example 1: Invalid Tour Stage – Stage referenced does not exist
stage:A
active:AParam
text:Fill in AParam
#invalid, the stage "NonExistent" is not defined for this script
next:NonExistent
end:A
Example 2: Valid Tour Stage – Stage referenced exists on parent
If a node A defines a tour script as follows:
stage:First
active:AParam1
text:Fill in AParam1 to make you happy
next:Second
end:First
Date of Last Save: Friday, December 06, 2013
21
Constructing Tour Guides for LAE Nodes
stage:Second
active:AParam2
text:Fill in AParam2 to make you money
end:Second
Then node B can inherit from node A, and set it’s tour guide inheritance mode to “Insert Before
Inherited Stages” – in which case, the following is valid:
stage:NewFirst
active:BParam1
text:Fill in BParam1 to make you angry
next:Second
end:NewFirst
Note that in this case, the stage “Second” is not defined on node B’s tour script. However, since it
inherits the script from its parent, where the stage “Second” is defined, then this is not an error.
If the inheritance mode was set to “Replace Inherited Tour” in this example, then this would be an error
condition due to the referenced stage not existing, as the stage “Second” would not be defined on node
B’s tour script, and there are no inherited stages.
Similarly, if the inheritance mode was set to “Insert After Inherited Stages”, this would end up being
invalid due to the looping error condition. This is because the composed tour script would then be:
stage:First
active:AParam1
text:Fill in AParam1 to make you happy
next:Second
end:First
stage:Second
active:AParam2
text:Fill in AParam2 to make you money
end:Second
stage:NewFirst
active:BParam1
text:Fill in BParam1 to make you angry
next:Second
end:NewFirst
This would result in the invalid evaluated tour chain First->Second->NewFirst->Second.
Date of Last Save: Friday, December 06, 2013
22
Constructing Tour Guides for LAE Nodes
Referencing non-existent parameters
All parameters referenced within the ActiveParameter element of a tour stage must be defined on
the node or somewhere in the node’s inheritance hierarchy. If any of the ActiveParameter
elements within a tour stage references a parameter that is not defined on the node – or in the node’s
inheritance hierarchy – this is an error.
Referencing non-active parameters
All parameters referenced within the ParamText element of a tour stage must be defined within a
corresponding ActiveParameter element on the same stage.
Stage Name Conflicts
All stage names must be unique across a tour guide. This includes the names of inherited stages. When
there are duplicate stage names, this is an error condition. The following two examples show cases
where this error condition is present:
Example 1: Simple Stage Name Conflict
stage:A
active:AParam
text:Fill in AParam
end:A
#invalid: Duplicate stage name “A”
stage:A
active:AParam2
text:Fill in AParam2
end:A
Example 2: Inherited Stage Name Conflict
If node A defines a tour script as follows:
stage:First
active:AParam1
text:Fill in AParam1 to make you happy
next:Second
end:First
stage:Second
active:AParam2
Date of Last Save: Friday, December 06, 2013
23
Constructing Tour Guides for LAE Nodes
text:Fill in AParam2 to make you money
end:Second
Then if node B can inherit from node A, and set its tour guide inheritance mode to either “Insert Before
Inherited Stages” or “Insert After Inherited Stages” then the following will cause an error due to a stage
name conflict:
#invalid: Duplicate stage name “First”
stage:First
active:BParam1
text:Fill in BParam1 to make you angry
end:First
Date of Last Save: Friday, December 06, 2013
24
Appendix A.
Advanced: Evaluation and Navigation of a Tour Guide
This section outlines the tour guide functionality as experienced by the "tourist" when using a node with
a tour guide defined. This describes how the guide is evaluated by BRE and how the user will be guided
through the tour. In general, the behavior of the tour will be relatively easy to understand once you
have written the tour. Therefore, in general, this section can be ignored unless you are having difficulty
understanding how the tour is being presented.
Navigating the Tour
When the user opens the node editor, what is displayed depends on whether or not there is a tour
defined for that node, and whether or not the user has the guided tours preference switched on or off in
Tools->Preferences.
The option to enter and exit the tour is in a checkbox “Guided Tour”. This is only displayed when there is
a tour available on the node. This is checked when a tour is in progress and unchecked when there is no
tour in progress. The user can check and uncheck this checkbox to toggle between using the tour and
using the node editor “normally”.
This information is summarized in the following table:
Node Guided Tours
True
True
Tour Defined on Node
True
False
False
True
False
False
Display
The tour is displayed
Node editor appears without any
tour information
Node editor is displayed with a
checkbox to allow the user to
start the tour, however the tour
is not displayed until they select
to show the tour
Node editor appears without any
tour information
Once the tour is underway, the tour takes the tourist through a series of stages. Within each stage, there
are a set of “active” parameters which are to be entered for that stage.
The information and controls for each stage in the tour is displayed at the bottom of the node editor
and contains:


Buttons for Previous and Next (or Finish if the stage is the last stage in the tour)
o These may be enabled or disabled depending on the current state and tour plan as
described in the following sections.
Text describing what is to be done for the current stage
o The informational text is composed of the text element in the tour script
Date of Last Save: Friday, December 06, 2013
Constructing Tour Guides for LAE Nodes
o
If there are any paramText elements defined on the stage, all of the paramText
documentation for all selected parameters will be displayed below the description from
the text element.
In addition to these items, the node editor has different display properties when a guided tour is
underway, as follows:




All selected parameters have a “normal” label, however the parameters themselves are
surrounded by a bold black border
The selected parameter which currently has focus has a slightly thicker bold border than the
other active parameters
All non-selected parameters are greyed out
The labels for all non-selected parameters are greyed out unless they contain a validator which
is not satisfied (in which case they are displayed in the red color which is standard for cases
where validation isn’t satisfied on a parameter)
An example of the display for a tour stage is shown below. In this instance, the “Numeric” parameter is
active on the stage, while SqlQuery and SqlQueryFieldBindings are not valid for the stage.
Figure 1 Example of a tour stage with a selected "Numeric" parameter
Split Tour Stages
There is no restriction that all active parameters within a tour stage in the tour script are defined to be
present on the same parameter group. Some active parameters may not be visible. However even for all
Date of Last Save: Friday, December 06, 2013
26
Constructing Tour Guides for LAE Nodes
selected parameters (i.e. active, visible parameters) that are defined in a stage within a tour script, these
could be split across multiple parameter groups/tabs. While it would generally be bad practice to define
a tour stage in this manner, the real reason this is allowed and is not treated as an error condition is
because anyone using (i.e. inheriting from the node) has the option to modify the parameter group of
any parameter it inherits.
Therefore, a tour planner could construct a tour script where all active parameters for a given tour stage
are defined on the one parameter group. However someone using the node could modify the parameter
groups using the “inherited parameter group overrides” mechanism, and the active parameters would
then be split across multiple parameter groups – thereby split across multiple tabs in the UI. When this
occurs, BRE will split the tour stage into multiple stages such that each compiled tour stage has all of its
active parameters on the same parameter group.
BRE will first check if the selected parameters defined within a tour stage are all on the same group. If
they are not on the same group, then a new tour stage will be constructed for each of the parameter
groups. The generated stages are all constructed with the explicit display condition and text from the
original stage defined in the tour script. The active parameters and parameter text for each of the stage
will only contain the parameters that are active within the parameter group for that stage.
BRE will construct the stages in order based on the order that the active parameters are defined in the
stage in the tour script. For the first tour of these stages, the original stage name is maintained, such
that all existing stages will still be able to reference it correctly in their next element. The next element
on the last of these stages is maintained such that the next element in the last of the generated stages
will correctly point to the stage that the original stage pointed to.
All other next elements and stage names within the generated stages are auto-generated.
Consider the following example tour script:
stage:A
active:AParam
text:Fill in AParam
next:B
end:A
stage:B
displayCondition:{{?SomeParam?}}
#BParam1 is in parameter group "General"
active:BParam1
#BParam2 is in parameter group "Optional"
active:BParam2
#BParam3 is in parameter group "Connection"
Date of Last Save: Friday, December 06, 2013
27
Constructing Tour Guides for LAE Nodes
active:BParam3
#BParam4 is in parameter group "Optional"
active:BParam4
#BParam5 is in parameter group "General"
active:BParam5
text:Fill in all of the BParams
paramText:BParam1:Sets the first part of the BParams
paramText:BParam2:Sets the second part of the BParams
paramText:BParam3:Sets the third part of the BParams
paramText:BParam4:Sets the fourth part of the BParams
paramText:BParam5:Sets the fifth part of the BParams
next:C
end:B
stage:C
active:CParam
text:Fill in CParam
end:C
When BRE compiles this tour script, it realizes that for the stage B, the selected parameters are split
across multiple parameter groups. Therefore, it will split this stage and insert generated stages, such
that the resulting tour script will be the following:
stage:A
active:AParam
text:Fill in AParam
next:B
end:A
stage:B
displayCondition:{{?SomeParam?}}
#BParam1 is in parameter group "General"
active:BParam1
#BParam5 is in parameter group "General"
active:BParam5
text:Fill in all of the BParams
paramText:BParam1:Sets the first part of the BParams
paramText:BParam5:Sets the fifth part of the BParams
Date of Last Save: Friday, December 06, 2013
28
Constructing Tour Guides for LAE Nodes
next:autoGenerated_B_Stage_1
end:B
stage:autoGenerated_B_Stage_1
displayCondition:{{?SomeParam?}}
#BParam2 is in parameter group "Optional"
active:BParam2
#BParam4 is in parameter group "Optional"
active:BParam5
text:Fill in all of the BParams
paramText:BParam2:Sets the second part of the BParams
paramText:BParam4:Sets the fourth part of the BParams
next:autoGenerated_B_Stage_2
end:autoGenerated_B_Stage_1
stage:autoGenerated_B_Stage_2
displayCondition:{{?SomeParam?}}
#BParam3 is in parameter group "Connection"
active:BParam3
text:Fill in all of the BParams
paramText:BParam3:Sets the third part of the BParams
next:C
end:autoGenerated_B_Stage_2
stage:C
active:CParam
text:Fill in CParam
end:C
Evaluated Tour Plan
When the user opens the node editor, and a tour guide is to be displayed, BRE will first compose the
tour script based on the tour script entered and the inheritance mechanism used in the inheritance
hierarchy of the node until the node or one of its parents defines an inheritance mechanism of “replace
inherited tour”. The combined tour script is then evaluated to form an evaluated tour plan. This tour
plan consists of a series of chained tour stages. There can only be one first tour stage, and one last tour
stage – although in the case of a tour with one stage, the first tour stage may be the last. Each stage
Date of Last Save: Friday, December 06, 2013
29
Constructing Tour Guides for LAE Nodes
within the tour that is not the last tour stage will point to the next tour stage in the chain (the Next
element defined, or the subsequent stage defined in the tour script). Each stage within the tour that is
not the first tour stage will be pointed to by one other tour in the chain. The links are only one-way.
There are no links pointing to the previous element in the tour.
Tour Stage States
Each tour stage is classified into a state in the state tree defined below. The state of the tour stage can
be used to determine the overall tour guide mode that will be used when starting a tour and when the
Next/Finish buttons will be enabled on a given tour.


Invalid
o The tour stage contains invalid syntax, contains a reference to a stage in a “Next”
element that would cause a loop in the tour, or points to an undefined stage. An invalid
tour stage will result in an invalid tour.
Valid
o A tour stage with correct syntax, which doesn’t result in loops, and points to no
undefined stages.
o Non-Operational
 A valid tour stage that does not contain any active, visible parameters
o Operational
 A valid tour stage that contains at least one active, visible parameter
 Unsatisfied
 An operational tour stage which contains at least one active, visible
parameter that has a validator and is not valid according to its validator.
 Satisfied
 An operational tour stage where all active, visible parameters are valid
(either with no validator, or valid according to their validator)
 Fully Specified
o A satisfied tour stage where all parameters are populated
Tour Guide Modes
When a tour guide is initialized, it can be in one of three modes: "Normal", "Review/Edit" or "Invalid".
Since "Invalid" implies that the tour is not valid, and won't be displayed there are only two modes with
which a user will ever navigate a tour: "Normal" or "Review/Edit". In general, the tour will be started in
"Review/Edit" mode. It is only if the user hops off then hops on the tour that the tour guide will be
started in "Normal" mode – and then, only if all stages are not fully specified.
Depending on the mode, the implicit display condition applied to each stage is different. Once a tour is
underway, this mode is used throughout the duration of the tour. These modes are outlined in the
following table.
Date of Last Save: Friday, December 06, 2013
30
Constructing Tour Guides for LAE Nodes
Tour Guide Mode
Normal
Review/Edit
Invalid
When starting the tour, BRE will select this mode when…
There is at least one Operational stage in the chain which is
not Fully Specified (i.e. Unsatisfied, or Satisfied but not Fully
Specified) that has either:
 No explicit displayCondition or
 A displayCondition which evaluates to true
AND
The user has been on the tour previously, but has hopped off
the tour without finishing it (clicking finish) and has rejoined.
The above conditions are not met. However, there is at least
one Operational stage in the tour that has either:
 No explicit displayCondition or
 A displayCondition which evaluates to true
Neither of the above conditions are met
For a tour in “Invalid Mode”, no tour guide will be displayed, and no checkbox will be displayed to allow
the user to start the tour.
Parameter Navigation Mode
There are effectively two modes of parameter navigation. These are “Normal” and “Revisit”. Whenever
the user is simply entering parameter values, and clicking the “Next” button, they are operating in
“Normal” parameter navigation mode. However, if a user clicks on “Previous” on a given stage S, then
they will be brought to some other stage T. If they are then brought back to stage S, then the first time
they visit that stage, the parameter navigation mode for that stage will be “Revisit”.
As an example, consider the tour script below defined on a node N:
stage:A
active:AParam
text:Fill in AParam
next:B
end:A
stage:B
active:BParam
text:Fill in BParam
next:C
end:B
stage:C
active:CParam
text:Fill in CParam
Date of Last Save: Friday, December 06, 2013
31
Constructing Tour Guides for LAE Nodes
end:C
Then the following table outlines the parameter navigation mode that will be in operation during
various tour stages (assuming the user has “Guided Node Tours” checked in BRE preferences):
User Action
Open Node
Editor for node N
Populates
AParam
Clicks "Next"
Populates
BParam
Clicks "Previous"
Modifies AParam
Clicks Next
Modifies BParam
Clicks "Next"
Clicks "Previous"
Clicks "Next"
State After User Action
Active
Parameter Navigation
Stage
Mode
A
Normal
A
B
Normal
Normal
B
A
A
B
B
C
B
C
Normal
Normal
Normal
Revisit
Revisit
Normal
Normal
Revisit
Note that stage B is first visited in “Normal” parameter navigation mode. However, after clicking
“Previous” while on stage B, the next time that the stage B is evaluated, it is in “Revisit” parameter
navigation mode. However, since the stage has now been revisited, then the next time the stage is
evaluated (via clicking “Previous” from stage C), the stage is evaluated in “Normal” parameter
navigation mode.
Implicit Display Condition
The implicit display condition in use depends on the mode in which the tour is operating and the
parameter navigation mode. These implicit display conditions are outlined in the following table.
Tour Guide Mode
Normal
Review/Edit
Invalid
Parameter Navigation Mode
Implicit Display Condition
Normal
The stage is Operational, and not Fully
Specified
Revisit
The stage is Operational
All
The stage is Operational
All
N/A
There is no valid tour defined so no tour
(or checkbox) is displayed
Date of Last Save: Friday, December 06, 2013
32
Constructing Tour Guides for LAE Nodes
The properties and actions of the Next, Previous and Finish buttons are outlined in the following table
Button
Next
Tour Guide
Mode
Normal or
Review/Edit
Visibility
Whenever there
is another stage
later in the tour
that the user
can transition to
Enabled
The current stage is
Satisfied
Previous Review/Edit
(see notes
below for
"Normal"
mode)
Always
Finish
Always
There are stages that
the user has clicked
“Next” on to transition
away from and not
since “Previous” to
return to that step.
From the current stage
in the tour and
downstream, there
are no Unsatisfied
stages.2
Normal or
Review/Edit
Action
BRE follows the chained tour
stages and – using the implicit
and explicit display conditions –
determines the next stage to
display. This stage then
becomes the current tour stage
and is displayed.
Displays the last stage that was
displayed prior to the current
stage
Exits the tour guide
For "Review/Edit" mode, note that when the tour script is evaluated and an evaluated tour chain is
composed, there are no links to previous elements in the tour. There are only forward links. Therefore,
the stage which is displayed when “Previous” is clicked is simply the last stage which was displayed prior
to the current stage.
For "Normal" mode, when the tour script is evaluated and an evaluated tour chain is composed, if there
are any stages which are skipped which are:

Operational stages
AND
o Have no displayCondition
OR
o A displayCondition which evaluates to true
These stages will be available via the "Previous" button. The previous button is also always visible in
"Normal" mode. When the user clicks "Next" from a given stage S in "Normal" mode, the stage S is
added appended to the stages that can be reached via the Previous button.
2
Note that there may be stages upstream that have become unsatisfied due to textual substitution invalidating a
validator, but these are not considered in determining the enabled status of "Finish"
Date of Last Save: Friday, December 06, 2013
33
Constructing Tour Guides for LAE Nodes
The explicit and implicit display conditions are not evaluated when determining the stage to display
after the user clicks on “Previous”. Therefore, BRE determines which stage to display in the case of the
user clicking “Previous” via the use of a simple previous stack from which stages are pushed and popped.
It is important to note that this stack is not used when the user clicks “Next” after clicking “Previous”.
Rather, when the user clicks “Next”, the evaluated tour chain links – along with implicit and explicit
display conditions – are used to determine the next stage to display.
Consider the following example:
stage:A
active:AParam
text:Fill in AParam
next:B
end:A
stage:B
displayCondition:"{^AParam^}}" == "A"
active:BParam
text:Fill in BParam
next:C
end:B
stage:C
active:CParam
text:Fill in CParam
end:C
Then consider the consequences of the following user actions:
State After User Action
Parameter Values
User Action
Open Node Editor
Populates AParam
with value "A"
Active Stage
A
AParam
BParam CParam Comment
A
A
Clicks "Next"
Populates BParam
with value "B"
B
A
B
A
B
Clicks "Previous"
A
A
B
Stage B is active, since its
displayConditions are satisfied
Stage A is active, since it was
the stage displayed prior to B
Date of Last Save: Friday, December 06, 2013
34
Constructing Tour Guides for LAE Nodes
Changes AParam
to "A1"
Clicks "Next"
Populates Cparam
with value "C"
Clicks "Finish"
A
A1
B
C
A1
B
C
<none>
A1
A1
B
B
Stage C is active, since the
explicit displayCondition for
stage B is not satisfied
C
C
Note that in this instance, the user navigates away from stage B using the “Previous” button. However,
after modifying the value of AParam on stage A and clicking “Next”, they are brought to stage C rather
than stage B.
Parameter Display Order vs. Parameter Navigation Order
Within the Node Editor in BRE, the user has the option of declaring the order of parameters. This defines
the graphical layout of the parameters within a given parameter group (note there is no ability to set
parameter group ordering at the moment). When a tour stage is displayed, however, there is a separate
concept of “parameter navigation order” within a tour. The tour guide does not modify any of the
graphical layout of parameters. However, it does define the order of selected parameters within a tour
stage.
The order with which active parameters are defined in a tour stage determines their “selection order”.
For the current tour stage, the first visible parameter with regards to its selection order will have focus.
Navigation within a tour stage will follow the selection order of the parameters as defined in the tour
script.
Keyboard Navigation
Normally, when not using guided tours, the user can use the Tab and Shift+Tab key accelerators to
navigate around the parameters. Similarly, when the guided tour is underway, these keys can be used.
However, rather than tab jumping to the next parameter, pressing Tab will jump to the next active,
visible parameter within the stage, based on its selection order. If there are no more selected
parameters, the focus on Tab will shift to the “Previous” button (if it is enabled), followed by the “Next”
button then the ”Finish” button. Similarly, the Shift+Tab key combination will navigate to the previous
selected parameter as per the selection order of the parameter stage. If there are no previous selected
parameters, the focus will shift to the “Next”/”Finish” button (if it is enabled), followed by the
“Previous” button.
Note: A tab in a text field will enter the tab in the text editor, rather than changing focus.
Hop-on-hop-off
Whenever the user clicks – with either right or left mouse buttons - on a non-selected parameter, they
will leave the tour. If they click on the button in a label of a non-selected multi-line parameter they will
Date of Last Save: Friday, December 06, 2013
35
Constructing Tour Guides for LAE Nodes
leave the tour. Similarly, if they click – again with either right or left mouse buttons - on any of the
parameter tabs other than the currently selected tab, they will leave the tour. The “Guided Tour”
checkbox at this point will be unchecked. The user can re-check the “Guided Tour” checkbox to re-join
the tour. When rejoining a tour, the user will restart the tour in "Normal" mode.
If the user clicks on Declare Parameters, they will leave the tour. On returning from the Declare
Parameters window, if there was a tour running when the user clicked on Declare Parameters, the node
editor will attempt to re-initialize the tour (i.e. as if the node editor had just been open). If the changes
in Declare Parameters have led to the tour that was previously displayed becoming invalid, then the user
will be presented with an appropriate error message.
Date of Last Save: Friday, December 06, 2013
36