Kitto.Metadata.Models

The model metadata layer. Defines data models (TKModel) mapped to database tables, their fields (TKModelField), detail (master-detail) references, validation rules, and the catalog (TKModels) and registry that manage them. Models are the source of truth for structure and defaults that views build upon.

TKReferenceDataType class

Data type of a reference (foreign-key) field. Its stored value is the referenced model's key.

class function GetTypeName: string;

Returns the type name under which this data type is registered ('Reference').

function GetDefaultEmptyAsNull: Boolean;

Default value of EmptyAsNull for reference fields.

function SupportsEmptyAsNull: Boolean;

Returns True: reference fields support the EmptyAsNull setting.

TKRule class

A single validation/business rule attached to a model or field.

TKHTMLEditorConfig class

Configuration for the SunEditor rich-text toolbar on HTMLMemo fields. YAML path: Field/HTMLEditor

HTMLEditor:
EnableFont: True
EnableFontSize: True
EnableFormat: True
EnableColors: True
EnableAlignments: True
EnableLinks: True
EnableLists: True
EnableSourceEdit: True

TKThumbnailConfig class

Thumbnail dimensions for IsPicture blob fields. YAML path: Field/IsPicture/Thumbnail

IsPicture: True
Thumbnail:
Width: 150
Height: 150

TKPreviewWindowConfig class

Preview window dimensions for FileReference fields. YAML path: Field/PreviewWindow

PreviewWindow: True
Width: 226
Height: 320

TKRules class

property RuleCount: Integer read GetRuleCount;

Number of rules in the collection.

property Rules[const AIndex: Integer]: TKRule read GetRule;

The rules, by index (default property).

function HasRule(const ARule: TKRule): Boolean;

Returns True if there's a rule of the same type as the passed one.

TKModelField class

function GetEmptyAsNull: Boolean;

Returns the effective EmptyAsNull setting for this field.

procedure BeforeSave;

Housekeeping performed before the field is saved to YAML.

function GetResourceURI: string;

The access-control resource URI identifying this field.

property Model: TKModel read GetModel;

The model this field belongs to.

property FieldName: string read GetFieldName;

The field's logical name.

property DBColumnName: string read GetDBColumnName;

Returns the PhysicalName or, if not specified, the FieldName.

property DBColumnNameOrExpression: string read GetDBColumnNameOrExpression;

The DB column name, or the SQL expression for a computed field.

property AliasedDBColumnName: string read GetAliasedDBColumnName;

Returns the physical column name (DBColumnName) plus, if the field has a different logical name, a space and the logical name (FieldName).

property AliasedDBColumnNameOrExpression: string read GetAliasedDBColumnNameOrExpression;

AliasedDBColumnName, or the SQL expression for a computed field.

property FieldNameOrExpression: string read GetFieldNameOrExpression;

The field name, or the SQL expression for a computed field.

property QualifiedDBColumnName: string read GetQualifiedDBColumnName;

The DB column name prefixed with the table name (table.column).

property QualifiedDBColumnNameOrExpression: string read GetQualifiedDBColumnNameOrExpression;

QualifiedDBColumnName, or the SQL expression for a computed field.

property DataType: TEFDataType read GetDataType;

The field's data type.

function GetActualDataType: TEFDataType;

Returns the DataType. For reference fields, returns the referenced field's actual data type (recursively).

property Size: Integer read GetSize;

The field size (e.g. string length); 0 when not applicable.

property ParentField: TKModelField read GetParentField;

If the field is contained (as with local children of a reference fields), returns the parent field, otherwise nil.

property IsContained: Boolean read GetIsContained;

Returns True if the field has a ParentField.

property IsReference: Boolean read GetIsReference;

True if the field is a reference.

property DefaultFilter: string read GetDefaultFilter;

Optional filter to use when creating select lists. Only applies to reference fields.

property LookupFilter: string read GetLookupFilter;

Optional filter to use when creating lookup lists. Only applies to reference fields.

property DefaultFilterConnector: string read GetDefaultFilterConnector;

