Kitto^x FAQ

This page collects frequently asked questions about the Kitto^x framework. If you need an article covering a particular subject, or if you think you have something to contribute, let us know by posting in the issues section of this repository.

General

What is Kitto^x?

Kitto^x is a Delphi framework for building data-driven web applications. You define your data models, views, and layouts in declarative YAML files, and Kitto^x generates a complete web application with server-rendered HTML, HTMX for dynamic updates, and AlpineJS for client-side interactivity.

What Delphi versions are supported?

Kitto^x supports RAD Studio / Delphi 10.4 Sydney, 11 Alexandria, and 12 Athens. The project files are in Projects/D10_4, Projects/D11, and Projects/D12.

Which databases does Kitto^x support?

Kitto^x is database-agnostic through pluggable adapters: FireDAC (recommended, supports all major databases), DBExpress, and ADO/OLEDB. Configure the adapter in Config.yaml under Databases.

Can I use multiple databases in the same application?

Yes. Define multiple entries under Databases in Config.yaml and use DatabaseName on models or DatabaseRouter for dynamic routing. See Multiple Databases.

Application structure

What is the minimum set of files for a Kitto^x application?

A minimal application needs:

• A Delphi project file (.dpr) calling TKStart.Start
• UseKitto.pas referencing Kitto.Html.All and any project-specific units
• Home/Metadata/Config.yaml with at least Server/Port and a Databases entry
• At least one Model (.yaml in Home/Metadata/Models/)
• At least one View (.yaml in Home/Metadata/Views/)
• A Home View defining the main layout

What is the Home directory?

Home/ is the runtime root for each application. The %HOME_PATH% macro resolves to it. It contains Metadata/ (YAML files), Resources/ (static assets), and optionally ReportTemplates/.

How do I run my application?

Compile and run the Delphi project. It starts a built-in HTTP server on the port defined in Config.yaml (Server/Port, default 8080). Open a browser at http://localhost:<port>.

Models and Views

What is the difference between a Model and a View?

A Model describes the data structure (fields, types, relationships, validation rules) and maps to a database table. A View describes the UI: which model to display, which fields to show, how to arrange them, and which controller to use.

How do I create a reference (foreign key) field?

In your model YAML, add a field with type Reference pointing to the referenced model:

Fields:
  Customer: Reference(Customer)

This creates a lookup combo in the UI. See Referenced Fields.

How do I add a detail table (master-detail)?

Add a DetailTables section to your view's MainTable:

MainTable:
  Model: Order
  DetailTables:
    Table:
      Model: OrderItem

The detail table appears as a tab in the form editor.

How do I make a field read-only, hidden, or required?

Set the corresponding property on the model field or view field:

Fields:
  CreatedDate:
    IsReadOnly: True
  InternalCode:
    IsVisible: False
  CustomerName:
    IsRequired: True

View-level settings override model-level settings.

Controllers

What controllers are available?

Controller	Description
List	Data grid with paging, sorting, filtering
Form	Record edit/add/view form
BorderPanel	5-region layout (North, West, Center, East, South)
TabPanel	Tabbed container for sub-views
TilePanel	Tile/card layout for menu items
TreePanel	Tree navigation menu
HtmlPanel	Static or dynamic HTML content
ChartPanel	Chart.js-based data visualization
TemplateDataPanel	Custom HTML template with data binding
GroupingList	List with row grouping
CalendarPanel	Calendar view
StatusBar	Status bar with text
ToolBar	Navigation toolbar

See Panel-Based Controllers for the full reference.

How do I add export/download buttons to a list?

Add a ToolViews section under the view table's Controller:

Controller: List
  ToolViews:
    DownloadCSV:
      DisplayLabel: Download CSV
      Controller: ExportCSVTool
        RequireSelection: False
    DownloadExcel:
      DisplayLabel: Download Excel
      Controller: ExportExcelTool
        ClientFileName: Report.xls
        TemplateFileName: %APP_PATH%ReportTemplates\Template.xlt

See Tool Controllers for all available tools.

How do I add filters to a list?

Add a Filters section under the controller. See How to Filter Data for examples.

Controller: List
  Filters:
    DisplayLabel: Search
    Items:
      FreeSearch: Name
        ExpressionTemplate: UPPER({Q}) LIKE UPPER('%{value}%')
      DynaList: Category
        ExpressionTemplate: T.CATEGORY_ID = {value}
        CommandText: SELECT ID, NAME FROM CATEGORIES ORDER BY NAME

How do I open a form in add mode directly?

Use a standalone Form controller with Operation: Add:

Controller: Form
  Operation: Add

Supported operations: Add, Edit, View, Dup.

Configuration

How do I configure authentication?

Set the Auth section in Config.yaml. Kitto^x supports database-based, text file, and OS-based authentication:

Auth: DB
  ReadUserCommandText: |
    SELECT USER_NAME, PASSWORD_HASH, EMAIL
    FROM USERS WHERE USER_NAME = '{UserName}'

See Authentication.

How do I set up access control?

Use the AccessControl section in Config.yaml with SQL commands that read permissions and roles:

AccessControl: DB
  ReadPermissionsCommandText: |
    SELECT RESOURCE_URI, ACCESS_MODES
    FROM PERMISSIONS WHERE ROLE_ID IN ({RoleList})

See Access Control.

How do I enable logging?

Add a Log section to Config.yaml:

Log:
  Level: 5
  TextFile:
    IsEnabled: True
    FileName: %APP_PATH%log.txt

KIDE (visual editor)

What is KIDE?

KIDE is the visual IDE for designing Kitto^x applications. It provides a tree editor for YAML metadata with context-aware popup menus, database reverse engineering, and syntax verification. See KIDE Introduction.

How does KIDE know which properties a node supports?

KIDE uses RTTI-based discovery: each framework class is annotated with custom Delphi attributes (YamlNode, YamlSubNode, YamlContainer, YamlChildType) that describe its YAML properties. When you right-click a node, KIDE reads these annotations to build the popup menu dynamically. See KIDE YAML Attributes.

How do I add KIDE support for a custom controller?

1. Add {$RTTI EXPLICIT PROPERTIES([vcPublic])} before your class
2. Add EF.YAML.Attributes to the uses clause
3. Annotate each config property with [YamlNode('Path', 'Default', 'Description')]

KIDE will automatically discover the properties via RTTI. See KIDE YAML Attributes — How to annotate.

Deployment

How do I deploy a Kitto^x application?

Compile the application as a VCL executable or Windows service. Deploy the executable, the Home/ directory with all metadata and resources, and any required database drivers. The application includes a built-in HTTP server — no external web server is needed. See Deployment.

Can I run behind a reverse proxy?

Yes. Configure your reverse proxy (nginx, Apache, IIS) to forward requests to the Kitto^x built-in server port. Set Server/Proxy in Config.yaml if the external URL differs from the internal one. See Proxy.

Troubleshooting

My application starts but the browser shows a blank page

Check that:

• The Home/ directory is in the correct location (same directory as the executable, or configured via command line)
• Config.yaml exists and has a valid Server/Port
• The Home View is defined and the Controller value matches a registered controller

Fields are not showing in the form

Ensure the fields are defined in the View's MainTable/Fields section. If you omit the Fields section, all model fields are included by default. If you define Fields, only listed fields are shown.

The filter panel is not visible

Make sure the Filters section is under the Controller node (not at the view level) and that Items contains at least one filter definition with a valid ExpressionTemplate.