| > Show on single page > Show on multiple pages |
Each tutorial in your bundle is bound by a help
element. The help
element supports
the following attributes:
id
(mandatory) is the internal ID of the tutorial, which you can use in a properties file to translate as needed (using TUTO.<id>.NAME and TUTO.<id>.DESCR) to display in the correct language in the Tutorials popup in the web interface.
icon
(optional, default: standard tutorial icon) is the path to the icon to display for this tutorial in the tutorial selection popup. The icon is relative to the location of Bundle.xml.
opacity
(optional, default: 0.4) is the opacity of the mask (the grey element that surrounds the highlighted element) for this tutorial. You can specify a value between 0 and 1 where 0 is transparent and 1 is completely opaque.
firstConnectionGroup
(optional, default: none) allows launching this tutorial automatically for users of the specified groups the first time that they log into Squore. This attribute accepts a semicolon-separated list of groups.
textPosition
(optional, default: EXTERNAL) is the location of the help text relative to the highlighted element. This attribute supports the following values:
INTERNAL to display the text inside the item
LEFT to display the text to the left of the item
RIGHT to display the text to the right of the item
EXTERNAL to display the text dynamically to the left or the right of the item, depending on where more space is available
TOP to display the text above the item
BOTTOM to display the text under the item
maskColor
(optional, default: transparent) is the colour of
the mask to display over the highlighted element. This attribute supports the colour syntax detailed in [colour syntax] .
maskOpacity
(optional, default:0.6) is the opacity of the mask over the highlighted element for this tutorial. You can specify a value between 0 and 1 where 0 is transparent and 1 is completely opaque.
textSize
(optional, default: 25) is the size of the help text displayed next to the highlighted element.
textColor
(optional, default: WHITE) is the colour of the help text displayed next to the highlighted element.
The help
element accepts one or more item
or
phase
elements. If you simply want to highlight items one at a time, add item
elements
directly in the help
. Using phase
elements is useful if you want to execute specific
actions or display several items at the same time.
The phase
element accepts the following attributes:
element
(optional, default: none) is the selector of the item to highlight when this phase starts. You can choose any element from the list of predefined selectors described in the section called “Element Selectors”.
param
(optional, default: none) is an optional parameter which you can pass to certain selectors. This parameter is generally used when you specify to highlight a specific chart, metric or artefact as opposed to the first element available. You can read more about the selectors that support parameters in the section called “Element Selectors”.
type
(optional, default: SEQUENTIAL) allows specifying the display behaviour of the child items of this phase. The supported values are:
SEQUENTIAL to highlight items one at a time
PARALLEL to highlight all items in this phase at the same time
PROGRESSIVE to highlight items in succession, retaining the previous highlight at each click
FREE to allow users to perform actions inside the highlighted item
optional
(optional, default: false) allows to skip the
phase automatically if the items or elements it uses are not available for the current user. You can for example create a
tutorial that includes information about the Capitalisation Base that will only be shown to users who can actually use
the Capitalisation Base.
The item
element accepts the following attributes:
element
(mandatory) is the selector of the item to highlight. You can choose any element from the list of predefined selectors described in the section called “Element Selectors”.
param
(optional, default: none) is an optional parameter which you can pass to certain selectors. This parameter is generally used when you specify to highlight a specific chart, metric or artefact as opposed to the first element available. You can read more about the selectors that support parameters in the section called “Element Selectors”.
descrId
(mandatory) is the ID of the help text to display for the highlighted element. Use this ID is used in your properties file to localise the tutorial.
linkId
(optional, default: none) allows creating a link to another tutorial. The value must be the name
of another tutorial defined in the same bundle. You can specify several links by separating them with a /.
You can use a preAction
element in a phase if you want to carry out an action before highlighting
a specific item. The preAction
element supports the following attributes:
action
(mandatory) is the action to perform. The supported actions are:
EXPAND_PORTFOLIO_TREE expands the Project Portfolios down to project level. This action accepts a project name as a parameter, otherwise it uses the first project available.
COLLAPSE_PORTFOLIO_TREE collapses the entire Project Portfolios
SELECT_MODEL selects a model in the Project Portfolios. This action accepts a model name as a parameter, otherwise it uses the first model available.
SELECT_PROJECT expands a project node in the Project Portfolios to show its list of versions and select the most recent one. This action accepts a project name and version as a parameter (e.g.: Earth/V6), otherwise it uses the first project available.
EXPAND_ARTEFACT_TREE expands the Artefact Tree. This action accepts the path to an artefact as a parameter (e.g.: Earth/apps/machine.c), otherwise it uses the first artefact available.
COLLAPSE_ARTEFACT_TREE collapses the entire Artefact Tree.
SELECT_ARTEFACT clicks an artefact in the Artefact Tree to show its dashboard
SELECT_ARTEFACT_LEAF clicks the first lowest-level artefact leaf in the Artefact Tree.
EXPAND_MEASURE_TREE expands the Indicator Tree. This action accepts the path to a metric as a parameter (e.g.: Maintainability/Analysability/Function Analysability), otherwise it uses the first available measure in the tree.
COLLAPSE_MEASURE_TREE collapses the entire Indicator Tree.
SELECT_WIZARD picks a wizard from the list of wizards available in the first step of the project wizard. This action requires a wizardId (e.g.: RISK) as a parameter.
RUN_PROJECT_CREATION clicks the Run button on the summary screen of the project wizard.
param
(optional, default: none) is an optional parameter you can pass to an action if it supports it.
clickIndicator
(optional, default: varies according to the action) allows showing or hiding the click indicator when the action is performed. This attribute supports the values TRUE and FALSE.
It is generally not necessary to specify any preAction
, since each element selector automatically places
the web interface in the right context to highlight the specified item. For example, if you specify that a tutorial should highlight the Findings
tab, the tutorial will open the Explorer and switch to the Findings tab automatically for the first project available. It is only necessary to use a
preAction
if you want a specific project or model to be selected before showing the Findings tab.
The table below lists the selectors that you can use in the
item
or phase
elements of your tutorials. when
a parameter is allowed, it is specified. If no parameter is specified, the first available item is usually
highlighted.
Table 12.1. Available element selectors for tutorials in Squore
| element | param | Highlighted Element |
|---|---|---|
| CUSTOM | The JQuery selector of the element of the Squore UI you want to highlight | - |
| BODY | - | the part of the window containing the Squore UI |
| TOP | - | the entire window |
| BREADCRUMBS | - | the breadcrumbs bar |
| MENU_BAR | - | the menu bar |
| MENU_BAR_HOME | - | the home button in the menu bar |
| MENU_BAR_EXPLORER | - | the Explorer button in the menu bar |
| MENU_BAR_MY_PROJECTS | - | the My Projects button in the menu bar |
| MENU_BAR_MY_FAVOURITES | - | the My Favourites button in the menu bar |
| MENU_BAR_CAPITALISE | - | the Capitalisation Base button in the menu bar |
| MENU_BAR_USER | - | the <username> in the menu bar |
| MENU_MODEL | - | the Models button in the menu bar |
| MENU_ADMIN | - | the Administration button in the menu bar |
| MENU_HELP | - | the ? in the menu bar |
| HOME_PAGE | - | the home page |
| HOME_WELCOME | - | the welcome text on the home page |
| HOME_USER | - | the user details section of the home page |
| HOME_WORK | - | the list of tasks available to users on the home page |
| HOME_HELP | - | the help section of the home page |
| HOME_PINNED | - | the list of pinned artefacts on the home page |
| HOME_HISTORY | - | the list of recently visited projects on the home page |
| HOME_EXPLORER | - | the link to the Explorer on the home page |
| HOME_PROJECTS | - | the link to My Projects on the home page |
| HOME_CAPITALISE | - | the link to the Capitalisation Base on the home page |
| SUB_MENU_MODEL | - | the entire Models menu |
| SUB_MENU_MODEL_ROW | a row ID | the specified option in the Models menu |
| SUB_MENU_MODEL_ROW_FIRST | - | the first option in the Models menu |
| SUB_MENU_ADMIN | - | the entire Administration menu |
| SUB_MENU_ADMIN_ROW | a row ID | the specified option in the Administration menu |
| SUB_MENU_ADMIN_ROW_FIRST | - | the first option in the Administration menu |
| SUB_MENU_HELP | - | the entire Help menu |
| SUB_MENU_HELP_ROW | a row ID | the specified option in the Help menu |
| SUB_MENU_HELP_ROW_FIRST | - | the first option available in the Help menu |
| TUTORIAL_POPUP | - | the tutorial selection popup |
| TUTORIAL_POPUP_MODEL | a model ID | the tutorials for the specified model in the tutorial selection popup |
| TUTORIAL_POPUP_MODEL_FIRST | - | the first model-specific tutorial available in the tutorial selection popup |
| TUTORIAL_POPUP_TUTORIAL_NAME | a tutorial's id
| the specified tutorial |
| TUTORIAL_POPUP_TUTORIAL_NAME_FIRST | - | the name
of the first available tutorial in the tutorial selection popup |
| TUTORIAL_POPUP_TUTORIAL_DESCR | a tutorial's id
| the description of the specified tutorial |
| TUTORIAL_POPUP_TUTORIAL_DESCR_FIRST | - | the description of the first available tutorial in the tutorial selection popup |
| EXPLORER | - | the Explorer |
| DRILLDOWN | - | the drilldown pane of the Explorer |
| EXPLORER_TAB | - | the right-hand panel of the Explorer |
| PORTFOLIO_TREE | - | the Project Portfolios |
| ARTEFACT_TREE | - | the Artefact Tree |
| MEASURE_TREE | - | the Indicator Tree |
| EXPLORER_HEADER | - | the Explorer tabs |
| PORTFOLIO_HEADER | - | the Project Portfolios tabs |
| ARTEFACT_TREE_SEARCH | - | the search box in the Artefact Tree |
| ARTEFACT_TREE_FILTER | - | the filter button in the Artefact Tree |
| REVIEW_SET | - | the Review Set |
| PORTFOLIO_TREE_PROJECT | a project name (Earth) or name and version (Earth/V3) | a project and its list of versions in the Project Portfolios |
| PORTFOLIO_TREE_PROJECT_FIRST | - | the first project in the Project Portfolios and its versions |
| MODEL_DASHBOARD | a model ID | the dashboard for the specified model |
| MODEL_CHARTS | a model ID | the charts section of the dashboard for specified model |
| MODEL_CHART_FIRST | a model ID | the first chart in the dashboard of the specified model |
| MODEL_TABLE | a model ID | the table section of the dashboard for the specified model |
| MODEL_TABLE_ROW_FIRST | a model ID | the first table row in the dashboard of the specified model |
| MODEL_CHART | a chart ID | the specified chart in the dashboard for the specified model |
| MODEL_TABLE_ROW | a project name (Earth) or name and version (Earth/V3) | the specified project in the dashboard for the specified model |
| MODEL_CHART_POPUP | a chart ID | the chart viewer with the specified model-level chart |
| MODEL_CHART_POPUP_GRAPH | a chart ID | The chart in the chart viewer |
| MODEL_CHART_POPUP_PREVIOUS_ARROW | a chart ID | the previous arrow in the chart viewer |
| MODEL_CHART_POPUP_NEXT_ARROW | a chart ID | the next arrow in the chart viewer |
| MODEL_CHART_POPUP_NAV_BAR | a chart ID | the carousel in the chart viewer |
| MODEL_CHART_POPUP_ASIDE | a chart ID | the right-hand panel of the chart viewer |
| MODEL_CHART_POPUP_ASIDE_HEAD | a chart ID | the tabs in the right hand panel of the chart viewer |
| MODEL_CHART_POPUP_DESCR | a chart ID | the description panel of the chart viewer |
| FILTER_POPUP | a project name (Earth) or name and version (Earth/V3) | the filter popup |
| FILTER_LEVEL | a project name (Earth) or name and version (Earth/V3) | the levels section of the filter popup |
| FILTER_TYPE | a project name (Earth) or name and version (Earth/V3) | the types section fo the filter popup |
| FILTER_EVOLUTION | a project name (Earth) or name and version (Earth/V3) | the evolution section of the filter popup |
| FILTER_STATUS | a project name (Earth) or name and version (Earth/V3) | the status section of the filter popup |
| ARTEFACT_TREE_LEAF | a project name (Earth) or name and version (Earth/V3) | a lowest-level artefact of a project int he artefact_tree; |
| MEASURE_TREE_LEAF | a project name (Earth) or name and version (Earth/V3) | a lowest-level metric in the Indicator Tree |
| DASHBOARD | a project name (Earth) or name and version (Earth/V3) | the dashboard for a project |
| SCORECARD | a project name (Earth) or name and version (Earth/V3) | the scorecard |
| KPI | a project name (Earth) or name and version (Earth/V3) | the KPI chart in the scorecard |
| CHARTS | a project name (Earth) or name and version (Earth/V3) | the charts section of the dashboard |
| TABLES | a project name (Earth) or name and version (Earth/V3) | the tables in the scorecard |
| CHART_FIRST | a project name (Earth) or name and version (Earth/V3) | the first chart in the dashboard |
| LINE | a project name (Earth) or name and version (Earth/V3) | a line in a table |
| CHART | a chart ID | the specified chart |
| CHART_FIRST | - | the first chart in the dashboard |
| TABLE | a table ID | a table in the scorecard |
| TABLE_FIRST | - | the first table in the scorecard |
| MEASURE_POPUP | a measure, indicator or info ID | the information popup for a metric |
| MEASURE_POPUP_CONTENT | a measure, indicator or info ID | the contents of the information popup for the metric |
| MEASURE_POPUP_LEVELS | a measure, indicator or info ID | the scale for the metric in the information popup |
| MEASURE_POPUP_ROW_FIRST | a measure, indicator or info ID | the first row in the information popup |
| MEASURE_POPUP_ROW | a row ID in the information popup | the specified row in the information popup |
| CHART_POPUP | a chart ID | the chart viewer |
| CHART_POPUP_GRAPH | a chart ID | the chart in the chart viewer |
| CHART_POPUP_COMPARE_OPTION | a chart ID | the compare mode button |
| CHART_POPUP_PREVIOUS_ARROW | a chart ID | the previous arrow in the chart viewer |
| CHART_POPUP_NEXT_ARROW | a chart ID | the next arrow in the chart viewer |
| CHART_POPUP_NAV_BAR | a chart ID | the carousel in the chart viewer |
| CHART_POPUP_ASIDE | a chart ID | the right-hand panel of the chart viewer |
| CHART_POPUP_ASIDE_HEAD | a chart ID | the tabs in the right hand panel of the chart viewer |
| CHART_POPUP_DESCR | a chart ID | the description panel of the chart viewer |
| CHART_POPUP_COMMENTS | a chart ID | the comments panel of the thart viewer |
| CHART_POPUP_FAVORITES | a chart ID | the favourites panel of the chart viewer |
| CHART_POPUP_COMPARATIVE_CHART | a version name | the older version of the chart in the chat viewer in compare mode |
| ACTION_ITEMS | a project name (Earth) or name and version (Earth/V3) | the Action Items tab of the Explorer |
| ACTION_ITEMS_TABLE | a project name (Earth) or name and version (Earth/V3) | the Action Items table |
| ACTION_ITEMS_TABLE_HEAD | a project name (Earth) or name and version (Earth/V3) | the Action Items table header |
| ACTION_ITEMS_TABLE_HEAD_CHECK | a project name (Earth) or name and version (Earth/V3) | the Action Items Select All checkbox |
| ACTION_ITEMS_ADD_REVIEW_SET | a project name (Earth) or name and version (Earth/V3) | the Action Items Add to review set button |
| ACTION_ITEMS_EXPORT_LIST | a project name (Earth) or name and version (Earth/V3) | the Action Items export formats |
| ACTION_ITEMS_EXPORT_BUTTON | a project name (Earth) or name and version (Earth/V3) | the Action Items export button |
| ACTION_ITEMS_SEARCH | a project name (Earth) or name and version (Earth/V3) | the Action Items filtering options |
| ACTION_ITEMS_ROW | a project name (Earth) or name and version (Earth/V3) | a single action item |
| ACTION_ITEMS_REASON | a project name (Earth) or name and version (Earth/V3) | a detailed action item |
| ACTION_ITEMS_ADVANCED_SEARCH | a project name (Earth) or name and version (Earth/V3) | the Action Items advanced filtering options |
| ACTION_ITEMS_ADVANCED_SEARCH_SELECT_FIRST | a project name (Earth) or name and version (Earth/V3) | the Action Items advanced filtering options with a selection applied |
| ACTION_ITEMS_ADVANCED_SEARCH_SELECT | The name of a list of the advanced search | the Action Items with the specified selection applied |
| HIGHLIGHTS | a project name (Earth) or name and version (Earth/V3) | the Highlights tab of the Explorer |
| HIGHLIGHTS_TABLE | a project name (Earth) or name and version (Earth/V3) | the Highlights table |
| HIGHLIGHTS_TABLE_HEAD | a project name (Earth) or name and version (Earth/V3) | the Highlights table header |
| HIGHLIGHTS_TABLE_HEAD_CHECK | a project name (Earth) or name and version (Earth/V3) | the Highlights table Select All checkbox |
| HIGHLIGHTS_SEARCH | a project name (Earth) or name and version (Earth/V3) | the Highlights options |
| HIGHLIGHTS_SEARCH_FILTER | a project name (Earth) or name and version (Earth/V3) | the Highlights categories list |
| HIGHLIGHTS_SEARCH_TYPE | a project name (Earth) or name and version (Earth/V3) | the Highlights artefact type list |
| HIGHLIGHTS_EXPORT_BUTTON | a project name (Earth) or name and version (Earth/V3) | the Highlights export button |
| HIGHLIGHTS_ADD_REVIEW_SET | a project name (Earth) or name and version (Earth/V3) | the Highlights Add to review set button |
| HIGHLIGHTS_ROW_FIRST | a project name (Earth) or name and version (Earth/V3) | the first row of Highlights in the table |
| FINDINGS | a project name (Earth) or name and version (Earth/V3) | the Findings tab of the Explorer |
| FINDINGS_TABLE | a project name (Earth) or name and version (Earth/V3) | the Findings table |
| FINDINGS_TABLE_HEAD | a project name (Earth) or name and version (Earth/V3) | the Findings table header |
| FINDINGS_SEARCH | a project name (Earth) or name and version (Earth/V3) | the Findings filtering controls |
| FINDINGS_RULE | a project name (Earth) or name and version (Earth/V3) | the Findings table |
| FINDINGS_ARTEFACT | a project name (Earth) or name and version (Earth/V3) | artefacts in the Findings table |
| FINDINGS_ROW_FIRST | a project name (Earth) or name and version (Earth/V3) | the first row in the Findings table |
| FINDINGS_ADVANCED_SEARCH | a project name (Earth) or name and version (Earth/V3) | advanced filtering options in the Findings table |
| FINDINGS_ADVANCED_SEARCH_SELECT_FIRST | a project name (Earth) or name and version (Earth/V3) | a selection in the advanced filtering options in the Findings table |
| FINDINGS_ADVANCED_SEARCH_SELECT | The name of a list of the advanced search | a selection in the advanced filtering options in the Findings table |
| REPORTS | a project name (Earth) or name and version (Earth/V3) | the Reports tab of the Explorer |
| REPORTS_REGION | a project name (Earth) or name and version (Earth/V3) | the Reports section |
| REPORTS_OPTIONS | a project name (Earth) or name and version (Earth/V3) | the Reports options |
| REPORTS_OPTION_TEMPLATE | a project name (Earth) or name and version (Earth/V3) | the available report templates |
| REPORTS_OPTION_FORMAT | a project name (Earth) or name and version (Earth/V3) | the available report formats |
| REPORTS_OPTION_SYNTHETIC_VIEW | a project name (Earth) or name and version (Earth/V3) | the synthetic report option |
| REPORTS_CREATE | a project name (Earth) or name and version (Earth/V3) | the Generate button button |
| EXPORT_REGION | a project name (Earth) or name and version (Earth/V3) | the Exports section |
| EXPORT_OPTIONS | a project name (Earth) or name and version (Earth/V3) | the Exports options |
| EXPORT_CREATE | a project name (Earth) or name and version (Earth/V3) | the Exports Create button |
| FORMS | a project name (Earth) or name and version (Earth/V3) | the Forms tab of the Explorer |
| FORMS_ATTRIBUTE | a project name (Earth) or name and version (Earth/V3) | a form attribute name |
| FORMS_ATTRIBUTE_FIELD | a project name (Earth) or name and version (Earth/V3) | a form attribujte value |
| FORMS_ATTRIBUTE_COMMENT | a project name (Earth) or name and version (Earth/V3) | a form attribute justification |
| FORMS_HISTORY | a project name (Earth) or name and version (Earth/V3) | a form value history |
| FORMS_BLOCK | a project name (Earth) or name and version (Earth/V3) | a form block |
| INDICATORS | a project name (Earth) or name and version (Earth/V3) | the Indicators tab of the Explorer |
| INDICATORS_TABLE | a project name (Earth) or name and version (Earth/V3) | the Indicators table |
| INDICATORS_TABLE_HEAD | a project name (Earth) or name and version (Earth/V3) | the Indicators table header |
| INDICATORS_ROW | a project name (Earth) or name and version (Earth/V3) | a row in the Indicators table |
| MEASURES | a project name (Earth) or name and version (Earth/V3) | the Measures tab of the Explorer |
| MEASURES_TABLE | a project name (Earth) or name and version (Earth/V3) | the Measures table |
| MEASURES_TABLE_HEAD | a project name (Earth) or name and version (Earth/V3) | the Measures table header |
| MEASURES_ROW | a project name (Earth) or name and version (Earth/V3) | a row in the Measures table |
| COMMENTS | a project name (Earth) or name and version (Earth/V3) | the Comments tab of the Explorer |
| COMMENTS_TABLE | a project name (Earth) or name and version (Earth/V3) | the Comments table |
| COMMENTS_TABLE_HEAD | a project name (Earth) or name and version (Earth/V3) | the Comments table header |
| COMMENTS_ROW | a project name (Earth) or name and version (Earth/V3) | a row in the Comments header |
| CREATE_PROJECT_BUTTON | - | the New Project... button on the My Projects page |
| WIZARD_PANEL | - | the list of wizards in the project creation wizard |
| WIZARD_ROW | a wizard ID | a wizard in the list of wizards in wizards in the project creation wizard |
| WIZARD_ROW_FIRST | - | the first wizard in the list of wizards in the project creation wizard |
| WIZARD_NEXT_BUTTON | - | the Next button on the first page of the project creation wizard |
| GENERAL_INFORMATION | - | the General Information section of the project creation wizard |
| PROJECT_IDENTIFICATION_BLOCK | - | the Project Identification section of the project creation wizard |
| GENERAL_INFO_BLOCK | - | the General Information section of the project creation wizard |
| GENERAL_INFO_ROW | - | a row in the General Information section of the project creation wizard |
| PROJECT_NEXT_BUTTON | - | the Next button on the second page of the project creation wizard |
| DP_PANEL | - | the Data Provider panel in the project creation wizard |
| DP_PANEL_BLOCK | - | the Data Provider panel block in the project creation wizard |
| DP_PANEL_ROW | - | a row in the Data Provider panel block in the project creation wizard |
| DP_PANEL_NEXT_BUTTON | - | the next button on the Data Provider page of the project creation wizard |
| CONFIRMATION_PANEL | - | the summary page of the project creation wizard |
| SUMMARY | - | the summary of parameters specified on the summary page of the project creation wizard |
| CONFIRMATION_PANEL_PARAMETERS | - | the project parameters in command line form |
| RUN_NEW_PROJECT_BUTTON | - | the Run button on the summary page of the project creation wizard |
If you do not find the selector for the element you want to highlight, you can use CUSTOM with your own JQuery selector as a parameter. You can use your browser's developer tools to inspect the web interface and extract the XPath of the element.
Advanced users can also expand on the list of available selectors, by overriding the default
list of selectors available in <SQUORE_HOME>/configuration/tutorials/aliasTuto.xml: Copy the file and place
it in the same relative location in your own configuration folder. You cannot create new actions,
but if an action exists for what you want to do, you can add your selector following the syntax:
<alias name="SELECTOR_ID" path="[JQuery selector with escaped ':' and '.']"/>