HTML Templates (structural)
Kittox renders the structural HTML of a page — the parts that frame the content — from HTML template files on disk, using the TemplatePro engine. The Delphi controllers compute the data; the template decides the markup.
These structural templates cover:
_Page— the full HTML page skeleton (<head>, theme, scripts, body wrapper)BorderPanel— the North/West/Center/East/South layoutTabPanel— the tab bar and tab bodiesTreePanel— the navigation tree/menu panelStatusBar— the footer status barLogin— the login dialog
The data-heavy HTML (grid rows and cells, form fields) is still produced in Delphi and is not templated — only the page structure (the frame) is.
Where templates live
Templates are plain .html files under a Home/Templates folder. They are server-side artifacts and are not exposed over HTTP: do not place them under Home/Resources (which is served, at /res/*).
The system defaults ship in the framework's own Home/Templates and each one carries a self-contained header comment documenting its purpose and the exact variables it receives.
Template syntax
KittoX templates use a small subset of TemplatePro:
| Token | Meaning |
|---|---|
{{:name}} | insert the value, HTML-escaped |
{{:name$}} | insert the value as raw HTML (already-rendered markup) |
{{if name}}…{{endif}} | conditional block |
{{# … #}} | comment — removed at compile time, never sent to the browser |
The trailing $ marks a variable whose value is already HTML (for example a rendered child region), so it must not be escaped. Because {{# … #}} comments are stripped during compilation, the copyright + documentation header inside each template adds zero bytes to the response.
The 3-level override lookup
When a controller needs its template, TKXTemplateEngine resolves it with a first-match-wins lookup:
‹App›/Home/Metadata/Views/Templates/‹ViewName›.html— per view override‹App›/Home/Templates/‹ControllerType›.html— per application override‹Kitto›/Home/Templates/‹ControllerType›.html— the system default
If no override exists, the system default is used — so an application runs with zero template files and you add one only where you want to change something.
Customizing a template
To change the markup of, say, the login dialog for your application:
- Copy the system default
Login.htmlinto your app'sHome/Templates/. - Edit the copy.
- A restart is not required for the change to appear — templates are read from disk when rendered.
Keep the file name identical to the controller type (level 2) or to the view name (level 1). Preserve the variables the controller injects and the CSS classes / element ids that the companion client scripts depend on (e.g. kx-login-status, kx-center-tabs), otherwise the interactive behavior breaks.
Each system template lists its variables in its header. For example _Page.html receives appTitle, resPath, homeContent$, the theme hooks (themeAttr$/themeBoot$/themeStyle$) and the localized JS strings; Login.html receives title, fieldsContent$, linksContent$, loginLabel, and so on.
Good to know
- Fallback safety. Overriding is purely additive: remove your copy and the system default takes over again.
- Upgrade drift. An override is a frozen copy. When a new KittoX release improves a default template (new features, fixes, changes to the HTMX API), your copy does not receive them automatically. On upgrade, re-diff your overrides against the new system defaults.
- Theming vs. templates. Day-to-day look-and-feel is driven by CSS custom properties (see the theme system); reach for a template override only when you need to change the structure of the markup, not just its styling.