TsgcHTMLComponent_Tour: un tour guidato del prodotto per l'onboarding. Evidenzia gli elementi della pagina un passo alla volta con uno spotlight e una scheda, parte da solo alla prima visita, da un pulsante o dal server, e riporta l'avanzamento di ogni utente tramite eventi server, in Delphi, C++ Builder e .NET.
Aggiungi gli Steps, punta ciascuno a un elemento e imposta AutoStart oppure aggiungi un pulsante di avvio. OnStepChange, OnSkip e OnComplete dicono al server fin dove è arrivato ogni utente.
TsgcHTMLComponent_Tour, con un TsgcHTMLTourStep per passo in Steps
Un elemento nascosto con la configurazione come JSON e lo script del tour, con i suoi stili incorporati, senza file esterni e senza CDN
Delphi, C++ Builder, .NET
Con AutoStart il tour parte da solo la prima volta che un browser apre la pagina, e il pulsante di avvio lo riproduce in qualsiasi momento. Con un HTMXEngine assegnato, il browser invia gli eventi che hanno un gestore.
uses
sgcHTML_Session, sgcHTML_Component_Tour;
// Creato una sola volta: risponde ai suoi eventi server dopo che la pagina è stata renderizzata
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'; // nessuna destinazione: una scheda centrata
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; // la sessione di questa richiesta
if oSession <> nil then
SaveOnboardingDone(oSession.UserID); // il tuo codice
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;@* Il contenuto di ogni passo è l'HTML della sua scheda *@
<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);
}Un primo avvio che mostra ai nuovi utenti cosa c'è e dove, e un registro sul tuo server di fin dove è arrivato ciascuno.
Ogni passo evidenzia un elemento con un ritaglio spotlight in uno sfondo attenuato e mostra accanto una scheda con un titolo, contenuto HTML, un'immagine facoltativa, un contatore dei passi con punti di avanzamento e i pulsanti Indietro, Avanti, Salta il tour e Fine. Un passo senza destinazione mostra la scheda centrata nella pagina.
Da solo alla prima visita (AutoStart), da un pulsante (GetStartButtonHTML, o data-sgc-tour-start su qualsiasi elemento), dal tuo script (GetStartScript) o dal server per un utente (GetStartHTML).
Fine o Salta il tour viene memorizzato nel localStorage del browser sotto StorageKey, di default sgc-tour:<Name>, e AutoStart non fa ripartire il tour lì. Cambia StorageKey per mostrare a tutti un tour rivisto.
Un passo la cui destinazione manca o è nascosta, per esempio un pannello di un ruolo che l'utente non ha, viene saltato in entrambe le direzioni, e il contatore conta solo i passi che possono essere mostrati. La scheda resta dentro il viewport e, sugli schermi stretti, passa a sotto, sopra o centrata.
La scheda è una finestra di dialogo il cui nome è il suo titolo. Il focus si sposta su Avanti quando un passo viene mostrato e torna dov'era quando il tour termina, e in una scheda modale Tab scorre ciclicamente i suoi pulsanti. I tasti freccia si spostano tra i passi, Esc esce, e una regione live cortese annuncia "Passo n di m: titolo".
I pulsanti e il testo dei passi sono disponibili nelle 17 lingue della libreria. Le pagine da destra a sinistra specchiano il posizionamento e i tasti freccia, e la scheda copia il data-bs-theme della pagina, quindi segue un tema scuro. Gli stili vengono aggiunti quando il tour parte e rimossi quando termina.
I membri che usi più spesso.
Ogni passo ha un Target (un selettore CSS, la sua prima corrispondenza) o un TargetComponent, un Title in testo semplice, Content in HTML sanificato con sgcHTMLSanitizeHTML, un URL Image che passa per sgcHTMLSanitizeURL, un Placement, il proprio ShowBackdrop e ScrollIntoView.
ShowBackdrop, ShowProgress e ShowSkip attivano o disattivano lo sfondo, il contatore con i punti e il pulsante Salta il tour. Padding (6 di default) è lo spazio in pixel attorno alla destinazione, AllowKeyboard abilita Esc e i tasti freccia, e CloseOnBackdropClick esce dal tour con un clic sullo sfondo.
OnStepChange scatta ogni volta che un passo viene mostrato, OnSkip quando l'utente esce prima della fine, con l'indice del passo, e OnComplete quando l'utente preme Fine sull'ultimo passo. Il browser invia solo gli eventi che hanno un gestore, e un indice di passo fuori da Steps viene rifiutato.
Il gestore viene eseguito sul thread della richiesta, dove sgcHTMLRequestSession fornisce la sessione e l'utente. L'HTML che restituisce in aResponse viene sostituito da htmx quando i suoi elementi sono marcati con hx-swap-oob="true".
Assegna HTMXEngine, oppure imposta ActionURL e chiama DispatchComponentEvent('tour', Params, Response) dalla tua route. Senza nessuno dei due, il tour gira nel browser e non invia nulla. Con htmx nella pagina invia tramite htmx.ajax, altrimenti tramite XMLHttpRequest con i meta tag CSRF della pagina.
GetStartHTML restituisce un frammento che avvia il tour nel browser che lo riceve, come risposta htmx o come push a una connessione. Il pulsante di avvio, GetStartScript e GetStartHTML ignorano la voce memorizzata nel browser.
window.sgcHTMLTour offre start(id[, step]), next, back, end, reset e active. Ogni funzione accetta l'id del tour, il valore di GetElementIdentifier. reset rimuove la voce memorizzata, così AutoStart esegue di nuovo il tour.
In una vista Razor, il Tag Helper <sgc-tour name="..."> renderizza il tour, con un figlio <sgc-tour-step> per passo il cui contenuto è l'HTML della scheda. Il primo rendering crea un componente per motore e nome, registrato nel motore di AddSgcHtml, quindi risponde ai suoi eventi server dopo che la pagina è stata renderizzata.
Demos\60.HTML\01.RunTime\29.Tour è la sgc Cloud Console sulla porta 8131: un tour di primo avvio in otto passi con spotlight, un secondo tour delle novità nella stessa pagina, tooltip sui pulsanti della barra degli strumenti, schede statistiche e campi dei moduli, e un funnel di onboarding che il server registra per utente. Le versioni design time, Lazarus e .NET lo replicano.
| Provalo onlineGuardalo nella demo Tour e tooltip, in esecuzione dal vivo sul server demo di eSeGeCe. | Apri | |
| Guida in lineaRiferimento API completo e guida all'uso di questo componente. | Apri | |
| Componente TooltipSuggerimenti su pulsanti e campi, mostrati con il tour nella stessa demo. | Apri | |
| Tutti i componenti sgcHTMLEsplora la matrice completa delle funzionalità di oltre 80 componenti. | Apri | |
| Scarica la Prova GratuitaLa prova di 30 giorni include i progetti demo 60.HTML. | Apri | |
| PrezziLicenze Single, Team e Site con codice sorgente completo. | Apri |