TsgcHTMLComponent_Tour: een begeleide producttour voor onboarding. Hij licht de elementen van de pagina stap voor stap uit met een spotlight en een kaart, start vanzelf bij het eerste bezoek, vanaf een knop of vanaf de server, en meldt de voortgang van elke gebruiker via serverevents, in Delphi, C++ Builder en .NET.
Voeg de Stappen toe, wijs elke stap naar een element, en stel AutoStart in of voeg een startknop toe. OnStepChange, OnSkip en OnComplete vertellen de server hoe ver elke gebruiker kwam.
TsgcHTMLComponent_Tour, met één TsgcHTMLTourStep per stap in Stappen
Een verborgen element met de configuratie als JSON en het tourscript, met ingebedde stijlen, zonder externe bestanden en zonder CDN
Delphi, C++ Builder, .NET
Met AutoStart start de tour vanzelf de eerste keer dat een browser de pagina opent, en de startknop speelt hem op elk moment opnieuw af. Als een HTMXEngine is toegewezen, verstuurt de browser de events waarvoor een handler bestaat.
uses
sgcHTML_Session, sgcHTML_Component_Tour;
// Eenmalig gemaakt: het beantwoordt zijn serverevents nadat de pagina is gerenderd
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'; // geen doel: een gecentreerde kaart
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; // de sessie van dit verzoek
if oSession <> nil then
SaveOnboardingDone(oSession.UserID); // je eigen 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;@* De inhoud van elke stap is de HTML van zijn kaart *@
<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);
}Een eerste keer gebruiken die nieuwe gebruikers laat zien wat waar staat, en een registratie op je server van hoe ver elk kwam.
Elke stap licht een element uit met een spotlight-uitsparing in een gedimde achtergrond en toont ernaast een kaart met titel, HTML-inhoud, een optionele afbeelding, een stapteller met voortgangspunten en de knoppen Terug, Volgende, Rondleiding overslaan en Klaar. Een stap zonder doel toont de kaart gecentreerd op de pagina.
Vanzelf bij het eerste bezoek (AutoStart), vanaf een knop (GetStartButtonHTML, of data-sgc-tour-start op elk element), vanuit je eigen script (GetStartScript) of vanaf de server voor één gebruiker (GetStartHTML).
Klaar of Rondleiding overslaan wordt opgeslagen in de localStorage van de browser onder StorageKey, standaard sgc-tour:<Name>, en AutoStart start de tour daar niet opnieuw. Wijzig StorageKey om iedereen een herziene tour te tonen.
Een stap waarvan het doel ontbreekt of verborgen is, bijvoorbeeld een paneel van een rol die de gebruiker niet heeft, wordt in beide richtingen overgeslagen, en de teller telt alleen de stappen die getoond kunnen worden. De kaart blijft binnen de viewport en op smalle schermen valt hij terug op onder, boven of gecentreerd.
De kaart is een dialoog die naar zijn titel is genoemd. De focus gaat naar Volgende wanneer een stap verschijnt en keert terug naar waar hij was wanneer de tour eindigt, en in een modale kaart loopt Tab rond over de knoppen. De pijltoetsen wisselen tussen de stappen, Esc verlaat de tour, en een beleefd live-gebied kondigt "Stap n van m: titel" aan.
De knoppen en de staptekst zijn er in de 17 talen van de bibliotheek. Pagina's van rechts naar links spiegelen de plaatsing en de pijltoetsen, en de kaart neemt het data-bs-theme van de pagina over, dus hij volgt een donker thema. De stijlen worden toegevoegd wanneer de tour start en verwijderd wanneer hij eindigt.
De leden die je het vaakst gebruikt.
Elke stap heeft een Doel (een CSS-selector, de eerste treffer) of een TargetComponent, een Title in gewone tekst, Content in HTML opgeschoond met sgcHTMLSanitizeHTML, een Image-URL die door sgcHTMLSanitizeURL gaat, een Placement, een eigen ShowBackdrop en ScrollIntoView.
ShowBackdrop, ShowProgress en ShowSkip zetten de achtergrond, de teller met de punten en de knop Rondleiding overslaan aan of uit. Padding (standaard 6) is de ruimte in pixels rond het doel, AllowKeyboard schakelt Esc en de pijltoetsen in, en CloseOnBackdropClick verlaat de tour bij een klik op de achtergrond.
OnStepChange wordt geactiveerd telkens als een stap wordt getoond, OnSkip wanneer de gebruiker vóór het einde vertrekt, met de index van de stap, en OnComplete wanneer de gebruiker in de laatste stap op Klaar drukt. De browser verstuurt alleen de events waarvoor een handler bestaat, en een stapindex buiten Stappen wordt geweigerd.
De handler draait op de thread van het verzoek, waar sgcHTMLRequestSession de sessie en de gebruiker geeft. De HTML die hij in aResponse teruggeeft, wordt door htmx ingewisseld wanneer de elementen zijn gemarkeerd met hx-swap-oob="true".
Wijs HTMXEngine toe, of stel ActionURL in en roep DispatchComponentEvent('tour', Params, Response) aan vanuit je eigen route. Zonder een van beide draait de tour in de browser en verstuurt hij niets. Met htmx op de pagina verstuurt hij via htmx.ajax, anders via XMLHttpRequest met de CSRF-metatags van de pagina.
GetStartHTML geeft een fragment terug dat de tour start in de browser die het ontvangt, als htmx-antwoord of als push naar één verbinding. De startknop, GetStartScript en GetStartHTML negeren het in de browser opgeslagen item.
window.sgcHTMLTour biedt start(id[, step]), next, back, end, reset en active. Elke functie neemt de id van de tour, de waarde van GetElementIdentifier. reset verwijdert het opgeslagen item, zodat AutoStart de tour opnieuw uitvoert.
In een Razor-view rendert de Tag Helper <sgc-tour name="..."> de tour, met één <sgc-tour-step>-kind per stap waarvan de inhoud de HTML van de kaart is. De eerste render maakt één component per engine en naam, geregistreerd bij de engine van AddSgcHtml, zodat het zijn serverevents beantwoordt nadat de pagina is gerenderd.
Demos\60.HTML\01.RunTime\29.Tour is de sgc Cloud Console op poort 8131: een tour voor het eerste gebruik van acht stappen met een spotlight, een tweede tour Wat is nieuw op dezelfde pagina, tooltips op de werkbalkknoppen, statistiekkaarten en formuliervelden, en een onboardingtrechter die de server per gebruiker vastlegt. De designtime-, Lazarus- en .NET-versies spiegelen het.
| Online proberenBekijk het in de demo Rondleiding en tooltips, live draaiend op de eSeGeCe-demoserver. | Openen | |
| Online helpVolledige API-referentie en gebruikshandleiding voor dit component. | Openen | |
| Tooltip-componentHints op knoppen en velden, in dezelfde demo samen met de tour getoond. | Openen | |
| Alle sgcHTML-componentenBlader door de volledige functiematrix van 80+ componenten. | Openen | |
| Download gratis proefversieDe proefversie van 30 dagen bevat de 60.HTML-demoprojecten. | Openen | |
| PrijzenSingle-, Team- en Site-licenties met volledige broncode. | Openen |