How to configure new ORM properties and data types

For each ORM framework ORM Designer allows to set up available ORM properties which can be assigned to any object in the model.

This article describes of which types the properties can be, what can be the purposes to their usage in ORM Designer and how to correctly configure them. At the end of article, there is an exemple how to extend current framework with one's own ORM properties or behavior.

Configuration Files

Application configuration files

During the ORM Designer installation, the files defining the individual frameworks support are by default copied into the configuration file. These files describes the frameworks and their properties.

This file is placed in directory

%ORM_Designer_Path%\Config

Warning: User should not change these files because during the next ORM Designer installation they are automatically overwritten by a current version.

User configuration files

User configuration folder serves for user modification and framework extension. All this files will remain also after the reinstalling. Using user configuration files user can extend current framework with new data types, new properties of any object or it serves to add e.g. new behavior. Eventually user can define there also his own ORM framework.

The file with user data is placed at

 %User_Application_Data%\OrmDesignerCore\config

Configuration path

Both paths described above you can find in application configuration in file System Info.

Configuration files validation

During a configuration files loading, an XML validation is performing by XML schema. This schema is also recommended to use during editing XML configurations in your favorite XML editor. The schema is stored at

  %ORM_Designer_Path%\Schema\configuration.xsd

ORM properties options in ORM Designer

As stated in introduction of this article, ORM Designer allows for each framework to define property types, which are possible to set for each single object.

Objects supporting ORM properties

Project
Module
Region
Comment
Table
Column
Index
IndexColumn (*1)
ForeignKey
ForeignKeyColumn (*1)
Many to Many Relation
Many to Many Foreign key (*1)

*1 : Currently in ORM Designer it's not possible to visually edit these properties. The properties are only serialized and internally processed.

Data types of properties

Properties can be composed of elementary data types to more complex structures, lists or sets. Currently ORM Designer supports following data types

Simple	Object	Complex
String	Table	List
Decimal	Column	Set
Float	TableParents	Struct
Bool	TableChildren
Enum

Concrete usage of all properties is described below.

Property definition

Each property definition is described by following options

name: unique name of property type
type: data type of the property,
abstract: tells about the type, that it is only the abstract type, not concrete (this is explained at the end of article),
child-type: in the case of complex object describes type of his child objects
default: initial value of param (*2),
enum-value: establishes that it is an enumeration type with entered values
help: help shown during the property selection
help-url: url adress to website with additional information about the property url (*2)
merge-column: special attribute use for merge multiple objects

*2: These properties are currently supported only on the core ORM Designer level, but aren't shown in GUI.

Example of property definition

As example let's define Doctrine framework and new property "phpName" for model object "TABLE".

The most simple definition of the property looks like this:

<orm-designer-configuration>
    <orm-configuration name="Doctrine">
        <attribute name="TABLE">
            <attribute name="phpName" type="string" help="attribute example"/>
        </attribute>
    </orm-configuration>
</orm-designer-configuration>

After entering this definition the editing in ORM Designer looks like this:

The property data types and their usage

String

Property of this type can contain any text value. During its entering ORM Designer doesn't modify this value neither advise the possible values.

<attribute name="phpName" type="string"/>

Decimal

Property of this type can contain integer value. During its entering ORM Designer checks only the enabled characters.

<attribute name="length" type="decimal"/>

Float

Property of this type can contain float value. During its entering ORM Designer checks only the enabled characters.

<attribute name="positionX" type="float"/>

Bool

Property of this type can contain the values "true" / "false" or not entered. ORM Designer offers all three pre-defined values in combo-box.

<attribute name="unsigned" type="bool"/>

Enum

Property of this type can contain one of pre-defined value. ORM Designer offers all pre-defined values in combo-box, but doesn't allow to enter any other value.

<attribute name="type" type="enum" enum-value="one|many"/>

Table

If some property has type "Table", ORM Designer offers list of the relevant available tables. This type is supported for objects "Project", "Region", "Module" and "Table". In the case of "Region" and "Module" this type offers the tables, which fall into this area. In the case of type "Table" the list of all other tables is offered.

<attribute name="i18nTable" type="Table"/>

Column

If property is a "Column" type, ORM Designer offers the list of available relevant columns. Currently this type is supported only for object "Table", where is offered list of all its colums.

<attribute name="versionColumn" type="column"/>

TableParents and TableChildren

This type offers tables, which are the parent / child tables of chosen object. Currently in ORM Designer this type is supported for types "Table" and "ForeignKey".

