Introduction

This document describes Kitto^x's standard conventions for setting up Delphi, and how to change them for custom setups.

Kickstart a new application

For a quick startup of a new application, you can just:

1. Copy the directory structure of HelloKitto or another example application;
2. Open the project file and save it under a new name;
3. Edit Config.yaml and start creating your own metadata files.

---

When running the compiled application, beware that it will try to run as a service if under an administrator account. To force the application to run with a visible GUI, pass -a as a command line argument.

---

If instead you want a detailed description of what's where and what you can customize, read on.

Details

A Kitto^x application is made up of a Delphi project that you create and maintain, a Home folder with metadata and resources (such as images or javascript files), and a link to the Kitto^x sources or precompiled files.

Standard directory layout

As you can see in the HelloKitto example, a typical folder structure for Delphi 10.2 Tokio goes like this:

• HelloKitto
  • Home
    • Metadata
      • Models
      • Views
      • Config.yaml
    • Resources
      • js
        • application.js
    • Example.exe (the compiled application)
  • Source
  • Projects
    • D12
      • HelloKitto.dproj/dpr (project files)
  • Lib
  • Externals
    • Kitto^x
      • Source
      • Home

Your application code goes into Source and Projects, and the project file should be configured to output the compiled dcu files into subdirectories of Lib:

Unit output directory = ..\..\Lib\$(Version)\D12\$(Platform)

and the exe file into Home:

Output directory = ..\..\Home

This folder contains your yaml metadata and support files as well, and is called the Application Home.

The Application Home path

The Application Home is assumed to the your executable's directory. You can change this (for example when using a single Kitto^x executable to serve different applications) in the following ways:

• By passing a -home argument on the command line.
• By setting the property TKConfig.AppHomePath at application startup.

Finding Kitto^x: The System Home path

Externals\KittoX\Home contains the predefined metadata and support files, such as Kitto^x's default style sheet, CSS, JavaScript libraries, SVG icons, and HTML templates, which are used by your Kitto^x application at run time and you shouldn't need to touch. This is called the System Home.

As you can see, the application needs to have Kitto^x inside its directory structure. This is done to allow different applications to use different versions of the library without stepping on each other's toes, and to make the application as much self-contained as possible.

The project should be configured to find Kitto^x, either in source format:

Search path = ..\..\Externals\KittoX\Source;

..\..\Externals\KittoX\Source\EF;

..\..\Externals\KittoX\Source\ThirdParty;

or in pre-compiled format:

Search path = ..\..\Externals\KittoX\Lib\$(Platform)

---

For the latter version to work, you need to build Externals\KittoX\Projects\D13\KittoXCore.dproj at least once.

---

By default, the System Home is the first existing path in the following list (relative to the executable directory):

..\Externals\KittoX\Home\

..\..\ext\KittoX\Home\

..\..\Externals\KittoX\Home\

..\..\..\KittoX\Home\

..\..\..\..\KittoX\Home\

%KITTOX%\Home\

If none of the paths above exists, then the Application Home is assumed. This allows you to prepare a zero-configuration setup in which the System and Application Home paths are merged in the default Application Home.

Setting up a custom System Home

If you'd like a centralized setup better, you can change that easily, in one of the following ways:

1. You can make KittoX a junction/link so it points to a directory elsewhere. Windows has been supporting file system links for a good while now; you can find a utility to manage them here.
2. If you use Subversion or Git, you can define KittoX as an external/submodule that points to a different repository.
3. You can put Kitto^x elsewhere and change the search path accordingly in the project options. Be warned that this takes care of the KittoX\Source directory, but your application will still need KittoX\Home at run time. If you want to move KittoX\Home elsewhere as well, you will need to do the following at application startup (for example, in a unit's initialization section):

TKConfig.SystemHomePath := 'D:\Path\To\KittoX\Home\';

That's it. You should now be ready to develop and test your Kitto^x applications. We suggest that you stick to the standard conventions unless you have good reasons to do otherwise, because they are designed to save you time and effort in the long run.

Adding YAML files to the Delphi project

The YAML metadata files under Home/Metadata/ are not compiled — dcc32/dcc64 ignores them — but they are part of the application as much as the Pascal sources. We recommend referencing them as <None Include> items in the .dproj, so they show up in the Delphi IDE Project Manager next to the .pas files.

The reason: the KIDEX package (KittoXIDE.bpl) installs a YAML syntax highlighter (KIDE.YAMLHighlighter.pas) into the Delphi IDE. Once the YAML files are part of the project, you can:

• Open them with one click from the Project Manager and edit them with proper YAML syntax highlighting.
• Use Find in Files scoped to "Project files" (or "Open files") to search across .pas and .yaml together — invaluable when looking for a model name, a controller class, a field reference, or a macro across the whole codebase.
• Get back-and-forth navigation between Pascal source and metadata as if they were the same artifact.

How to add them

In the IDE: right-click the project in Project Manager → Add... → select the YAML files. Or edit the .dproj directly: in the same <ItemGroup> that contains the <DCCReference> lines, add one <None Include> entry per file, with paths relative to the project directory:

<DCCReference Include="..\Source\UseKitto.pas"/>
<DCCReference Include="..\Source\Rules.pas"/>
<None Include="..\Home\Metadata\Config.yaml"/>
<None Include="..\Home\Metadata\Views\Home.yaml"/>
<None Include="..\Home\Metadata\Views\MainMenu.yaml"/>
<None Include="..\Home\Metadata\Models\Customer.yaml"/>
<!-- ...one per yaml file under Home/Metadata... -->
<BuildConfiguration Include="Base">

The <None> MSBuild item type is "miscellaneous file, no compile action": the IDE shows them, indexes them for search, but the build system skips them.

Apply to every .dproj

A KittoX application typically ships with several .dproj per app (Standalone, Desktop Embedded, ISAPI, Apache module). Add the same <None Include> block to all of them, so every deployment target shares the same project tree in the IDE. The three sample apps (HelloKitto, TasKitto, KEmployee) already follow this pattern across all four .dproj files each.