# Sgcwebsockets HTML Forms

> sgcHTML Forms and Inputs

- Skill: `esegece-com/sgcwebsockets-html-forms` (Agent Skill, multi-file: 59 files)
- Install (CLI): `npx skillmds@latest add esegece-com/sgcwebsockets-html-forms`
- Raw SKILL.md: https://api.skillmd.com/api/skills/esegece-com/sgcwebsockets-html-forms/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-forms

---


# sgcHTML Forms and Inputs

Twenty-one input widgets for sgcHTML forms: text, numbers, dates, selection,
sliders, colour, rich text, file upload and a signature pad. Each renders a
Bootstrap-styled control and can bind directly to a Delphi `TDataSource`.

Read `sgcwebsockets-html-core` first. It covers the page builder these widgets
register with, and the edition gate that decides whether they exist at all.
In short: sgcHTML is All-Access only, needs Indy, and is not available on
Android or iOS.

## When to use this skill

- Put a form on a server-rendered page: text, email, password, number, date
- Offer a choice: select, multi-select, radio group, checkbox, autocomplete
- Take a date, a time, a datetime or a date range
- Take a number on a slider, or a range between two values
- Take rich text, a colour, an uploaded file or a drawn signature
- Bind any of those to a dataset field so the page shows live data

## The surface every widget shares

These are on all of them, and they are most of what you will actually set:

| Property | What it does |
| --- | --- |
| `PageBuilder` | The builder this widget renders into. Nothing appears without it |
| `Label_` | The visible label. Note the trailing underscore |
| `ElementName` | The HTML form field name, which is what a POST arrives under |
| `ElementID`, `CSSClass`, `Style`, `Attributes` | Raw HTML passthrough |
| `Section`, `SectionTitle`, `SectionOrder`, `RowGroup` | Where it lands on the page |
| `ColumnWidth` | Bootstrap column width, `cwAuto` or `cw1` to `cw12` |
| `DataSource`, `DataField`, `DataAutoRefresh` | Dataset binding |
| `ComponentVisible` | Render it or not |
| `HTML` | Read-only, the fragment this widget produces |
| `OnDataChanged`, `OnBeforeRefresh`, `OnAfterRefresh` | Delphi events |
| `OnClick` | **A string of JavaScript**, not a Delphi event |

`Label_` ends in an underscore because `Label` collides in Delphi. Writing
`FEdit.Label := 'Name'` will not compile, and the fix is the underscore.

`OnClick` being a string is the one that surprises people. It is client-side
JavaScript emitted into the markup. For server-side reactions use the Delphi
events, or HTMX from `sgcwebsockets-html-core`.

## 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 bound to a dataset, or free-standing?** With `DataSource` and
   `DataField` set, the widget shows live data and you write almost no code.
   Without them you set `Value` yourself.
2. **How is the form submitted?** A normal POST reads `ElementName` values on
   the server. HTMX submits fragments instead. That decision shapes the handler.
3. **What layout?** `Section` and `RowGroup` group widgets, `ColumnWidth` sets
   the Bootstrap columns. Without them everything stacks.
4. **Which input type?** One `TsgcHTMLComponent_Edit` covers text, email,
   password, number, date and more through `InputType`, so a separate component
   is often unnecessary.

## Components in this skill

| Group | Components |
| --- | --- |
| Text | `_Edit`, `_Memo`, `_RichEditor` |
| Choice | `_Select`, `_MultiSelect`, `_RadioGroup`, `_CheckBox`, `_AutoComplete`, `_Transfer` |
| Date and time | `_DatePicker`, `_TimePicker`, `_DateTimePicker`, `_DateRangePicker` |
| Numeric | `_Slider`, `_RangeSlider`, `_Rating` |
| Other input | `_ColorPicker`, `_FileUpload`, `_SignaturePad` |
| Structure | `_Form`, `_InputGroup` |

All are prefixed `TsgcHTMLComponent_`.

## Quickstart, a bound form

```pascal
uses
  sgcHTML_Component;   // plus each widget's own unit, see its API page

FEdit := TsgcHTMLComponent_Edit.Create(Self);
FEdit.PageBuilder := FPage;
FEdit.Label_ := 'Email';
FEdit.ElementName := 'email';
FEdit.InputType := itEmail;
FEdit.Required := True;
FEdit.Placeholder := 'you@example.com';
FEdit.HelpText := 'We only use this to reply.';
FEdit.ColumnWidth := cw6;
FEdit.Section := 'contact';
FEdit.SectionTitle := 'Contact details';

// bind it to a dataset instead of setting Value by hand
FEdit.DataSource := dsCustomers;
FEdit.DataField := 'EMAIL';
FEdit.DataAutoRefresh := True;
```

`TsgcHTMLInputType` is `(itText, itEmail, itPassword, itNumber, itTel, itURL,
itSearch, itDate, itTime, itDateTimeLocal, itMonth, itWeek, itColor, itRange,
itFile, itHidden)`, so a plain `_Edit` covers most fields on its own.

`TsgcHTMLColWidth` is `(cwAuto, cw1 ... cw12)`, the twelve Bootstrap columns.
Two `cw6` widgets sit side by side, three `cw4` make thirds.

## Layout without writing CSS

Widgets are placed by property, not by markup:

- `Section` groups widgets into a block, `SectionTitle` gives that block a
  heading, and `SectionOrder` decides where the block sits on the page.
- `RowGroup` puts widgets on the same row.
- `ColumnWidth` divides that row.

Set none of them and the form renders as a single stacked column, which is a
perfectly reasonable default for a short form.

## Things that catch people out

- `Label` does not exist. It is `Label_`.
- `OnClick` is JavaScript in a string. Assigning a Delphi method to it will not
  compile, and it is not a server-side event.
- A widget with no `PageBuilder` renders nowhere and reports nothing.
- `ElementName` is what the browser posts. Leaving it blank means the value
  arrives unnamed and you cannot read it server-side.
- `Required` renders the HTML validation attribute. That is a browser check and
  trivially bypassed, so validate again on the server.
- Binding a `DataSource` without `DataField` shows an empty control rather than
  raising, which reads as the binding being broken when it is just incomplete.

## 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.