Since 5.0
This component isn't included into the library package and should be taken from https://github.com/webix-hub/hint-component
Webix Hint is a view-based component for rendering hints for users. The purpose of the widget is to guide new users through a website or app. This component can be especially useful in case of complex contents and multiple controls.
It's quite simple to create Hint:
webix.ui({
view: "hint",
id: "hint",
steps: [
{
el: ".div1",
title: "Welcome to Booking App!",
text: "Click here to check out regular flights",
event:"click"
},
{
el: ".div2",
title: "Get Flights Info in a Click!",
text: "Click here to take a look at all flights info",
event:"click"
},
{
el: "$accordionitem1",
eventEl: "button",
title: "Book Flight Tickets",
text: "Fill in the form and press 'enter' to book your flight",
event:"enter"
}
]
});
$$("hint").start();
Related sample: Hint initialization
Each step has a compulsory el property and can have a number of optional properties.
The relations between el and eventEl properties are shown in the following example. Imagine that on one of the Hint steps you want to highlight a form, while a user will interact only with a specific control on it. Then the form should be set as the el and the control element - as the eventEl of the step.
Related sample: Hint basic usage
By default, each hint has two buttons for navigating between interface elements' descriptions, namely, moving back and forth between hints. The config of these buttons is set via the related attributes:
nextButton - (boolean/string) defines, whether the Next button will be displayed (boolean) or sets a label for it (string). By default, the property is set to true. The default label for the last step is "End Tour", while the default label for the other steps is "Next".
prevButton - (boolean/string) defines, whether the Previous button will be displayed (boolean) or sets a label for it (string). By default, the property is set to true. The default label is "Previous".
webix.ui({
view: "hint",
id: "hint",
steps: [
{
el: ".div1",
title: "Welcome to Booking App!",
text: "Click here to check out regular flights",
event:"click"
},
{
el: ".div2",
title: "Get Flights Info in a Click!",
text: "Click here to take a look at all flights info",
event:"click"
}
],
nextButton: "Show next", // the new caption of the button
prevButton: false // the "Previous" button won't be rendered
});
The first step of Hint has only the Next button displayed.
As Hint is created on the base of webix.view, it inherits some of its methods.
Thus, to display Hint on a page, use the show method.
$$("hint").show();
In case you need to hide Hint, apply the hide method.
$$("hint").hide();
The Hint API provides the start method that allows you to:
$$("hint").start();
It is also possible to terminate showing hints at any step via the end method:
$$("hint").end();
You can get the list of current Hint steps via the getSteps method. It returns an array of step objects.
var steps = $$("hint").getSteps();
The setSteps method lets you to set your own steps for the Hint widget. You need to pass an array of objects as a parameter.
For example, the code below will define one step of a hint:
$$("hint").setSteps(
[
{
el: ".div1",
title: "Welcome to Booking App!",
text: "Click here to check out regular flights. Click the tab to proceed",
event:"click"
}
]
);
You can get the number of the current step of Hint with the help of the getCurrentStep method:
var step = $$("hint").getCurrentStep();
Note that the count of Hint steps starts from 1.
Webix Hint API allows you to resume displaying of hints from any step. You just need to pass the number of the necessary step to the resume method.
webix.ui({
view: "hint",
id: "hint",
on: {
onEnd: function(step) {
$$("hint").resume(2); // resume from the second step
}
},
steps:[
{
el: ".div1",
title: "Welcome to Booking App!",
text: "Click here to check out regular flights",
event:"click"
},
{
el: ".div2",
title: "Get Flights Info in a Click!",
text: "Click here to take a look at all flights info",
event:"click"
}
]
});
You can also omit the parameter to resume hints showing from the very first step.
In case you need to load a part of a large dataset or go to a different page on the next hint step, it can be useful to return a promise of data, to avoid errors if the necessary chunk of data hasn't been loaded yet.
For instance, let's suppose we have a datatable with a pager and a hint widget, which has a step that needs to trigger loading of the next page of the datatable:
{
el: "masterPager1",
eventEl: "button",
title: "Datatable can be used with a pager",
text: "Please click the second button to open page number two",
padding: 10,
event: "click",
next: function() {
return $$("mytable").waitData;
}
}
As you can see, we have set the next property in the step configuration. It specifies a function that returns a promise for the next part of the data from the datatable. So when a user clicks the second button of the pager, the second page of the datatable is displayed.
If you want to trigger some actions on return to the previous step, make use of the previous property.
As Hint is also based on webix.EventSystem, you can make use of the on property to attach handlers to its events.
Imagine that you want to create a looped sequence of hints, i.e. after a user views the last hint (onEnd), the whole sequence starts from the beginning, unless the user exits the hint.
For this purpose, you are to call the resume method without a parameter:
webix.ui({
view: "hint",
id: "hint",
on: {
onEnd: function(step) {
$$("mytable").getPager().select(0);
$$("hint").resume();
}
},
steps:[
{
el: ".div1",
title: "Welcome to Booking App!",
text: "Click here to check out regular flights",
event:"click"
},
{
el: ".div2",
title: "Get Flights Info in a Click!",
text: "Click here to take a look at all flights info",
event:"click"
}
]
});
Related sample: Hint basic usage
In the code above, we have set the onEnd event. The event will fire after the user views the last hint, and its handler takes the number of the step as a parameter. Inside of the handler function we have specified that when we come to the end of the hint, we return to the first page of the datatable and resume the hint from the start.
Here is the list of events that you can make use of:
Webix Hint can be localized according to the rules of a particular language. You can localize the names of Hint buttons.
The /codebase/i18n
folder contains locales for 10 main languages, English is set by default.
A locale for the Hint widget contains a set of local names for the "Next", "Previous" and "End Tour" buttons:
webix.i18n.hint = {
next: "Next",
prev: "Previous",
last: "End Tour"
}
To apply a new language for the buttons names, you should call the setLocale method. The locale name is specified as a parameter of the method:
webix.i18n.setLocale("be-BY");
Back to top