Specifies the logical connector to use when appending the DefaultFilter to an existing WHERE clause (for example, a referenced model's own DefaultFilter). Defaults to 'and'; another common value is 'or'.

property FieldCount: Integer read GetFieldCount;

If the field is part of a reference field, returns the number of physical fields that make up the reference.

property Fields[I: Integer]: TKModelField read GetField;

If the field is part of a reference field, returns the physical fields that make up the reference.

property FieldList: TKModelFields read GetFields;

The sub-fields collection (the constituent fields of a reference field). Exposed for RTTI discovery of the YAML 'Fields' container.

function FieldByName(const AName: string): TKModelField;

Returns the sub-field with the given name; raises if absent.

function FindField(const AName: string): TKModelField;

Returns the sub-field with the given name, or nil.

function FindFieldByPhysicalName(const APhysicalName: string): TKModelField;

Returns the sub-field with the given physical (DB) name, or nil.

function FindFieldByPredicate(const APredicate: TKModelFieldPredicate): TKModelField;

Returns the first sub-field satisfying APredicate, or nil.

function GetFieldNames: TStringDynArray;

Returns the names of the sub-fields, if any.

function GetDBColumnNames: TStringDynArray;

Returns the DB names of the sub-fields, if any.

property ReferencedModelName: string read GetReferencedModelName;

If the field is a reference, returns the referenced model's name, otherwise ''.

property ReferencedModel: TKModel read GetReferencedModel;

If the field is a reference, returns the referenced model, otherwise nil.

property ReferenceFieldNames: TStringDynArray read GetReferenceFieldNames;

If the field is a reference, returns the reference field names (that is the names of the fields, in the underlying table, that make up the foreign key to the referenced model).

function GetReferenceFields: TKModelFieldArray;

If the field is a reference, returns an array of its subfields (that is the fields, in the underlying table, that make up the foreign key to the referenced model).

property IsRequired: Boolean read GetIsRequired;

Default requiredness status of this field in views. Defaults to the database nullability status of the column.

property IsVisible: Boolean read GetIsVisible;

Default visibility status of this field in views. Defaults to True.

property IsReadOnly: Boolean read GetIsReadOnly;

Default read-only status of this field in views. Defaults to False.

property IsComputed: Boolean read GetIsComputed;

A field computed on server side. At client side is not editable. Defaults to False. </summary

property IsGenerated: Boolean read GetIsGenerated;

Returns True if the field is auto-generated at the database level, such as an auto-increment field. Default is False.

property Expression: string read GetExpression;

A field that is not a physical field but rather computed by a SQL expression will have the expression stored in this property.

property CanInsert: Boolean read GetCanInsert;

Returns True if the field can be modified when inserting a new record. By default all fields for which CanActuallyModify returns True are editable, but you can makle a field non editable during insert by adding 'CanInsert: False' to its definition. You can't make editable a field that is naturally non editable, such as an expression field.

property CanUpdate: Boolean read GetCanUpdate;

Returns True if the field can be modified when editing an existing record. By default all fields for which CanActuallyModify returns True are editable, but you can makle a field non editable during update by adding 'CanUpdate: False' to its definition. You can't make editable a field that is naturally non editable, such as an expression field.

function CanActuallyModify: Boolean;

Returns True if a field is natually editable. All fields except expression fields are currently considered natually editable.

property EmptyAsNull: Boolean read GetEmptyAsNull;

Indicates that an empty value input by the user should be converted to null when writing to the database. For string/date/time/datetime fields defaults to True; for other data types defaults to False.

Only relevant for string/date/time/datetime fields. In other cases, empty values are always converted to null. If the field is not of one of these types, this property always returns True.

If the field has a parent field, then the parent field's EmptyAsNull is returned (IOW setting EmptyAsNull on fields that are part of other fields, such as in multi-column reference fields, is ineffective. You set it once for all in the parent field).

property AllowedValues: TEFPairs read GetAllowedValues;

If the field has a fixed list of allowed values, it is stored here. Each value has as an associated label. Only string fields are currently supported.

property NotifyChange: Boolean read GetNotifyChange;

When True, editing this field triggers the server-side change cascade (onchange notification). Read from the model field or overridden on the view field.

property Colors: string read GetColors;

Conditional cell colouring: each child is <hex-color>: <regexp>; the value is coloured with the first colour whose regexp matches it.

property AutoAddFields: string read GetAutoAddFields;

RTTI carrier for the AutoAddFields node: extra fields pulled in automatically when this reference field is selected. Read by path.

property DisplayLabel: string read GetDisplayLabel;

Default label for this field in views. Defaults to a beautified field name. The beautifying function can be customized.

property DisplayLabel_Grid: string read GetDisplayLabel_Grid;

Default label for this field in Grid/List. If not present uses the value of DisplayLabel.

property DisplayLabel_Form: string read GetDisplayLabel_Form;

Default label for this field in Form. If not present uses the value of DisplayLabel.

property Hint: string read GetHint;

Default label for this field into editing control when the value is missing

property DisplayWidth: Integer read GetDisplayWidth;

Default width for this field in views. Defaults to the field size for string fields, and reasonable sizes for other field types.

property DisplayTemplate: string read GetDisplayTemplate;

A string format that will be used to render the field's value. may include the {value} placeholder that will be replaced with the field's value in read-only GUIs, and any {FieldName} placeholders for other fields' values. A template of '{value}' acts the same as no template.

property BlankValue: Boolean read GetBlankValue;

Indicates to hide the field value when an image is displayed (otherwise both image and value are shown). If no image is displayed, this property is ignored.

property AutoCompleteMinChars: Integer read GetAutoCompleteMinChars;

Indicates how many chars must be edited before the search starts. By default after 4 characters

property DefaultValue: Variant read GetDefaultValue;

Optional value to set for the field when a new record is created.

property DefaultDisplayWidth: Integer read GetDefaultDisplayWidth;

Returns the default Display Width based on the DataType

property DefaultDisplayLabel: string read GetDefaultDisplayLabel;

Returns the default Display label of the field as a beautified value of FieldName

property DefaultEmptyAsNull: Boolean read GetDefaultEmptyAsNull;

Returns the default value form EmptyAsNull based on the DataType

property FileNameField: string read GetFileNameField;

For blob or file reference fields, optionally specifies the name of another field in the same model that will store the original file name upon upload.

function GetFilterByFields: TArray<TKFilterByField>;

For a reference field with FilterBy nodes, returns the (field, foreign-field) pairs that constrain the lookup by the value of another field in the same model.

TKModelFields class

function FieldByName(const AName: string): TKModelField;

Returns the field with the given name; raises if absent.

function FindField(const AName: string): TKModelField;

Returns the field with the given name, or nil.

function FindFieldByPhysicalName(const APhysicalName: string): TKModelField;

Returns the field with the given physical (DB) name, or nil.

function FindFieldByPredicate(const APredicate: TKModelFieldPredicate): TKModelField;

Returns the first field satisfying APredicate, or nil.

property FieldCount: Integer read GetFieldCount;

Number of fields.

property Fields[I: Integer]: TKModelField read GetField;

The fields, by index (default property).

function GetFieldNames: TStringDynArray;

Returns all field names, in order.

function GetDBColumnNames: TStringDynArray;

Returns all fields' DB column names, in order.

property ParentField: TKModelField read GetParentField;

If the fields are contained inside a parent field, this property returns the parent field, otherwise nil.

TKModelSubobject class

Base class for objects contained in a model (e.g. detail references).

property Model: TKModel read GetModel;

The model this sub-object belongs to.

TKModelDetailReference class

A master-detail reference from a model to a detail (child) model, identifying the child model and the foreign-key field that links back to this master model.

The node's own value is the detail model's name:

DetailReferences: Invitation: Invitation CascadeDelete: True

Everything else is a child of it -- CascadeDelete above is a child of Invitation, not a sibling. Written one level out it becomes a detail reference of its own, named CascadeDelete, and is silently ignored as a setting.

The nodes below carry [YamlNode] so KIDE and the MCP server know them. TYamlAttributeReader reads the whole set at once and a class that declares none is not checked at all (see KIDE.TreeValidator), so adding one means declaring them all.

property PhysicalName: string read GetPhysicalName;

The detail reference's physical (DB foreign-key) name.

property DBForeignKeyName: string read GetDBForeignKeyName;

Returns PhysicalName.

property DisplayLabel: string read GetDisplayLabel;

Label shown for the detail table (defaults to a beautified name).

property DetailReferenceName: string read GetDetailReferenceName;

The detail reference's logical name.

property DetailModel: TKModel read GetDetailModel;

The detail (child) model.

property DetailModelName: string read GetDetailModelName;

Name of the detail (child) model.

property ReferenceField: TKModelField read GetReferenceField;

Returns the counterpart reference field in the detail model. If there's only one reference field from the detail model to this master model, then it's assumed it is the one being looked for, otherwise its name is fetched from the ReferenceField parameter of the DetailReference.

property ReferenceFieldName: string read GetReferenceFieldName;

Name of the counterpart reference field in the detail model.

property CascadeDelete: Boolean read GetCascadeDelete;

Whether deleting a master deletes the rows of this detail along with it. False unless the model says otherwise.

Off by default on purpose: on by default would make one delete take an unknown number of rows with it, in every application, without anyone having asked. An application that wants it says so, per relation:

DetailReferences: Invitation: Invitation CascadeDelete: True

Where it is not said the delete is refused, with a message that names the master and counts the rows holding it back instead of quoting a constraint name at the user.

TKModelDetailReferences class

property DetailReferences[I: Integer]: TKModelDetailReference read GetDetailReference;

The detail references, by index (default property).

property DetailReferenceCount: Integer read GetDetailReferenceCount;

Number of detail references.

function DetailReferenceByName(const AName: string): TKModelDetailReference;

Returns the detail reference with the given name; raises if absent.

function FindDetailReference(const AName: string): TKModelDetailReference;

Returns the detail reference with the given name, or nil.

function FindDetailReferenceToModel(const AModel: TKModel): TKModelDetailReference;

Returns the detail reference pointing to the given model, or nil.

function FindDetailReferenceToModel(const AModelName: string): TKModelDetailReference;

Returns the detail reference pointing to the named model, or nil.

function FindDetailReferenceToField(const AField: TKModelField): TKModelDetailReference;

Returns the detail reference whose FK is the given field, or nil.

function FindDetailReferenceByPhysicalName(const APhysicalName: string): TKModelDetailReference;

Returns the detail reference with the given physical (FK) name, or nil.

TKModel class

procedure BeforeSave;

Housekeeping performed before the model is saved to YAML (e.g. drops an empty DetailReferences node).

property Catalog: TKModels read GetCatalog;

The models catalog this model belongs to.

property DefaultPluralModelName: string read GetDefaultPluralModelName;

The default plural model name (the English plural of ModelName).

property PluralModelName: string read GetPluralModelName;

Plural form of ModelName. This is an identifier, not a caption: its only consumer is TKViewTableRecords.GetXMLTagName, which uses it as the name of the XML element wrapping a record set in TKRecords.GetAsXML (read by the XML export and FOP report tools). Do not localize it - the plural caption is PluralDisplayLabel.

property DefaultPhysicalName: string read GetDefaultPhysicalName;

The default physical name (the ModelName) when PhysicalName is not set.

property DBTableName: string read GetDBTableName;

Returns the physical database table name (PhysicalName property) or, if not specified, the ModelName. It is the name to be used to update the physical table.

property DefaultDisplayLabel: string read GetDefaultDisplayLabel;

The default display label (a beautified ModelName).

property DefaultPluralDisplayLabel: string read GetDefaultPluralDisplayLabel;

The default plural display label (the English plural of DisplayLabel).

property DefaultImageName: string read GetDefaultImageName;

The default icon name when ImageName is not set.

property FieldCount: Integer read GetFieldCount;

Number of first-level fields in the model.

property Fields[I: Integer]: TKModelField read GetField;

The first-level fields, by index.

property FieldList: TKModelFields read GetFields;

The fields collection. Exposed (in addition to the indexed accessor) so the YAML 'Fields' container is discoverable via RTTI by the tree validator and the KIDE/MCP metadata tooling.

function FieldByName(const AName: string): TKModelField;

Returns the field with the given name; raises if absent.

function FindField(const AName: string): TKModelField;

Returns the field with the given name, or nil.

function FindFieldByPhysicalName(const APhysicalName: string): TKModelField;

Returns the field with the given physical (DB) name, or nil.

procedure EnumFields(const AProc: TProc<TKModelField>);

Calls AProc for all first-level fields in the model.

procedure EnumPhysicalFields(const AProc: TProc<TKModelField>);

Calls AProc for all first-level fields in the model except fields with subfields (such as reference fields). In such cases, calls AProc for each subfield and never for the parent field.

function GetKeyFieldNames: TStringDynArray;

Returns an array of key field names. Throws an exception if no primary key is defined.

function GetKeyDBColumnNames(const AQualify: Boolean = False;

Returns an array of key physical field names.

Parameters:

• AQualify — If True, each field name is prefixed with the table name and a dot.
• AAlias — If True, makes it so that every field that has a different physical name is aliased (meaning the physical name is output, followed by a space and the FieldName).

property KeyFieldCount: Integer read GetKeyFieldCount;

Number of fields that make up the primary key.

property KeyFields[I: Integer]: TKModelField read GetKeyField;

The primary-key fields, by index.

property DetailReferenceCount: Integer read GetDetailReferenceCount;

Number of detail (master-detail) references.

property DetailReferences[I: Integer]: TKModelDetailReference read GetDetailReference;

The detail references, by index.

property DetailReferenceList: TKModelDetailReferences read GetDetailReferences;

The detail references collection. Exposed (in addition to the indexed accessor) so the YAML 'DetailReferences' container is discoverable via RTTI by the tree validator and the KIDE/MCP metadata tooling.

function DetailReferenceByName(const AName: string): TKModelDetailReference;

Returns the detail reference with the given name; raises if absent.

function FindDefaultCaptionField: TKModelField;

Returns the default caption field (heuristic), or nil.

function FindCaptionField: TKModelField;

Returns the caption field (CaptionField node, else default), or nil.

function FindDetailReference(const AName: string): TKModelDetailReference;

Returns the detail reference with the given name, or nil.

function FindDetailReferenceByPhysicalName(const APhysicalName: string): TKModelDetailReference;

Returns the detail reference with the given physical (FK) name, or nil.

function FindDetailReferenceByModel(const AModel: TKModel): TKModelDetailReference;

If there's exactly one detail reference to the specified model, returns it, otherwise returns nil.

function FindDetailReferenceByModelName(const AModelName: string): TKModelDetailReference;

If there's exactly one detail reference to the model with the specified name, returns it, otherwise returns nil.

function FindDetailReferenceByField(const AField: TKModelField): TKModelDetailReference;

Returns the first found detail reference to the specified reference field. If not found, returns nil.

function FindReferenceField(const AModel: TKModel): TKModelField;

If there's exactly one field referencing the specified model, it is returned. Otherwise the method returns nil.

function FindReferenceField(const AModelName: string;

Finds and returns a field referencing a model with the specified name and all subfields listed in the specified field name array (and only these), otherwise nil.

If AFieldNames contains only one item, a same-named reference field with no subfields does qualify as a return value. If AFieldNames contains several items (indicating a multi-field reference) then the name of the field does not matter and only the subfields contribute.

Parameters:

• AModelName — Name of the referenced model.
• AFieldNames — Names of the referencing fields.

function FindReferenceField(const AForeignKeyName: string): TKModelField;

If a reference field with a ForeignKeyName property equals to the specified name exists, it is returned. Otherwise nil is returned.

Not all reference fields have a ForeignKeyName set.

Parameters:

• AForeignKeyName — Name of the database-level foreign key.

property PreventAdding: Boolean read GetPreventAdding;

Model-level default that prevents adding records. The REST API honors it (POST -> 405); a view Controller/PreventAdding overrides it for the GUI only (view-if-specified else this model default).

property PreventEditing: Boolean read GetPreventEditing;

Model-level default that prevents editing records. The REST API honors it (PUT/PATCH -> 405); a view Controller/PreventEditing overrides it for the GUI only.

property PreventDeleting: Boolean read GetPreventDeleting;

Model-level default that prevents deleting records. The REST API honors it (DELETE -> 405); a view Controller/PreventDeleting overrides it for the GUI only.

property IsLarge: Boolean read GetIsLarge;

True if the model's underlying data store is a large one. Used to decide the kind of lookup combo box to create. Se this to True if the cardinality of the underlying database table exceeds what you are comfortable to put in an Ajax response (typically a few hundred records, depending on the number and size of columns).

property DefaultSorting: string read GetDefaultSorting;

Optional fixed ORDER BY expression to apply when building the select SQL statement to display data. Should refer to fields through qualified names. Defaults to the list of fields in the key, if any.

property DefaultDefaultSorting: string read GetDefaultDefaultSorting;

The fallback sort expression (the key fields) when DefaultSorting is not set.

property LookupSorting: string read GetLookupSorting;

Optional fixed ORDER BY expression to apply when building the select SQL statement for lookup. Should refer to fields through qualified names. Defaults CaptionField.DBColumnNameOrExpression

property DefaultCaptionField: TKModelField read GetDefaultCaptionField;

The heuristic default caption field (first string key/field).

property CaptionField: TKModelField read GetCaptionField;

The field used as the model's display caption.

function LoadRecords(const AStore: TEFTree;

Loads a set or a page of records into the specified store.

Parameters:

• AStore — Instance of the store to populate. May be (will probably be) an instance?of an inherited class.
• AFilterExpression — Optional filter expression. It is commonly a SQL predicate, but it suffices that it is meaningful to the particular model class.
• ASortExpression — Optional?sort expression. It is commonly a SQL ORDER BY clause, but it suffices that it is meaningful to the particular model class.
• AStart — Optional: First record to load. If both this argument and ALimit are 0, all records matching the filter are loaded, otherwise only a page starting from this record and ALimit records long tops.
• ALimit — Maximum number of records to load. It is the page size. Pass 0 in both this argument and AStart to load all records matching the filter.

Returns: Count of actually loaded records.

procedure SaveRecords(const AStore: TEFTree;

Persists all records in AStore (insert/update/delete per record state), optionally in a single transaction; calls AAfterPersist on success.

procedure SaveRecord(const ARecord: TEFNode;

Saves the specified record.

In case of errors, this method raises exceptions and does not call AAfterPersist.

Parameters:

• ARecord — Instance of the record to save. May be (will probably be) an instance of an inherited class.
• APersist — If True, the record is to be persisted to the underlying data store, otherwise it should only be prepared now and persisted later (for example, when saving a detail record this argument is False).
• AAfterPersist — A procedure to be called after successfully persisting the record. It will only be called if APersist is True and the save goes well.

procedure BeforeNewRecord(const ARecord: TEFNode;

Called when a new record is being created in the GUI, after applying any default or cloned values but before applying new record rules.

Parameters:

• ARecord — Instance of the record just created. May be (will probably be) an instance of an inherited class.
• AIsCloned — If True, the record was created as a result of a clone operation, which means it should contain values; otherwise it is empty except for the default values.

procedure AfterNewRecord(const ARecord: TEFNode);

Called when a new record has been created in the GUI, after applying any default or cloned values and new record rules.

Parameters:

• ARecord — Instance of the record just created. May be (will probably be) an instance of an inherited class.

TKModelList class

A simple list of models.

procedure AddModelNamesToStrings(const AStrings: TStrings);

Adds the name of each model in the list to AStrings.

TKModels class

The catalog of all models, loaded from the Models/ directory.

class procedure ResetDefaultModelClassType;

Resets DefaultModelClassType to the framework default (TKModel).

property ModelCount: Integer read GetModelCount;

Number of models in the catalog.

property Models[I: Integer]: TKModel read GetModel;

The models, by index (default property).

function ModelByName(const AName: string): TKModel;

Returns the model with the given name; raises if absent.

function FindModel(const AName: string): TKModel;

Returns the model with the given name, or nil.

function ModelByNode(const ANode: TEFNode): TKModel;

Returns the model referenced by the given node; raises if absent.

function FindModelByNode(const ANode: TEFNode): TKModel;

Returns the model referenced by the given node, or nil.

function FindModelByPhysicalName(const APhysicalName: string): TKModel;

Returns a reference to the first found model with the specified physical name. If a model has no custom physical name specified, the (case insensitive) match is done on its name instead.

procedure GetModelList(const AList: TKModelList);

Reads the Models/ directory from disk and fills AList with all models found. AList is cleared first. If the catalog is not yet open it calls Open; if already open it calls Refresh, so each call reflects the current on-disk state.

TKModelRegistry class

Singleton registry mapping type ids to model classes.

function GetClass(const AId1, AId2: string): TKModelClass;

Returns the registered model class for the given id(s).

Routines

function EvalExpression(const AExpression: Variant): Variant;

Returns the input value unless it's a supported literal, in which case evaluates the literal and returns it. Used by model and view fields to compute default values.

function Pluralize(const AName: string): string;

Returns the English plural of AName (used to derive PluralModelName).