TsgcHTMLComponent_Tour: a guided product tour for onboarding. It highlights the elements of the page one step at a time with a spotlight and a card, starts by itself on the first visit, from a button or from the server, and reports the progress of each user through server events, in Delphi, C++ Builder and .NET.
Add the Steps, point each one at an element, and set AutoStart or add a start button. OnStepChange, OnSkip and OnComplete tell the server how far each user got.
TsgcHTMLComponent_Tour, with one TsgcHTMLTourStep per step in Steps
A hidden element with the configuration as JSON and the tour script, with its styles embedded, no external files and no CDN
Delphi, C++ Builder, .NET
With AutoStart the tour starts by itself the first time a browser opens the page, and the start button replays it at any time. With an HTMXEngine assigned, the browser posts the events that have a handler.
uses
sgcHTML_Session, sgcHTML_Component_Tour;
// Created once: it answers its server events after the page was rendered
oTour := TsgcHTMLComponent_Tour.Create(Self);
oTour.Name := 'onboarding';
oTour.AutoStart := True;
oTour.HTMXEngine := HTMXEngine1;
oTour.OnComplete := TourComplete;
oTour.OnSkip := TourSkip;
with oTour.Steps.Add do
begin
Title := 'Welcome'; // no target: a centered card
Content := '<p>Take a minute to see what is where.</p>';
end;
with oTour.Steps.Add do
begin
Target := '#sidebar';
Title := 'Navigation';
Content := '<p>Every module of the app is here.</p>';
Placement := trpRight;
end;
sHtml := oTour.HTML + oTour.GetStartButtonHTML('Restart tour');
procedure TForm1.TourComplete(Sender: TObject; var aResponse: string);
var
oSession: TsgcHTMLSession;
begin
oSession := sgcHTMLRequestSession; // the session of this request
if oSession <> nil then
SaveOnboardingDone(oSession.UserID); // your own code
end;
procedure TForm1.TourSkip(Sender: TObject; aStep: Integer; var aResponse: string);
var
oSession: TsgcHTMLSession;
begin
oSession := sgcHTMLRequestSession;
if oSession <> nil then
SaveOnboardingSkipped(oSession.UserID, aStep);
end;@* The content of each step is the HTML of its card *@
<sgc-tour name="onboarding" auto-start="true" on-complete="Model.TourDone" on-skip="Model.TourSkipped">
<sgc-tour-step title="Welcome"><p>Take a minute to see what is where.</p></sgc-tour-step>
<sgc-tour-step target="#sidebar" title="Navigation" placement="right">
<p>Every module of the app is here.</p>
</sgc-tour-step>
<sgc-tour-step target="#btnSettings" title="Settings" image="/img/settings.png">
<p>Change the theme and your profile here.</p>
</sgc-tour-step>
</sgc-tour>using esegece.sgcWebSockets;
var tour = new TsgcHTMLComponent_Tour { Name = "onboarding" };
tour.AutoStart = true;
tour.HTMXEngine = htmxEngine;
tour.OnComplete += TourDone;
tour.OnSkip += TourSkipped;
var step = tour.Steps.Add();
step.Title = "Welcome";
step.Content = "<p>Take a minute to see what is where.</p>";
step = tour.Steps.Add();
step.Target = "#sidebar";
step.Title = "Navigation";
step.Content = "<p>Every module of the app is here.</p>";
step.Placement = TsgcHTMLTourPlacement.trpRight;
string html = tour.HTML + tour.GetStartButtonHTML("Restart tour");
public void TourDone(object sender, ref string response)
{
SaveOnboardingDone(User.Identity?.Name);
}
public void TourSkipped(object sender, int step, ref string response)
{
SaveOnboardingSkipped(User.Identity?.Name, step);
}A first run that shows new users what is where, and a record on your server of how far each one got.
Each step highlights an element with a spotlight cutout in a dimmed backdrop and shows a card next to it with a title, HTML content, an optional image, a step counter with progress dots and the Back, Next, Skip tour and Done buttons. A step without a target shows the card centered on the page.
By itself on the first visit (AutoStart), from a button (GetStartButtonHTML, or data-sgc-tour-start on any element), from your own script (GetStartScript) or from the server for one user (GetStartHTML).
Done or Skip tour is stored in the localStorage of the browser under StorageKey, sgc-tour:<Name> by default, and AutoStart does not start the tour again there. Change StorageKey to show a revised tour to everyone.
A step whose target is missing or hidden, for instance a panel of a role the user does not have, is skipped in both directions, and the counter counts only the steps that can be shown. The card stays inside the viewport, and on narrow screens it falls back to bottom, top or centered.
The card is a dialog named by its title. The focus moves onto Next when a step shows and returns where it was when the tour ends, and in a modal card Tab wraps around its buttons. The arrow keys move between the steps, Esc leaves, and a polite live region announces "Step n of m: title".
The buttons and the step text come in the 17 languages of the library. Right to left pages mirror the placement and the arrow keys, and the card copies the data-bs-theme of the page, so it follows a dark theme. The styles are added when the tour starts and removed when it ends.
The members you reach for most often.
Each step has a Target (a CSS selector, its first match) or a TargetComponent, a Title in plain text, Content in HTML sanitized with sgcHTMLSanitizeHTML, an Image URL that passes through sgcHTMLSanitizeURL, a Placement, its own ShowBackdrop and ScrollIntoView.
ShowBackdrop, ShowProgress and ShowSkip turn the backdrop, the counter with the dots and the Skip tour button on or off. Padding (6 by default) is the space in pixels around the target, AllowKeyboard enables Esc and the arrow keys, and CloseOnBackdropClick leaves the tour on a click of the backdrop.
OnStepChange fires each time a step is shown, OnSkip when the user leaves before the end, with the index of the step, and OnComplete when the user presses Done on the last step. The browser posts only the events that have a handler, and a step index outside Steps is refused.
The handler runs on the thread of the request, where sgcHTMLRequestSession gives the session and the user. The HTML it returns in aResponse is swapped by htmx when its elements are marked hx-swap-oob="true".
Assign HTMXEngine, or set ActionURL and call DispatchComponentEvent('tour', Params, Response) from your own route. Without either, the tour runs in the browser and posts nothing. With htmx on the page it posts through htmx.ajax, otherwise through XMLHttpRequest with the CSRF meta tags of the page.
GetStartHTML returns a fragment that starts the tour in the browser that receives it, as an htmx response or a push to one connection. The start button, GetStartScript and GetStartHTML ignore the entry stored in the browser.
window.sgcHTMLTour offers start(id[, step]), next, back, end, reset and active. Every function takes the id of the tour, the value of GetElementIdentifier. reset removes the stored entry, so AutoStart runs the tour again.
In a Razor view, the <sgc-tour name="..."> Tag Helper renders the tour, with one <sgc-tour-step> child per step whose content is the HTML of the card. The first render creates one component per engine and name, registered with the engine of AddSgcHtml, so it answers its server events after the page was rendered.
Demos\60.HTML\01.RunTime\29.Tour is the sgc Cloud Console on port 8131: an eight step first-run tour with a spotlight, a second What's new tour on the same page, tooltips on the toolbar buttons, stat cards and form fields, and an onboarding funnel that the server records per user. The design time, Lazarus and .NET versions mirror it.
| Try It OnlineSee it in the Tour & Tooltips demo, running live on the eSeGeCe demo server. | Open | |
| Online HelpFull API reference and usage guide for this component. | Open | |
| Tooltip ComponentHints on buttons and fields, shown with the tour in the same demo. | Open | |
| All sgcHTML ComponentsBrowse the full feature matrix of 80+ components. | Open | |
| Download Free TrialThe 30-day trial ships the 60.HTML demo projects. | Open | |
| PricingSingle, Team and Site licenses with full source code. | Open |