Views and Controllers

In Kitto^x, a View is a user interface unit; it might be a page or panel, a tabbed panel, a tree, a toolbar, a list or grid panel, and so on. Often, a view is linked to underlying data from the database, in which case it is a more specific concept, a DataView.

In all cases, a View uses a Controller that renders it. While a View is a pure metadata object (implemented by a Delphi class that encapsulates the tree of nodes), a Controller is a Delphi class that generates HTML fragments to render the user interface and manage user interaction through HTMX-powered AJAX calls.

Controller-level properties are specified under the view's Controller subnode, and the set of supported properties depends on the controller type.

All panel-based controllers support common properties like IsModal, Maximized, AllowClose, Width, and Height. See Panel-based Controllers for the full list. Key properties:

• IsModal (True/False): determines whether the view is shown as a dialog overlay or inline in a tab. Default True for Forms, False for Lists.
• AllowClose (True/False): determines whether the view can be closed by the user (X button in dialog, Close button in forms). Default True. Set to False for views that should not be dismissible (e.g. Login).
• Maximized (True/False): forces the dialog to fill the entire viewport. On mobile, this is automatically set to True for all views.

Defining views

Build views visually

KIDE^x's View & Layout Editor edits view YAML in a tree with validation, its DataView Wizard generates a data grid from a Model, and its View Wizard does the same for any of the seven builders below, showing the Yaml before it writes it. The sections below document the underlying YAML.

Yaml file View

A view can be defined in its own yaml file in the Views directory, and referenced where it's used. You can use a view in several places.

Inline View

You can also define a view inline, which is convenient for very simple views you don't need to reference more than once.

Example:

# Refers to Views\MyHomeView.yaml
HomeView: MyHomeView

# Defines the view inline
HomeView:
  Controller: BorderPanel
    CenterView:
      Controller: HtmlPanel
        Html: <h1>Hello World!</h1>

---

The latter example actually defines two inline views, one inside the other, each using its own controller, and also shows the smallest possible self-contained Kitto^x application.

---

Using a ViewBuilder

A ViewBuilder generates a whole DataView from a Model at the moment the view is referenced, so that something you would otherwise write by hand — every field, the detail tables, a free-text search filter — needs no Yaml file at all. It is most useful for data you administer rather than design: parameter and configuration tables, lookup lists, and the one-line menu entry that opens them.

A builder is invoked with the Build verb in place of a view name, and the subnodes of the View node configure it:

# Refers to Taskitto example: Views\MainMenu.yaml
Type: Tree
Folder: Tables
  View: Employees
  View: Build AutoList
    Model: OPERATOR_ROLE
    DisplayLabel: Operator Roles
...

This asks the builder for a DataView over the model OPERATOR_ROLE, with a free search on it. This is the result:

A view built this way is not persistent: it is created in memory the first time the node is resolved, kept for as long as the node lives, and never written to disk. Nothing stops you from starting with a builder and replacing it later with a Yaml file, which is what you do as soon as the view needs anything the builder has no node for.

The available builders

Builder	Produces	Required besides Model	See
AutoList	Controller: List — a data grid	—	List
AutoForm	Controller: Form, in Add operation	—	Form
AutoGroupingList	Controller: GroupingList	GroupingFieldName	GroupingList
AutoTemplateData	Controller: TemplateDataPanel	Template or TemplateFileName	TemplateDataPanel
AutoChart	Controller: List hosting CenterController: ChartPanel	LabelFieldName, ValueFieldName	ChartPanel
AutoCalendar	Controller: List hosting CenterController: CalendarPanel	StartDateFieldName	CalendarPanel
AutoGoogleMap	Controller: GoogleMap	AddressFields	GoogleMap

Model is required, but it is seldom the only one

Only AutoList and AutoForm can be driven by Model alone. The other five have to be told which field does what — nothing in a Model says which column is the date an event starts on, or which number sizes a bar — and they stop with an explicit error when that subnode is missing, instead of building a view that renders nothing. The subnodes specific to each builder are documented on the page of the controller it produces.

The last three rows are worth a second look: where the controller ends up is not the same for all of them. The chart and the calendar are presenters — they need a data context and a filter panel — so they are built as the Center of a List, which is the shape every hand-written chart or calendar view has, and which is what lets a grid sit beside them in a side region over the same rows. The map makes its own context and renders its own sidebar, so it is the view's controller, with no List around it.

Subnodes every builder accepts

Node	Description
Model	Required. The Model the view is built from.
DisplayLabel	The user-visible caption of the view.
DisplayLabel2	The caption used instead of DisplayLabel when the alternate language is in use (see Localization).
ResourceName	The resource name the access control rules are matched against.
Controller	A subtree merged into the generated Controller node — the way to set a controller property the builder has no node of its own for.
MainTable/Fields	An explicit field list, which wins over the one generated from the Model.
MainTable/Controller	A subtree copied to the view table's controller.

What a builder generates

Whatever the kind, the view comes out with Type: Data, a MainTable on the requested Model carrying every field of the Model as a column (unless MainTable/Fields says otherwise), one detail table per detail reference, built recursively, and a FreeSearch filter whose expression covers every visible text field. The two controllers that draw no filter panel of their own — TemplateDataPanel and GoogleMap — have that filter removed again, rather than left in the Yaml doing nothing.

The same builders, materialized as a file

KIDE^x's View Wizard and the view_*_create tools of MCP-KittoX call these very builders and save the result in the Views directory. So a builder is also a fair way to see the Yaml you would have to write: generate it once, then keep the file and edit it. The wizard shows you that Yaml on its last page, before it writes anything.

---

Regardless of how you specify it, a view has some important subnodes. Special types of views have their own special nodes, but all views have a DisplayLabel (user-visible short description) and a Controller.

Controllers

The value of the Controller node specifies its name, while the subnodes configure it. Often the most part of a view definition consists of controller configuration.

Here is a list of currently available controllers. Keep in mind that new controllers are going to be added frequently, and that you can easily create custom controllers and use them to render your views.

Top Level Controllers

The following are top-level controllers, that is controllers that can render autonomously. All other types of controllers need to be (ultimately) nested inside one of these. You must use one of these to render the Home view.

Name	Description
BorderPanel	Hosts from 1 to 5 subviews in a border layout — use as top-level Home View controller

WARNING

The Viewport controller from Kitto1 is deprecated. Use BorderPanel directly as the top-level controller. See Viewport for migration instructions.

Other predefined Controller

Name	Description
TreePanel	Renders a TreeView (a special kind of view that is a tree of subviews) as a visual tree. Useful for menus.
TabPanel	Shows subviews as tabbed panels.
ToolBar	Renders a TreeView as a set of buttons with potentially multi-level menus.
StatusBar	The classic status bar for messages and info.

Data-bound controllers

(all need to render a DataView):

Name	Description
List	Renders a list of records.
Form	Renders a single record (optionally allowing used editing).

Action Controllers

Action controllers are meant to perform operations rather than render something; views using these controllers are usually rendered as buttons or other clickable elements that launch the server-side code embedded inside the controller. Often you create custom controllers to be used this way, but Kitto^x includes several predefined controllers of this type that you can use or inherit from:

Name	Description
URL	Navigates to a given URL (supports macros).
FilteredURL	Navigates to a URL chosen from a set according to filter expressions.
DownloadFile	Downloads an already existing file or one prepared on-demand.

You can see most of these controllers in action in the examples bundled with Kitto^x.