Tour

TsgcHTMLComponent_Tour: um tour guiado do produto para onboarding. Ele destaca os elementos da página um passo de cada vez com um holofote e um cartão, começa sozinho na primeira visita, a partir de um botão ou do servidor, e informa o progresso de cada usuário por meio de eventos de servidor, em Delphi, C++ Builder e .NET.

Visão geral

TsgcHTMLComponent_Tour

Adicione os Steps, aponte cada um para um elemento, e defina AutoStart ou adicione um botão de início. OnStepChange, OnSkip e OnComplete informam ao servidor até onde cada usuário chegou.

Classe do componente

TsgcHTMLComponent_Tour, com um TsgcHTMLTourStep por passo em Steps

Renderiza

Um elemento oculto com a configuração em JSON e o script do tour, com seus estilos embutidos, sem arquivos externos e sem CDN

Família

Sobreposições e Feedback

Linguagens

Delphi, C++ Builder, .NET

QuickStart

Passos, um início, e os eventos que registram o onboarding

Com AutoStart o tour começa sozinho na primeira vez que um navegador abre a página, e o botão de início o repete a qualquer momento. Com um HTMXEngine atribuído, o navegador envia os eventos que têm manipulador.

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);
}

Recursos

O que seus usuários recebem

Uma primeira execução que mostra aos novos usuários o que está onde, e um registro no seu servidor de até onde cada um chegou.

Holofote e cartão

Cada passo destaca um elemento com um recorte de holofote em um fundo esmaecido e mostra ao lado um cartão com um título, conteúdo HTML, uma imagem opcional, um contador de passos com pontos de progresso e os botões Voltar, Próximo, Pular tour e Concluir. Um passo sem alvo mostra o cartão centralizado na página.

Quatro formas de começar

Sozinho na primeira visita (AutoStart), a partir de um botão (GetStartButtonHTML, ou data-sgc-tour-start em qualquer elemento), a partir do seu próprio script (GetStartScript) ou a partir do servidor para um usuário (GetStartHTML).

Lembrado no navegador

Concluir ou Pular tour é guardado no localStorage do navegador em StorageKey, sgc-tour:<Name> por padrão, e AutoStart não inicia o tour de novo ali. Altere StorageKey para mostrar um tour revisado a todos.

Passos que se ajustam ao usuário

Um passo cujo alvo está ausente ou oculto, por exemplo um painel de uma função que o usuário não tem, é ignorado nos dois sentidos, e o contador conta apenas os passos que podem ser mostrados. O cartão fica dentro da área visível, e em telas estreitas ele recua para baixo, para cima ou centralizado.

Teclado e leitores de tela

O cartão é um diálogo nomeado pelo seu título. O foco vai para Próximo quando um passo aparece e volta para onde estava quando o tour termina, e em um cartão modal o Tab circula pelos seus botões. As setas movem entre os passos, Esc sai, e uma região live educada anuncia "Passo n de m: título".

Idiomas e temas

Os botões e o texto dos passos vêm nos 17 idiomas da biblioteca. As páginas da direita para a esquerda espelham o posicionamento e as setas, e o cartão copia o data-bs-theme da página, de modo que segue um tema escuro. Os estilos são adicionados quando o tour começa e removidos quando termina.

Referência

Principais propriedades, métodos & eventos

Os membros que você mais usa.

Passos

Cada passo tem um Target (um seletor CSS, a sua primeira correspondência) ou um TargetComponent, um Title em texto simples, um Content em HTML saneado com sgcHTMLSanitizeHTML, uma URL de Image que passa por sgcHTMLSanitizeURL, um Placement, os seus próprios ShowBackdrop e ScrollIntoView.

Aparência

ShowBackdrop, ShowProgress e ShowSkip ligam ou desligam o fundo, o contador com os pontos e o botão Pular tour. Padding (6 por padrão) é o espaço em pixels ao redor do alvo, AllowKeyboard ativa Esc e as setas, e CloseOnBackdropClick sai do tour ao clicar no fundo.

Eventos de servidor

OnStepChange dispara cada vez que um passo é mostrado, OnSkip quando o usuário sai antes do fim, com o índice do passo, e OnComplete quando o usuário pressiona Concluir no último passo. O navegador envia apenas os eventos que têm manipulador, e um índice de passo fora de Steps é recusado.

O usuário do evento

O manipulador executa na thread da requisição, onde sgcHTMLRequestSession fornece a sessão e o usuário. O HTML que ele devolve em aResponse é inserido pelo htmx quando os seus elementos estão marcados com hx-swap-oob="true".

Sem um motor

Atribua HTMXEngine, ou defina ActionURL e chame DispatchComponentEvent('tour', Params, Response) a partir da sua própria rota. Sem nenhum dos dois, o tour roda no navegador e não envia nada. Com htmx na página ele envia por htmx.ajax, caso contrário por XMLHttpRequest com as meta tags CSRF da página.

Iniciar a partir do servidor

GetStartHTML devolve um fragmento que inicia o tour no navegador que o recebe, como resposta htmx ou como um push para uma conexão. O botão de início, GetStartScript e GetStartHTML ignoram a entrada guardada no navegador.

API JavaScript

window.sgcHTMLTour oferece start(id[, step]), next, back, end, reset e active. Cada função recebe o id do tour, o valor de GetElementIdentifier. reset remove a entrada guardada, de modo que AutoStart executa o tour de novo.

ASP.NET Core

Em uma view Razor, o Tag Helper <sgc-tour name="..."> renderiza o tour, com um filho <sgc-tour-step> por passo cujo conteúdo é o HTML do cartão. A primeira renderização cria um componente por motor e nome, registrado no motor de AddSgcHtml, de modo que responde aos seus eventos de servidor depois que a página foi renderizada.

A demo

Demos\60.HTML\01.RunTime\29.Tour é o sgc Cloud Console na porta 8131: um tour de primeira execução em oito passos com um holofote, um segundo tour Novidades na mesma página, tooltips nos botões da barra de ferramentas, cartões de estatísticas e campos de formulário, e um funil de onboarding que o servidor registra por usuário. As versões em design time, Lazarus e .NET a espelham.