# Sgcwebsockets HTML Core

> Use when building server-rendered HTML pages in Delphi with the sgcHTML components. Covers the page builder, HTML engine server, theme controller and theme builder, dashboard layout, the site component, the HTMX engine, fragments and router, and the visual design surface. Start here before the other sgcHTML skills.

- Skill: `esegece-com/sgcwebsockets-html-core` (Agent Skill, multi-file: 159 files)
- Install (CLI): `npx skillmds@latest add esegece-com/sgcwebsockets-html-core`
- Raw SKILL.md: https://api.skillmd.com/api/skills/esegece-com/sgcwebsockets-html-core/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: esegece-com (https://skillmd.com/u/esegece-com)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/esegece-com/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

| Component | Unit |
| --- | --- |
| `TsgcHTMLPageBuilder`, `TsgcHTMLThemeController` | `sgcHTML_Component` |
| `TsgcHTMLEngine_Server` | `sgcHTML_Engine_Server` |
| `TsgcHTMLDashboardLayout` | `sgcHTML_Component_DashboardLayout` |
| `TsgcHTMLThemeBuilder` | `sgcHTML_ThemeBuilder` |
| `TsgcHTMLComponent_Site` | `sgcHTML_Component_Site` |
| `TsgcHTMX_Engine_Server` | `sgcHTMX_Engine_Server` |
| `TsgcHTMX_Fragment` | `sgcHTMX_Fragment` |
| `TsgcHTMX_Router` | `sgcHTMX_Router` |
| `TsgcHTMLDesignSurface` | `sgcHTMLDesign_Surface` |
| `TsgcHTMLDesignServer` | `sgcHTMLDesign_Server_Indy` |

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

```pascal
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.