<attribute name="BaseTable" type="TableParents"/>

Struct

Property of Struct type is a complex type grouping several properties together. To define this property type there are two possible ways in ORM Designer. The first way is definition directly in the property:

<attribute name="Settings">
    <attribute name="charset" type="string"/>
    <attribute name="collate" type="string"/>
    <attribute name="type" type="string"/>
</attribute>

In this case for <attribute name="Settings"> it is not necessary to define type = "Struct". This option is set automatically. If we want to use some structure more than once, we will define it separately and then just refer to it. This could be done by following definition :

<attribute name="Position" abstract="true">
    <attribute name="x" type="decimal"/>
    <attribute name="y" type="decimal"/>
</attribute>

<attribute name="TABLE">
    <attribute name="PositionFrom" type="struct" child-type="Position"/>
    <attribute name="PositionTo" type="struct" child-type="Position"/>
</attribute>

List

Property of "List" type serves to save organized list of values. Data type of this values is specified by option child-type in attribute definition. Child-type can be any simple type or complex type. Values in data type list are arranged and ORM Designer offers some wizards for ordering these items.

<attribute name="fields" type="list" child-type="column"/>

Set

This attribute offers the list values as well as attribute "List". In contrast to "List" in this case the items are unordered. Child-type can be again the simple or complex type. Type "Set" can be used e.g. for object behavior when we assign concrete behavior to the objects regardless from their order.

<attribute name="actAs" type="set" child-type="Behaviors"/>

<attribute name="Behaviors" abstract="true">
    <attribute name="Versionable">....</attribute>
</attribute>

Comments to property definitons

Abstract attribute for "Struct" / "List" / "Set

If we define the type "Position" without the option abstract = "true", the attribute will be inserted into his parent completely including its name. So when we have following definition (without the option "Abstract)

<attribute name="Position"> <!-- without abstract="true" -->
    <attribute name="x" type="decimal"/>
    <attribute name="y" type="decimal"/>
</attribute>

the difference in property editor is following:

On the left there is a preview of result attributes with correctly set option Abstract. On the right there is a preview without this option.

How to create an own behavior

If you want to add to ORM Designer a new behavior and a new property of the table e.g. for the Doctrine framework, the approach will be following:

1) In directory with the user configuration we will create e.g. user-doctrine.cfg.xml file.

c:\Users\ludek.vodicka\AppData\Roaming\OrmDesignerCore\config\user-doctrine.cfg.xml

2) Into this file we will insert the basic structure of XML configuration which will look like this:

<?xml version="1.0" encoding="utf-8" standalone="no" ?>
   <orm-designer-configuration>
      <orm-configuration name="Doctrine">
   </orm-configuration>
<configuration>

3) Now we will define for an object of type "Table" new property "Rating" of type "Decimal". XML snippet inserting to the XML will look like this:

<orm-configuration name="Without ORM">
    <attribute name="TABLE">
        <attribute name="Rating" type="decimal"/>
    </attribute>
</orm-configuration>

4) Now we want to define a new behavior. All existing behaviors in configuration file for ORM Doctrine (doctrine.cfg.xml) is "encapsuled" in attribute "behavior". This is the reason, why a new behavior has to be added to attribute named "behavior". This can be done by following way:

<attribute name="Behaviors" abstract="true">
    <attribute name="OurNewbehavior">
        <attribute name="StringValue" type="string" />
        <attribute name="DecimalValue" type="decimal" />
    </attribute>
</attribute>

5) The whole XML configuration file will look like this:

<?xml version="1.0" encoding="utf-8" standalone="no" ?>
<orm-designer-configuration xmlns:Atx="http://www.inventic.cz" xmlns:yaml="http://www.inventic.cz/yaml2xml">
    <orm-configuration name="Doctrine">
        <attribute name="TABLE">
            <attribute name="Rating" type="decimal"/>
        </attribute>
        <attribute name="Behaviors" abstract="true">
            <attribute name="OurNewbehavior">
                <attribute name="StringValue" type="string" />
                <attribute name="DecimalValue" type="decimal" />
            </attribute>
        </attribute>
    </orm-configuration>
</orm-designer-configuration>

6) New attributes editing in ORM Designer is shown in following picture.

Conclusion

The question of ORM attributes settings is quite complex. That's why we hope that this article helps you to understand better, how to set up ORM Designer in order to be more helpfull in your everyday work.

If there is something obscure or you have any other questions to the article, you are welcome to contact us.

Author: Ludek Vodicka

visual editor for ORM frameworks