TsgcHTMLComponent_Tour: un recorrido guiado del producto para la incorporación. Resalta los elementos de la página paso a paso con un foco destacado y una tarjeta, se inicia solo en la primera visita, desde un botón o desde el servidor, e informa del progreso de cada usuario mediante eventos de servidor, en Delphi, C++ Builder y .NET.
Añade los Steps, apunta cada uno a un elemento y define AutoStart o añade un botón de inicio. OnStepChange, OnSkip y OnComplete informan al servidor de hasta dónde llegó cada usuario.
TsgcHTMLComponent_Tour, con un TsgcHTMLTourStep por paso en Steps
Un elemento oculto con la configuración como JSON y el script del recorrido, con sus estilos incrustados, sin archivos externos y sin CDN
Delphi, C++ Builder, .NET
Con AutoStart el recorrido se inicia solo la primera vez que un navegador abre la página, y el botón de inicio lo repite en cualquier momento. Con un HTMXEngine asignado, el navegador envía los eventos que tienen manejador.
uses
sgcHTML_Session, sgcHTML_Component_Tour;
// Se crea una sola vez: responde a sus eventos de servidor tras renderizar la página
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'; // sin destino: una tarjeta centrada
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 sesión de esta petición
if oSession <> nil then
SaveOnboardingDone(oSession.UserID); // tu propio código
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;@* El contenido de cada paso es el HTML de su tarjeta *@
<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 primer uso que muestra a los usuarios nuevos qué hay y dónde, y un registro en tu servidor de hasta dónde llegó cada uno.
Cada paso resalta un elemento con un recorte de foco en un fondo atenuado y muestra junto a él una tarjeta con un título, contenido HTML, una imagen opcional, un contador de pasos con puntos de progreso y los botones Atrás, Siguiente, Omitir recorrido y Hecho. Un paso sin destino muestra la tarjeta centrada en la página.
Solo en la primera visita (AutoStart), desde un botón (GetStartButtonHTML, o data-sgc-tour-start en cualquier elemento), desde tu propio script (GetStartScript) o desde el servidor para un usuario (GetStartHTML).
Hecho u Omitir recorrido se guarda en el localStorage del navegador bajo StorageKey, por defecto sgc-tour:<Name>, y AutoStart no vuelve a iniciar allí el recorrido. Cambia StorageKey para mostrar un recorrido revisado a todos.
Un paso cuyo destino falta o está oculto, por ejemplo un panel de un rol que el usuario no tiene, se omite en ambos sentidos, y el contador cuenta solo los pasos que se pueden mostrar. La tarjeta permanece dentro del viewport y, en pantallas estrechas, pasa a abajo, arriba o centrada.
La tarjeta es un diálogo con el nombre de su título. El foco pasa a Siguiente cuando se muestra un paso y vuelve a donde estaba cuando termina el recorrido, y en una tarjeta modal Tab recorre sus botones cíclicamente. Las flechas se mueven entre los pasos, Esc sale, y una región live cortés anuncia "Paso n de m: título".
Los botones y el texto de los pasos vienen en los 17 idiomas de la biblioteca. Las páginas de derecha a izquierda reflejan la posición y las teclas de flecha, y la tarjeta copia el data-bs-theme de la página, así que sigue un tema oscuro. Los estilos se añaden cuando el recorrido se inicia y se quitan cuando termina.
Los miembros que más vas a usar.
Cada paso tiene un Target (un selector CSS, su primera coincidencia) o un TargetComponent, un Title en texto sin formato, Content en HTML saneado con sgcHTMLSanitizeHTML, una URL de Image que pasa por sgcHTMLSanitizeURL, un Placement, su propio ShowBackdrop y ScrollIntoView.
ShowBackdrop, ShowProgress y ShowSkip activan o desactivan el fondo, el contador con los puntos y el botón Omitir recorrido. Padding (6 por defecto) es el espacio en píxeles alrededor del destino, AllowKeyboard habilita Esc y las flechas, y CloseOnBackdropClick abandona el recorrido al hacer clic en el fondo.
OnStepChange se dispara cada vez que se muestra un paso, OnSkip cuando el usuario sale antes del final, con el índice del paso, y OnComplete cuando el usuario pulsa Hecho en el último paso. El navegador envía solo los eventos que tienen manejador, y se rechaza un índice de paso fuera de Steps.
El manejador se ejecuta en el hilo de la petición, donde sgcHTMLRequestSession da la sesión y el usuario. El HTML que devuelve en aResponse lo intercambia htmx cuando sus elementos están marcados con hx-swap-oob="true".
Asigna HTMXEngine, o define ActionURL y llama a DispatchComponentEvent('tour', Params, Response) desde tu propia ruta. Sin ninguno de los dos, el recorrido se ejecuta en el navegador y no envía nada. Con htmx en la página envía mediante htmx.ajax, y si no mediante XMLHttpRequest con las metaetiquetas CSRF de la página.
GetStartHTML devuelve un fragmento que inicia el recorrido en el navegador que lo recibe, como respuesta htmx o como envío a una conexión. El botón de inicio, GetStartScript y GetStartHTML ignoran la entrada guardada en el navegador.
window.sgcHTMLTour ofrece start(id[, step]), next, back, end, reset y active. Cada función recibe el id del recorrido, el valor de GetElementIdentifier. reset elimina la entrada guardada, así que AutoStart vuelve a ejecutar el recorrido.
En una vista Razor, el Tag Helper <sgc-tour name="..."> renderiza el recorrido, con un hijo <sgc-tour-step> por paso cuyo contenido es el HTML de la tarjeta. El primer renderizado crea un componente por motor y nombre, registrado en el motor de AddSgcHtml, de modo que responde a sus eventos de servidor tras renderizar la página.
Demos\60.HTML\01.RunTime\29.Tour es la sgc Cloud Console en el puerto 8131: un recorrido de primer uso de ocho pasos con foco destacado, un segundo recorrido de novedades en la misma página, tooltips en los botones de la barra de herramientas, tarjetas de estadísticas y campos de formulario, y un embudo de incorporación que el servidor registra por usuario. Las versiones de tiempo de diseño, Lazarus y .NET lo replican.
| Pruébalo en líneaMíralo en la demo Recorrido y tooltips, funcionando en vivo en el servidor de demos de eSeGeCe. | Abrir | |
| Ayuda en líneaReferencia completa de la API y guía de uso para este componente. | Abrir | |
| Componente TooltipPistas en botones y campos, mostradas con el recorrido en la misma demo. | Abrir | |
| Todos los componentes de sgcHTMLExplora la matriz de características completa de más de 80 componentes. | Abrir | |
| Descargar prueba gratuitaLa prueba de 30 días incluye los proyectos de demostración 60.HTML. | Abrir | |
| PreciosLicencias Single, Team y Site con todo el código fuente. | Abrir |