Sei nuovi componenti di feedback sgcHTML: Badge, PDFViewer, ContextMenu, ProgressBar, JobProgress e LogViewer

Quarto articolo di questa serie sui 25 nuovi componenti di sgcHTML. Questo gruppo riguarda il mostrare al visitatore cosa sta succedendo in questo momento: un conteggio su un'icona a campanella, un documento aperto in linea, un menu al clic destro e tre modi diversi per mostrare un lavoro in corso — una singola barra, un elenco di job in background e un log scorrevole. Tutti e sei sono componenti Delphi/C++Builder/.NET renderizzati lato server; nessuno di essi richiede una libreria di grafici o PDF lato client da configurare da soli.

Badge — un'etichetta, una pillola o un puntino di notifica

TsgcHTMLComponent_Badge genera un singolo <span class="badge"> Bootstrap 5. Impostando Positioned si trasforma in un puntino di notifica posizionato in modo assoluto, ancorato a qualsiasi elemento position-relative che lo racchiude: il classico conteggio su un'icona a campanella.

uses
  sgcHTML_Enums, sgcHTML_Component_Badge;

var
  oBadge: TsgcHTMLComponent_Badge;
begin
  oBadge := TsgcHTMLComponent_Badge.Create(nil);
  try
    oBadge.Text := '3';
    oBadge.Color := bgDanger;
    oBadge.Pill := True;
    oBadge.Positioned := True;

    WebModule.Response := oBadge.HTML;   // <span class="badge bg-danger rounded-pill ...">
  finally
    oBadge.Free;
  end;
end;

// Or the one-line static helper for a simple inline badge:
WebModule.Response := TsgcHTMLComponent_Badge.Build('New', bgSuccess, True);

PDFViewer — un documento in pagina, senza plugin

TsgcHTMLComponent_PDFViewer genera una barra degli strumenti e un canvas basati su pdf.js, con navigazione tra le pagine, zoom, ricerca, download e stampa integrati. Puntare PDFURL a un documento (oppure incorporare i byte con Base64Data) e il rendering avviene interamente lato client.

uses
  sgcHTML_Component_PDFViewer;

var
  oViewer: TsgcHTMLComponent_PDFViewer;
begin
  oViewer := TsgcHTMLComponent_PDFViewer.Create(nil);
  try
    oViewer.ViewerID := 'invoice';
    oViewer.PDFURL := '/invoices/INV-2026-0042.pdf';
    oViewer.Height := '700px';
    oViewer.InitialPage := 1;
    oViewer.Zoom := 'page-width';
    oViewer.Theme := pvLight;
    oViewer.DownloadFileName := 'invoice-0042.pdf';

    WebModule.Response := oViewer.HTML;   // toolbar + canvas + pdf.js init script
  finally
    oViewer.Free;
  end;
end;

ContextMenu — un menu al clic destro delimitato da un selettore

TsgcHTMLComponent_ContextMenu genera un dropdown Bootstrap che si apre al clic destro, limitato agli elementi che corrispondono a TargetSelector. Le voci con un DataAction vengono inviate attraverso lo stesso canale già usato dai form e generano un evento DOM a cui è possibile agganciarsi.

uses
  sgcHTML_Component_ContextMenu;

var
  oMenu: TsgcHTMLComponent_ContextMenu;
  oItem: TsgcHTMLContextMenuItem;
begin
  oMenu := TsgcHTMLComponent_ContextMenu.Create(nil);
  try
    oMenu.MenuID := 'grid_menu';
    oMenu.TargetSelector := '.grid-row';

    oItem := oMenu.Items.Add;
    oItem.Caption := 'Edit';
    oItem.Icon := 'bi bi-pencil';
    oItem.DataAction := 'row:edit';

    oItem := oMenu.Items.Add;
    oItem.Caption := 'Delete';
    oItem.Icon := 'bi bi-trash';
    oItem.DataAction := 'row:delete';

    oItem := oMenu.Items.Add;
    oItem.Divider := True;

    oItem := oMenu.Items.Add;
    oItem.Caption := 'Open in new tab';
    oItem.Href := '/grid/open';

    WebModule.Response := oMenu.HTML;   // hidden <ul> + right-click binding script
  finally
    oMenu.Free;
  end;
end;

ProgressBar — barra singola o segmenti impilati

