TsgcHTMLComponent_Tour : une visite guidée du produit pour l'intégration des nouveaux utilisateurs. Elle met en évidence les éléments de la page étape par étape avec un projecteur et une carte, démarre d'elle-même à la première visite, depuis un bouton ou depuis le serveur, et signale la progression de chaque utilisateur par des événements serveur, en Delphi, C++ Builder et .NET.
Ajoutez les Steps, pointez chacune vers un élément, et définissez AutoStart ou ajoutez un bouton de démarrage. OnStepChange, OnSkip et OnComplete indiquent au serveur jusqu'où chaque utilisateur est allé.
TsgcHTMLComponent_Tour, avec un TsgcHTMLTourStep par étape dans Steps
Un élément masqué avec la configuration en JSON et le script de la visite, avec ses styles intégrés, sans fichiers externes et sans CDN
Delphi, C++ Builder, .NET
Avec AutoStart, la visite démarre d'elle-même la première fois qu'un navigateur ouvre la page, et le bouton de démarrage la rejoue à tout moment. Avec un HTMXEngine affecté, le navigateur envoie les événements qui ont un gestionnaire.
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);
}Un premier lancement qui montre aux nouveaux utilisateurs où se trouve chaque chose, et un enregistrement sur votre serveur de la progression de chacun.
Chaque étape met en évidence un élément avec une découpe de projecteur dans un fond estompé et affiche à côté une carte avec un titre, un contenu HTML, une image facultative, un compteur d'étapes avec des points de progression et les boutons Retour, Suivant, Passer la visite et Terminé. Une étape sans cible affiche la carte au centre de la page.
D'elle-même à la première visite (AutoStart), depuis un bouton (GetStartButtonHTML, ou data-sgc-tour-start sur n'importe quel élément), depuis votre propre script (GetStartScript) ou depuis le serveur pour un utilisateur (GetStartHTML).
Terminé ou Passer la visite est enregistré dans le localStorage du navigateur sous StorageKey, sgc-tour:<Name> par défaut, et AutoStart ne relance plus la visite à cet endroit. Modifiez StorageKey pour montrer une visite révisée à tout le monde.
Une étape dont la cible est absente ou masquée, par exemple un panneau d'un rôle que l'utilisateur n'a pas, est ignorée dans les deux sens, et le compteur ne compte que les étapes qui peuvent être affichées. La carte reste dans la fenêtre d'affichage, et sur les écrans étroits elle se replace en bas, en haut ou au centre.
La carte est une boîte de dialogue nommée par son titre. Le focus passe sur Suivant lorsqu'une étape s'affiche et revient où il était à la fin de la visite, et dans une carte modale Tab boucle sur ses boutons. Les touches fléchées passent d'une étape à l'autre, Échap quitte, et une région live polie annonce « Étape n sur m : titre ».
Les boutons et le texte des étapes existent dans les 17 langues de la bibliothèque. Les pages de droite à gauche inversent le placement et les touches fléchées, et la carte copie le data-bs-theme de la page, de sorte qu'elle suit un thème sombre. Les styles sont ajoutés au démarrage de la visite et retirés à sa fin.
Les membres que vous utiliserez le plus souvent.
Chaque étape a une Target (un sélecteur CSS, sa première correspondance) ou un TargetComponent, un Title en texte brut, un Content en HTML assaini avec sgcHTMLSanitizeHTML, une URL Image qui passe par sgcHTMLSanitizeURL, un Placement, ses propres ShowBackdrop et ScrollIntoView.
ShowBackdrop, ShowProgress et ShowSkip activent ou désactivent le fond, le compteur avec les points et le bouton Passer la visite. Padding (6 par défaut) est l'espace en pixels autour de la cible, AllowKeyboard active Échap et les touches fléchées, et CloseOnBackdropClick quitte la visite au clic sur le fond.
OnStepChange se déclenche à chaque affichage d'une étape, OnSkip lorsque l'utilisateur part avant la fin, avec l'index de l'étape, et OnComplete lorsque l'utilisateur appuie sur Terminé à la dernière étape. Le navigateur n'envoie que les événements qui ont un gestionnaire, et un index d'étape hors de Steps est refusé.
Le gestionnaire s'exécute sur le thread de la requête, où sgcHTMLRequestSession donne la session et l'utilisateur. Le HTML qu'il renvoie dans aResponse est inséré par htmx lorsque ses éléments sont marqués hx-swap-oob="true".
Affectez HTMXEngine, ou définissez ActionURL et appelez DispatchComponentEvent('tour', Params, Response) depuis votre propre route. Sans l'un ni l'autre, la visite s'exécute dans le navigateur et n'envoie rien. Avec htmx sur la page, elle envoie via htmx.ajax, sinon via XMLHttpRequest avec les balises meta CSRF de la page.
GetStartHTML renvoie un fragment qui démarre la visite dans le navigateur qui le reçoit, comme réponse htmx ou comme envoi vers une connexion. Le bouton de démarrage, GetStartScript et GetStartHTML ignorent l'entrée enregistrée dans le navigateur.
window.sgcHTMLTour propose start(id[, step]), next, back, end, reset et active. Chaque fonction prend l'id de la visite, la valeur de GetElementIdentifier. reset supprime l'entrée enregistrée, de sorte que AutoStart relance la visite.
Dans une vue Razor, le Tag Helper <sgc-tour name="..."> rend la visite, avec un enfant <sgc-tour-step> par étape dont le contenu est le HTML de la carte. Le premier rendu crée un composant par moteur et par nom, enregistré auprès du moteur de AddSgcHtml, de sorte qu'il répond à ses événements serveur une fois la page rendue.
Demos\60.HTML\01.RunTime\29.Tour est la sgc Cloud Console sur le port 8131 : une visite de premier lancement en huit étapes avec un projecteur, une seconde visite Nouveautés sur la même page, des infobulles sur les boutons de la barre d'outils, les cartes de statistiques et les champs de formulaire, et un entonnoir d'intégration que le serveur enregistre par utilisateur. Les versions design time, Lazarus et .NET en sont le miroir.
| Essayer en ligneVoyez-le dans la démo Visite guidée & infobulles, en fonctionnement direct sur le serveur de démos d'eSeGeCe. | Ouvrir | |
| Aide en ligneRéférence API complète et guide d'utilisation pour ce composant. | Ouvrir | |
| Composant TooltipDes conseils sur les boutons et les champs, présentés avec la visite dans la même démo. | Ouvrir | |
| Tous les composants sgcHTMLParcourez la matrice complète des fonctionnalités de plus de 80 composants. | Ouvrir | |
| Télécharger la version d'essai gratuiteLa version d'essai de 30 jours fournit les projets de démonstration 60.HTML. | Ouvrir | |
| TarifsLicences Single, Team et Site avec code source complet. | Ouvrir |