Três Novos Componentes de Administração sgcHTML: Presence, RolesPermissions e UserManagement

Último post desta série sobre os 25 novos componentes do sgcHTML. Fechamos com os três que todo painel de administração acaba precisando: quem está online agora, quem tem permissão para fazer o quê, e a tabela onde você de fato gerencia as contas. Os três enviam atualizações ao vivo pelo mesmo canal WebSocket que suas telas de chat e de progresso de tarefas já usam, então este lote se encaixa perfeitamente ao lado dos componentes dos posts anteriores.

Presence — uma lista ao vivo de quem está online

TsgcHTMLComponent_Presence renderiza uma pilha de avatares sobrepostos ou uma lista de nome e status, limitada por MaxVisible com um chip de excedente "+N". AddUser insere ou atualiza uma entrada na lista, SetUserStatus atualiza apenas o ponto de status, e GetUserFragmentHTML envia essa única alteração para todos os clientes conectados.

uses
  sgcHTML_Component_Presence;

var
  oPresence: TsgcHTMLComponent_Presence;
begin
  oPresence := TsgcHTMLComponent_Presence.Create(nil);
  try
    oPresence.PresenceID := 'roster';
    oPresence.Layout := plAvatars;
    oPresence.MaxVisible := 5;
    oPresence.Title := 'Online';

    oPresence.AddUser('u1', 'Ana Torres', psOnline);
    oPresence.AddUser('u2', 'Marc Bell', psAway, '', 'Back at 3pm');
    oPresence.AddUser('u3', 'Kenji Ito', psBusy);

    WebModule.Response := oPresence.HTML;   // avatar stack + scoped CSS
  finally
    oPresence.Free;
  end;
end;

// Push a status change to every connected client, no full re-render:
oPresence.SetUserStatus('u2', psOnline);
TsgcHTMX_Engine_Server.BroadcastFragment(oPresence.GetUserFragmentHTML('u2'));

RolesPermissions — uma matriz de concessão, não um formulário cheio de checkboxes

TsgcHTMLComponent_RolesPermissions organiza os papéis em colunas e as permissões em linhas (agrupadas por categoria), com um checkbox em cada interseção. AddRole e AddPermission constroem os dois eixos, SetGrant marca as células iniciais, e cada alternância feita pelo cliente chega ao servidor como um payload JSON que seu handler deve autorizar antes de aplicar com ProcessGrantChanged.

uses
  sgcHTML_Enums, sgcHTML_Component_RolesPermissions;

var
  oMatrix: TsgcHTMLComponent_RolesPermissions;
begin
  oMatrix := TsgcHTMLComponent_RolesPermissions.Create(nil);
  try
    oMatrix.MatrixID := 'acl';
    oMatrix.StickyHeader := True;

    oMatrix.AddRole('admin', 'Administrator').Color := hcDanger;
    oMatrix.AddRole('editor', 'Editor');
    oMatrix.AddRole('viewer', 'Viewer');

    oMatrix.AddPermission('users.edit', 'Edit users', 'Users');
    oMatrix.AddPermission('users.delete', 'Delete users', 'Users');
    oMatrix.AddPermission('billing.view', 'View invoices', 'Billing');

    oMatrix.SetGrant('admin', 'users.edit', True);
    oMatrix.SetGrant('admin', 'users.delete', True);
    oMatrix.SetGrant('editor', 'users.edit', True);

    WebModule.Response := oMatrix.HTML;   // matrix table + inline script
  finally
    oMatrix.Free;
  end;
end;

// Server-side handler for a checkbox toggle received over WebSockets.
// ALWAYS verify the acting user is authorized before applying the change:
oMatrix.ProcessGrantChanged('editor', 'users.delete', True);

UserManagement — a própria tabela de contas

TsgcHTMLComponent_UserManagement é a tabela onde esses papéis são atribuídos: avatar, badge de status, badges de papéis, último login, caixa de busca e um dropdown de ações por linha (editar, desativar/ativar, redefinir senha e, se você optar por isso, personificar e excluir). AddUser adiciona uma linha e retorna um TsgcHTMLUser para você preencher; ProcessUserAction trata o que quer que o dropdown de uma linha envie de volta, novamente somente após sua própria verificação de autorização.

uses
  sgcHTML_Component_UserManagement;

var
  oUsers: TsgcHTMLComponent_UserManagement;
  oUser: TsgcHTMLUser;
begin
  oUsers := TsgcHTMLComponent_UserManagement.Create(nil);
  try
    oUsers.TableID := 'users';
    oUsers.AllowImpersonate := True;
    oUsers.AllowDelete := True;

    oUser := oUsers.AddUser('u1', 'ana.torres', 'ana@example.com');
    oUser.DisplayName := 'Ana Torres';
    oUser.Roles := 'admin,editor';
    oUser.Status := usActive;
    oUser.LastLogin := '2026-07-15 09:12';

    oUsers.AddUser('u2', 'marc.bell', 'marc@example.com').Status := usInvited;

    WebModule.Response := oUsers.HTML;   // toolbar + table + inline script
  finally
    oUsers.Free;
  end;
end;

// Server-side handler for an action received over WebSockets.
// ALWAYS verify the acting user is authorized before applying it:
oUsers.ProcessUserAction('userDisable', 'u2');

Note o padrão repetido tanto em RolesPermissions quanto em UserManagement: o componente sempre se limita a renderizar a UI e emitir um evento. Nada muda de estado até que seu próprio código no servidor decida que o usuário que está agindo tem permissão para fazer essa mudança, e então chame explicitamente ProcessGrantChanged ou ProcessUserAction. Por design, o componente nunca autoriza nada por você.

Fim da série

Vinte e cinco componentes em cinco posts: dados estruturados (TreeGrid, PivotTable, ActivityFeed, Splitter), gráficos e códigos (Heatmap, Sparkline, CandlestickChart, TreeMap, QRCode, Barcode), campos de formulário (MultiSelect, ColorPicker, Slider, TimePicker, SignaturePad, Transfer), feedback e layout (Badge, PDFViewer, ContextMenu, ProgressBar, JobProgress, LogViewer), e os três componentes de administração de hoje. A matriz completa de recursos agora lista 83 componentes em nove famílias, e cada um deles está documentado com um QuickStart em Delphi, C++Builder e .NET em sua própria página: Presence, RolesPermissions e UserManagement incluídos.

Perguntas, feedback ou ajuda com migração? Entre em contato — você receberá uma resposta de quem escreveu o código.