TsgcHTMLComponent_ProgressBar copre sia il caso semplice, un singolo Value/Max, a righe e animato, sia il caso impilato: aggiungendo voci a Bars queste sostituiscono la barra singola con una barra multi-segmento, ciascun segmento con il proprio colore ed etichetta.

uses
  sgcHTML_Enums, sgcHTML_Component_ProgressBar;

var
  oBar: TsgcHTMLComponent_ProgressBar;
begin
  oBar := TsgcHTMLComponent_ProgressBar.Create(nil);
  try
    oBar.ProgressBarID := 'upload';
    oBar.Value := 72;
    oBar.Max := 100;
    oBar.ColorStyle := hcSuccess;
    oBar.Striped := True;
    oBar.Animated := True;
    oBar.ShowLabel := True;
    oBar.LabelFormat := '%d%% complete';

    WebModule.Response := oBar.HTML;   // Bootstrap progress bar
  finally
    oBar.Free;
  end;
end;

// Or a stacked, multi-segment bar:
with oBar.Bars.Add do
begin
  Value := 40;
  ColorStyle := hcPrimary;
  Label_ := 'Done';
end;
with oBar.Bars.Add do
begin
  Value := 20;
  ColorStyle := hcWarning;
  Label_ := 'In progress';
end;

JobProgress — un elenco live di job in background

TsgcHTMLComponent_JobProgress è ciò in cui si trasforma un ProgressBar quando si devono tracciare più cose contemporaneamente: una card che elenca ogni job in background, ciascuno con il proprio badge di stato e la propria barra di avanzamento. AddJob registra un job, UpdateJob lo fa avanzare e GetJobFragmentHTML invia solo quella riga ai client connessi invece di ridisegnare l'intero elenco.

uses
  sgcHTML_Enums, sgcHTML_Component_JobProgress;

var
  oJobs: TsgcHTMLComponent_JobProgress;
begin
  oJobs := TsgcHTMLComponent_JobProgress.Create(nil);
  try
    oJobs.JobsID := 'exports';
    oJobs.Title := 'Background Exports';
    oJobs.ShowCompleted := False;

    oJobs.AddJob('exp-42', 'Export customers.csv', 'Generating CSV export');

    WebModule.Response := oJobs.HTML;   // card + progress rows + cancel-form script
  finally
    oJobs.Free;
  end;
end;

// On a later progress tick, push just that row over the WebSocket:
oJobs.UpdateJob('exp-42', 65, jsRunning);
Engine.BroadcastFragment(oJobs.GetJobFragmentHTML('exp-42'));

LogViewer — un terminale in streaming, con filtro per livello incluso

TsgcHTMLComponent_LogViewer genera un pannello in stile terminale, scuro o chiaro, con una casella di ricerca e un filtro per livello, basato su un buffer circolare limitato (MaxLines) in modo che non cresca mai senza limiti. AddLine aggiunge una voce con timestamp e colore in base al livello; GetLastLineFragmentHTML trasmette le nuove righe a ogni client aperto senza un ridisegno completo.

uses
  sgcHTML_Component_LogViewer;

var
  oLog: TsgcHTMLComponent_LogViewer;
begin
  oLog := TsgcHTMLComponent_LogViewer.Create(nil);
  try
    oLog.LogID := 'applog';
    oLog.Theme := ltDark;
    oLog.MaxLines := 500;
    oLog.Height := '400px';

    oLog.AddLine(llInfo, 'Service started', 'app');
    oLog.AddLine(llWarning, 'Low disk space', 'monitor');
    oLog.AddLine(llError, 'Connection refused', 'db');

    WebModule.Response := oLog.HTML;   // toolbar + log body + inline script
  finally
    oLog.Free;
  end;
end;

// Push one more line to every connected client, no full re-render:
oLog.AddLine(llInfo, 'New order received', 'orders');
TsgcHTMX_Engine_Server.BroadcastFragment(oLog.GetLastLineFragmentHTML);

Provali

Documentazione completa, riferimenti alle proprietà principali ed esempi di codice Delphi/C++Builder/.NET si trovano nella pagina di ciascun componente: Badge, PDFViewer, ContextMenu, ProgressBar, JobProgress e LogViewer. Articolo precedente di questa serie: presenza, ruoli e gestione utenti.

Domande, feedback o serve aiuto con la migrazione? Contattaci — riceverai una risposta dalle persone che hanno scritto il codice.