Sgcwebsockets HTML Core

sgcHTML Core

sgcHTML builds server-rendered HTML pages from Delphi components. You drop components on a form, register them with a page builder, and the builder emits Bootstrap-based markup that an HTML engine server serves over HTTP.

This skill is the foundation: the page builder, the engine server, theming, the site and dashboard shells, the HTMX layer and the visual design surface. The individual widgets live in the six companion skills, and all of them assume what is described here.

Read this first: availability

sgcHTML is gated in sgcVer.inc, and the gate is narrower than most of the suite:

• SGC_PACK_HTML is defined only for the All-Access edition
• SGC_HTML then additionally requires the Indy library (SGC_INDY_LIB)
• it is excluded on Android and iOS

So sgcHTML is All-Access, desktop and server only. If the components do not appear or the units will not compile, check the edition before checking the code. There is nothing to configure on a build that does not include the pack.

When to use this skill

• Serve HTML pages from a Delphi application without writing HTML by hand
• Set up the page shell: title, language, dark mode, Bootstrap, custom CSS
• Apply a theme across every widget at once
• Build a dashboard or a multi-page site shell
• Add HTMX so parts of a page update without a full reload
• Use the visual design surface to lay a page out

Units, one per component

Each widget skill has its own units too, so a real page pulls in several. Every API page states its unit: at the top.

How the pieces fit

Three roles, and mixing them up is the usual first confusion:

1. Widgets produce fragments of HTML. They are the components in the six companion skills.
2. TsgcHTMLPageBuilder collects widgets through RegisterComponent and assembles the whole document. GetHTML returns it.
3. TsgcHTMLEngine_Server attaches to a TsgcWSHTTPServer through its Server property and serves what the builder produces.

So the HTTP server comes from sgcwebsockets-core; sgcHTML does not replace it, it plugs into it.

Before you start, ask the developer

Use a structured question tool if your host has one, for example Claude Code's AskUserQuestion. Otherwise ask in chat:

1. Is this All-Access? If not, none of this compiles, and that is the whole answer.
2. Is there already an HTTP server in the application? The engine server attaches to one, it does not create one.
3. Full page reloads or HTMX? HTMX changes how you structure handlers, because fragments are returned rather than whole pages. Retrofitting is awkward.
4. Where does Bootstrap come from? IncludeBootstrap decides whether the builder references it, and you must actually serve those assets or point at a CDN.

Quickstart

uses
  sgcWebSocket,             // the HTTP server
  sgcHTML_Component,        // page builder, theme controller
  sgcHTML_Engine_Server;    // the engine that serves pages

FServer := TsgcWebSocketHTTPServer.Create(Self);
FServer.Port := 8080;

FPage := TsgcHTMLPageBuilder.Create(Self);
FPage.Title := 'Dashboard';
FPage.HtmlLang := 'en';
FPage.DarkMode := True;
FPage.IncludeBootstrap := True;
FPage.SidebarBrand := 'My App';

// widgets from the companion skills register themselves here
FPage.RegisterComponent(FGrid);
FPage.RegisterComponent(FChart);

FEngine := TsgcHTMLEngine_Server.Create(Self);
FEngine.Server := FServer;

FServer.Active := True;

GetHTML returns the whole document. GetNavBarHTML and GetSidebarHTML return just those regions, which is what you want when HTMX is replacing one part of the page rather than all of it.

Theming

TsgcHTMLThemeController carries a Theme and emits the matching CSS through GetCSS. Set the theme once and every registered widget follows it, rather than styling widgets individually. TsgcHTMLThemeBuilder is the design-time companion for producing a custom theme. Both expose CustomCSS for the cases a theme does not cover.

HTMX

The three HTMX components add partial-page updates: TsgcHTMX_Engine_Server serves them, TsgcHTMX_Fragment represents a piece of page that can be swapped, and TsgcHTMX_Router maps requests to fragments. Note SGC_HTMX is defined alongside SGC_HTML, so it carries the same edition and platform limits.

Things that catch people out

• The whole pack is All-Access only, and absent on Android and iOS. That accounts for most "the component is not on the palette" reports.
• The engine server does not listen on anything by itself. It needs Server pointed at an HTTP server that you activate.
• A widget that is never passed to RegisterComponent renders nowhere. It will sit on the form doing nothing, with no error.
• IncludeBootstrap only decides whether the markup references Bootstrap. The files still have to be reachable, either served by your application or from a CDN, or the page arrives unstyled.
• Serving assets from a different origin than the page can be blocked by the browser, and web fonts need CORS regardless. Serving them from the same origin as the page avoids the whole class of problem.
• If you also use the lower-level node layer (sgcHTML_Nodes), its containers own what you add to them. Free only the root, never a node you already passed to Add, or the page crashes at render time rather than at compile time.

Routing

• Find a component: reference/components-index.md lists every component, its unit, and its edition, grouped by Reg module.
• Uses clause: add the component's unit: value (shown on its API page) to your uses clause. Nothing compiles without it.
• API detail: reference/api/<Component>.md has the Properties, Events and Methods, each in both Delphi and C++Builder form.
• Option / enum / event types: property and event types link to reference/types/<TypeName>.md, which documents the sub-properties of option classes, the values of enums, and the parameter list of event handlers.
• Examples: examples/index.md is the full demo catalog; examples/<Component>.md is a focused, real usage snippet for the most-used components.
• Concepts: concepts/overview.md (getting started + uses-clause rule) and concepts/editions-and-features.md (which components your edition includes).
• Bundled resources: concepts/resources.md lists the browser-side assets (JavaScript, HTML, CSS) the server components serve or embed, so a browser client works without an external CDN.
• Version history: reference/history.md lists what changed in each sgcWebSockets release.

Editions

Components are gated by edition (Professional, Enterprise, All-Access) or by a feature define. Check the edition column in the components index, or concepts/editions-and-features.md, before relying on a component.

Only public and published members are documented. Method bodies, private fields and protected members are intentionally not included.