Available translations
loading results
Tutorial
The tutorial hierarchy features a free arrangement of Tutorial Topic and Tutorial Step nodes that make up a tutorial. Each node in the hierarchy, including the parent tutorial node, represents an HTML page that may be overlaid on top of both the Design Space and the Charting Space.
Content
Nodes in the hierarchy may be arranged freely, meaning that there may be as many tutorial topics and tutorial steps as desired. Tutorial topics may contain tutorial steps but also other tutorial topics. This allows nesting topics to be used as subtopics.
The system – as usual – evaluates the hierarchy in a clockwise direction starting from the node to the right of the parent Tutorial node, and goes to the deepest node of each branch before moving to the next one.
In general terms, all types of nodes behave similarly in the sense that each node, independently of the precise type, represents a tutorial step in and of itself. That is, all nodes including the top-level Tutorial node, the Tutorial Topic node, and the Tutorial Step node may display a content page as a step in the tutorial. Subtle differences shall be pointed where appropriate.
Note: The key similarity among all types of nodes in the hierarchy is that all of them may draw content from the tutorial's collection of pages in the Docs. That is, each node in the hierarchy points to a Docs Page, and it is that page in the Docs that features the content displayed for the given step. The pointer is specified in the configuration of each node (see the docs property).
Configuring
Tutorial Configuration
The configuration of each node in the tutorial hierarchy determines the content and behavior of each step. All types of nodes share the same basic configuration. However, Tutorial Step nodes have extra properties, described on the Tutorial Step node page.
Tip: The configuration properties discussed on this page apply to all types of nodes in the hierarchy.
The layout of the HTML page follows the layout of the associated page in the Docs, although displayed within the confines of the tutorial window.
In other words, you affect the layout of the particular step by writing content and applying styles to individual paragraphs in the associated Docs Page.
Note: The HTML page features a limited space and does not support scrolling. If too much information is defined in the associated Docs Page, the resulting content overflows the available space in the tutorial window. There is no system-side control to deal with such overflows, so it's up to you to spread information across multiple steps and keep each page within its limits.
Configuration Properties
icon
The property icon requires two definitions:
- The "name" of the icon without the extension;
- The "project" the icon belongs to.
For your reference, icons are stored in the following path:
\Projects\[Project-Name]\Icons Tip: Use the existing collection of icons to illustrate each step of the tutorial. These illustrations help make for more compelling communication.
When the configuration exists, the icon is placed within a table, side by side with the text block that makes up the definition field of the associated Docs Page. When there is no icon, the definition occupies the full width of the page.
"icon": {
"name": "balance",
"project": "Foundations"
} The above configuration places the
balance.png icon of the Superalgos project in the table of the corresponding Docs page (see the docs property below). position
The position property determines the position of the floating HTML. There are three alternatives... "Left", "Right", or leave the field empty to position the page on the center of the screen.
"position": "Left" The configuration above places the tutorial step on the left-hand side of the screen.
slider
The slider property determines the position of the horizontal slider. There are three alternatives... "toTop", "toBottom", "toMiddle".
"slider": "toBottom" // Opens the Charting Space "slider": "toTop" // Opens the Design Space "slider": "toMiddle" // Enables using the Charting Space and the Design Space concurrently pressButton
The
pressButton property allows you to forcefully "Stop" the tutorial, go to the "Next" step, go to the "Previous" step, or "Skip" a step. When a step is loaded and one of these options is configured in this property, the action is applied immediately. Note: A common use of this feature is to skip a step, for instance, a Tutorial Topic node that is used solely for organizational purposes within the hierarchy, thus features no content. Leave the field empty for the step to play in the usual fashion.
"pressButton": "Next" The above configuration takes the user to the next step in the tutorial without displaying any content for the node in question.
Tip: You may use Tutorial Topic nodes for organizational purposes only, for instance, to arrange the hierarchy in a way that it's easy to read and maintain. Topics with too many steps are harder to deal with later on. In other words, you may use a Tutorial Topic node to group several steps, even if you don't intend the Tutorial Topic node to display any content. In such cases, you may use this property to skip the step that is not intended for content display.
docs
The docs property is used to point to the Docs Tutorial Page that feeds content to the particular tutorial step. The definition requires the name of the Project, the Docs Page Category which is always "Tutorial", and the complete name of the Docs Page, that is, the "type" as specified in the JSON file.
"docs": {
"project": "Foundations",
"category": "Tutorial",
"type": "Tutorial Step - Scales' Best-Kept Secrets"
} controlDocs
The property is used to control the behavior of the Docs panel. Within
controlDocs, several properties are available, and all of them are optional. Let's review each in detail. The panel property may be set to "Open" or "Close". This property controls the tab that allows you to open the Docs Panel in one step, and close it on a different step when it's no longer needed.
"controlDocs": {
"panel": "Open",
} Tip: If the Docs Panel is closed, the rest of the properties are somehow irrelevant. However, when the Docs Panel is open, the rest of the properties control what is displayed in the Docs Panel.
The property
closeTutorialEditor may switch on and off the Docs editor. When set to false or when there is no definition, and provided no specific Docs Page is called (see controlDocs below), the Docs panel shows the page associated with the current tutorial step in editing mode. "controlDocs": {
"panel": "Open",
"closeTutorialEditor": false,
} Tip: Because this definition is set to false by default, this is the usual behavior. That is, by default, when the Docs Panel is opened while a tutorial step is playing, the Docs Panel shows the Docs Page associated with the specific step so that the page may be edited right then and there.
When the
closeTutorialEditor property is set to true and there is no request to open a Docs page (see page property below), then the Docs panel shows whatever Docs Page was being displayed in the previous step. "controlDocs": {
"panel": "Open",
"closeTutorialEditor": true,
} Tip: You may want to close the tutorial editor when the user is supposed to interact with the Docs from one step to the next. For example, let's say the tutorial instructs the user to run a search and discusses the search results in the following step. In that case, you will want the tutorial editor to remain closed, as otherwise, the search performed by the user would be lost, and instead the page corresponding to the new tutorial step would be loaded.
The
searchPage property overruns the tutorial editor settings and loads the home search page featuring the search box in the center. "controlDocs": {
"panel": "Open",
"searchPage": true,
} Tip: Use the above setting when you wish the user to get the clean search box to make a search or run a command.
The page property is where you define which Docs Page must be loaded. You must specify the Project, the Docs Page Category, and the "type" which is the complete name of the page. The optional property anchor allows you to point the user to a specific paragraph in the page with the Docs Anchor Style.
"controlDocs": {
"panel": "Open",
"page": {
"project": "Foundations",
"category": "Topic",
"type": "Syntax Overview",
"anchor": "Previous Property"
}
} Tip: Use the above configuration when you wish the user to read a specific page in the Docs.
Initial Values
These are the Initial Values for Tutorial configuration:
{
"icon": {
"name": "",
"project": "Foundations"
},
"position": "Left",
"slider": "toTop",
"pressButton": "",
"docs": {
"project": "Foundations",
"category": "Tutorial",
"type": ""
},
"controlDocs": {
"panel": "",
"closeTutorialEditor": false,
"page": {
"project": "Foundations",
"category": "",
"type": ""
}
}
} Examples
This is a list of properties featured by the Tutorial configuration. Expanding a property shows sample values for the property extracted from the current Workspace.
Tutorial Menu
The Tutorial node has the following Node Menu items:
The Play menu item has the following properties:
- action: Play Tutorial
- actionProject: Education
- label: Play
- iconPathOn: play
- iconPathOff: play
- actionFunction:
payload.executeAction
The Resume menu item has the following properties:
- action: Resume Tutorial
- actionProject: Education
- label: Resume
- iconPathOn: resume
- iconPathOff: resume
- actionFunction:
payload.executeAction
The Configure menu item has the following properties:
- action: Configure
- actionFunction:
uiObject.configEditor.activate
- label: Configure
- iconPathOn: configuration
- iconPathOff: configuration
The Add Tutorial Step menu item has the following properties:
- action: Add UI Object
- actionProject: Visual-Scripting
- label: Add Tutorial Step
- relatedUiObject: Tutorial Step
- actionFunction:
payload.executeAction
- relatedUiObjectProject: Education
The Add Tutorial Topic menu item has the following properties:
- action: Add UI Object
- actionProject: Visual-Scripting
- label: Add Tutorial Topic
- relatedUiObject: Tutorial Topic
- actionFunction:
payload.executeAction
- relatedUiObjectProject: Education
The Reset Tutorial Progress menu item has the following properties:
- action: Reset Tutorial Progress
- actionProject: Education
- askConfirmation: true
- confirmationLabel: Confirm to Reset
- label: Reset Tutorial Progress
- iconPathOn: reset
- iconPathOff: reset
- actionFunction:
payload.executeAction
The Delete menu item has the following properties:
- action: Delete UI Object
- actionProject: Visual-Scripting
- askConfirmation: true
- confirmationLabel: Confirm to Delete
- label: Delete
- iconPathOn: delete-entity
- iconPathOff: delete-entity
- actionFunction:
payload.executeAction
Tip: When a menu item is grayed out, it means that Tutorial already has the required child type that the menu item may add, and only that child is allowed for that case.
Tutorial Children
The Tutorial node has the following childrenNodesProperties:
The Tutorial Steps node property features the following properties:
- name:
tutorialSteps
- type: array
- childType: Tutorial Step
- autoAdd: false
The Tutorial Topics node property features the following properties:
- name:
tutorialTopics
- type: array
- childType: Tutorial Topic
- autoAdd: false