Creating instructions

To create an instruction, go to the authoring tab and click the plus icon on the row of the guide you like to record. Added instructions will be added to the end of the list of instructions of that guide.

Modifying instructions

Find the instruction in the group tree list and click the edit icon next to it. For visible callouts it is possible to open the edit form directly by clicking the edit icon.

Ordering instructions

To change the order of instructions simply move the mouse over an instruction until you see the movement cursor. You can now use drag and drop to move the instruction up or down in the list.

Record Mode

By clicking Record instead of Add you go into Record Mode. In this mode you can continue to record while moving through the process.

Selection is done just like described below but the instruction will be created automatically and you will be able to continue making selection.

To leave Record Mode simply press esc.

Selecting targets

When adding an instruction, the author is automatically in target selection mode. Press ctrl+click or ctrl+space to submit your selection.

There are two ways of pointing out targets.

Supported targets (green)

The preferred method of selecting target elements is by using one of the built-in and supported green targets. The supported targets identification is carefully considered and maintained as part of the product. Supported targets are quality assured, cleaned off version specifics and html detail so that only a minimum required to identify the element is recorded with the instruction data. The complex and potential changing part is maintained in the configuration as part of the product.

Fall back - XPATH based targets (yellow)

To provide flexibility there is also a fall-back target recording method using xpath. You could see xpath as more of a direct map through the html elements to your target element. Using the flexibility of xpath you can record anything you want but you will also tie your instruction closer to the html and it will be more sensitive to change. More html version specifics will end up in the recorded data. We support this recording method but not the specific targets. Built in with the product is a set of ignored classes attributes etc to generate a good xpath starting point that is likely to work well as a start.

Colored rectangle

During selection a colored rectangle will appear to indicate:

• The element that is targeted for selection

• The status of the selection

Highlight all supported (green) targets

All supported (green) select targets can be highlighted by pressing ctrl + alt

Submitting your selection

To complete selection hold control key and left click mouse (ctrl + click) or press space (ctrl + space). Control + space is useful in cases when the target platform reacts to mouse click and prevents recording.

Re-selecting target elements

To re-select the target element, click the ‘SELECT TARGET’ button below the ‘Target element’ label found at the top of the instruction form.

Advanced innerText controls

To use advanced innerText controls, select a supported target element that is using innerText, then open the target details form and you will be able to change the behaviour of innerText evaluation. If the target element innerText should be equal, contain, startWith or endWith the chosen text.

Callout positioning (anchors)

A callout positioning choice could be done during selection by clicking one of the anchor points (grey small circles) at the edge of the rectangle. For some targets, such has really small ones, the anchor points on target selection are disabled by the administrator.

Callout positioning (panel form)

A callout is possible to position in a number of ways. To select the position, use the drop down. Default position is bottom.

Note that the anchor point could be assigned during target selection (see ‘Selecting Target Elements’).

Multi-Language Input

Author language

The Author Language option allows the author to choose a language in which the title and description of the instruction form will be saved.

Based on the selected language, the title and description will be stored against that language.

By changing the author language, the author can save the title and description in multiple supported languages.

Advanced positioning settings

Direction

By default the direction will be the same as the anchor but if the Author wants the direction can be changed.

Parent Offset

With parent offset the Author can select a target (e.g. an input field) but move up in the elements hierarchy to the container or another parent element.

Horizontal / Vertical Offset

A callout can also be re-positioned from its anchor position with horizontal and vertical offset (+/- in pixels).

Layer index

If you need to adjust the callouts z-index (element depth) position then the layer index can be used to e.g. put the callout behind a modal.

Preview instructions

While creating or modifying instruction an instant preview is made available. The preview instantly reacts and displays changes in text just as the consumer would see it.

Resizing callouts

Direct in the preview of the callout you have the possibility to resize it to fit you application or use.

To reset click on the reset-button in the bottom of the callout.

Instruction text

Instructions has two fields. The title renders in bold and the description renders as paragraph and is suitable for longer texts.
The description field features a rich text editor which allows you to apply basic formatting with font size, bold, italic, underline, lists, links, images and embedded videos.

Links

To add a link to an instruction simply enter the link text and then click on the link icon in the editor to add the URL.

Images

Images can be added by clicking on the image icon in the editor. Paste an url to an image and it will show up in the instruction.

Videos

Embedded videos can be added by clicking on the video icon in the editor. Paste an url to a video and it will show up in the instruction as an embedded video player (supported platforms are youtube, vimeo and dailymotion) or a link to the video.

Interactivity

Linked guides

Under “Interactivity” you can add linked guides to an instruction.
This will show up as a button in the bottom part of the callout.

Toggle off current guide

If you toggle on “Toggle off current guide” clicking the button will toggle off the current guide and toggle on the linked guide.

If you don’t toggle on “Toggle off current guide” clicking the button will only toggle the linked guide.

Customizing action buttons

Some instructions like those part of a Tour-guide will have action buttons (Prev, Next, Reset & Finish). These labels can be customized under the Interactivity section.

Simply select the button you wish to customize and change the label.

Apart from the automatically added actions (Prev, Next, Reset & Finish) you can also if you choose add a Close or Dismiss button to the instruction. This can be useful if you for example in case of the instruction being part of a sequence (read below about sequenced guides) want the user to close the instruction manually.

Controlling when instructions are shown

There are various ways to control when an instruction should show.

Contexts

To control when an instruction is shown, it is tied with application state. This is achieved by selecting among a set of built-in contexts valid for the current view.

Hovering a context in the list will highlight the element in the current view that the context is tied to.

Highlight all contexts

If you toggle “Highlight all contexts by de

fault” in the extension preferences all visible contexts will be highlighted in the UI.

• Green: Toggled contexts

• Red: Untoggled contexts

• Grey: Negated contexts

Multiple contexts

For cases when you want the instruction to be shown in multiple contexts you can click on the menu and add another context. The shared contexts will remain in Shared Context while every context that differ will end up in a context group.

For an instruction to be shown all shared contexts and one context group needs to be valid.

Negated contexts

A context can also be negated. This is done by simply clicking on the toggle again. The behaviour will then be the opposite of having the context toggled on.

Parent Contexts

Parent contexts are used to improve performance and limit (scope) the evaluation of all contexts to only evaluate those that have a possibility to be present.

To toggle some contexts the author needs to first toggle the parent context.

E.g. 3DDashboard widgets should only be evaluated in 3DDashboard and not 3DSpace.

Inside of

There are cases when the target element selection is ambiguous and generates multiple hits in the UI. In such cases you can use “Show inside of” to limit the context.

You can select multiple “Show inside of“ and in that case the callout will be rendered in the first available condition container.

Target state

Some target elements could have a state itself. Such elements can be configured with a target state that controls instruction visibility.

Sequence trigger

If a guide is auto sequenced sequence triggers can be used to progress the guide when the user clicks, hovers, focuses or blurs the target.

It's also possible to add sequence triggers to custom contexts if you don't want to use the target as a sequence trigger.

Input conditions & validation

Targeting input fields will always present the option to control state. e.g. text field, textarea, checkbox, radio button, select (dropdown), file upload. etc. will all present a state option to the author.

For text fields and textareas the author can use a set of different operators to control if the instruction should show or not. For all except Larger Than and Smaller Than multiple values can be set.

Popup context

If you have placed an instruction in a popup window you get the option to add the opener window contexts to control visibility of the instruction.

This is useful since the popup itself usually lack information about the state of the app and with the popup context you can tie the instruction to the state of the app when opening the popup.

Manually selected Context elements (Sequencing by state)

If the built-in standard contexts are not enough to control visibility of an instruction, one or more context elements could be used. Target states also apply to manually selected context elements and using it in combination is a powerful way to control sequential flow. Multiple context elements could be used in combination so that all conditions have to be met for the callout instruction to display.

Custom context mode

For custom contexts you can choose if you want the mode to be OR (Only one custom context needs to be valid for the instruction to be visible) or AND (All contexts must be valid for the instruction to be visible)

Sequencing (Fall-back)

Display one instruction after another with help of making instructions directly dependent on each other. Select the instruction you want to make a dependency to in the dropdowns. In the case multiple instructions are used as display after / before only one have to be shown to fulfil the requirement. The instruction sequence can be followed multiple times by specifying when the sequence should reset.

Instruction Type

You can change type of the instruction under “Options”.

Types

• Callout: Renders the default callout popover pointing to the selected element.

• Info: Renders the instructions more compact. Then the user will have to actively click the small info symbol to render the full callout.
  Optional: Under “Display Settings” there are additional settings for the Info type:

  • Open on hover: You can toggle “Open on hover” to have the full callout rendered when hovering the instruction instead on having to click.

  • Pulsating icon (enabled by default): If toggled off the info symbol will be static and not animate.

  • Icon type (Info by default): You can select between multiple different icon types e.g. question mark, warning, arrows etc.

• Global Info: Renders a global info overlay on top or bottom of the page (not pointing to a specific element).

• Highlight: Renders a more discrete highlight over the element. Then the user will have to actively hover the element to render the full callout.
  Optional: Under “Display Settings” there are additional settings for the Highlight type:

  • Only show highlight: This will only show the highlight and not render the full callout on hover.

  • Highlight type: You can select between multiple highlight types e.g. discrete, border, shadow).

• Target Blocker: This instruction type blocks the user from clicking the target as long as the contexts for the instructions are valid.
  This is useful if e.g. you want the user to fill in a form in a certain way before submitting. Combining custom contexts for all needed form fields with the OR mode will show the target blocker as long as any of the custom contexts are valid.
  Optional: Under “Display Settings” there are additional settings for Target Blocker type:

  • Mode: Invisible: Blocks the target without rendering anything over it.

  • Mode: Overlay: Renders an overlay similar to Highlight type.

  • Only block element: Will only render the blocker over the target and no callout.

Guide recommendations

If an instruction has “Display when guide disabled” toggled on the instruction will be shown if app is in the correct context but the guide is toggled off.

This can be useful to recommend the user to use a guide when they are in a specific context but might be unaware there are guides explaining the process.

When the guide is toggled on instructions with “Display when guide disabled” will be hidden.

View only once

If this is toggled the instruction will only be visible one time as long as that guide is active. If the user toggles the guide on and of again it will reset the visibility.

Move to another guide

You can change which guide an instruction should belong to.

Validation

To ensure proper data some validation is applied to the instruction create / edit form.

• At least 1 context is needed otherwise a warning is displayed

• Title is mandatory

• If used recorded XPATH have to be valid (details found when expanding target element)

Instruction Image

When an instruction is created, a screenshot of the page is captured by default.

• Image can be cropped using the crop action icon.

• Image can be regenerated by the image icon.

• Image can be removed using the cross icon.

Re-capture screenshots

To quickly re-capture screenshots enter the “Re-capture screenshots” mode by clicking on the three dots … next to the guide.

In this mode you can move through the guide quickly and take new screenshots.

Controls:

• Click ctrl+space to take a screenshot.

• Move between instruction with ctrl+-> and ctrl+<-

• Exit by clicking Esc

The status bar will show the status of the re-capture, how many instructions are pending, captured and failed.