Data type management

All data types assignable via the field editor must be explicitly registered. The system uses the metadata provided during registration to:

• generate the database columns storing the values of individual fields,
• configure code generator and field editor behavior,
• perform value conversions (and object mapping for complex types) when fetching data to and from the database.

The following table highlights important types registered by default:

Register custom data types

The default set of data types can be extended, which allows you to register additional data types into the system. To ensure that your data types are available in all scenarios, registration must be done during application startup in the OnPreInit method of a module class.

To register a custom data type, call the RegisterDataTypes(params DataType[]) method of the DataTypeManager class.

The DataType<T> class provides multiple constructors suitable depending on the complexity of the type being registered.

For primitive types and simple objects that can be directly serialized to the database, use

DataType<T>(sqlType: string sqlType,
            fieldType: string fieldType,
            schemaType: string schemaType,
            conversionFunc: Func<object, T, CultureInfo, T> conversionFunc)

where:

• T – generic substituted with the C# type of the data type being registered.
• sqlType – the SQL type of the database column storing the values of the DataType.
• fieldType – the string identifier of the data type in the system. Must be lowercase.
• schemaType – the XSD data type (xs:string, xs:integer, etc.) used for XML serialization into IDataContainer.
• conversionFunc – the function used to convert the stored database value to the data type. Must be static.

For composite types, use 

DataType<T>(sqlType: string sqlType,
            fieldType: string fieldType,
            schemaType: string schemaType,
            conversionFunc: Func<object, T, CultureInfo, T> conversionFunc,
            dbConversionFunc: Func<T, object, CultureInfo, object> dbConversionFunc,
            textSerializer: IDataTypeTextSerializer textSerializer)

where:

• T – generic substituted with the C# type of the data type being registered.
• sqlType – the SQL type of the database column storing the values of the DataType.
• fieldType – the string identifier of the data type in the system. Must be lowercase.
• schemaType – the XSD data type (xs:string, xs:integer, etc.) used for XML serialization into IDataContainer. For composite types, this is commonly set to xs:string, as you’re often storing a serialized object (e.g., as a JSON string).
• conversionFunc – the function used to convert the stored database value to the data type. Must be static.
• dbConversionFunc – the function used to convert the data type to its string representation for storage in the database (e.g., a JSON string). Must be static.

For example, the composite type MyCompositeType:

public class MyCompositeType
{
    public int Identifier { get; set; }
    public string Name { get; set; }
}

would use the following registration:

// Called during module pre-initialization on application startup
protected override void OnPreInit()
{
    DataTypeManager.RegisterDataTypes(
        new DataType<MyCompositeType>("nvarchar(max)", "mydatatype", "xs:string",
                                    MyCompositeTypeHelper.ConvertToSystemRepresentation, 
                                    MyCompositeTypeHelper.ConvertToDbRepresentation, 
                                    new DefaultDataTypeTextSerializer("mydatatype"))
            {
                    // Data type configuration
                    // See the 'Data type configuration' section for details
            }
    );
} 

public static class MyCompositeTypeHelper
{   
    public static object ConvertToDbRepresentation(MyCompositeType value, object defaultValue, CultureInfo _)
    {
        if (value == null)
        {
            return defaultValue;
        }

        try
        {
            return JsonSerializer.Serialize(value);
        }
        catch (Exception e)
        {
            throw new InvalidOperationException("An error occurred when serializing the data type.", e);
        }
    } 

    public static MyCompositeType ConvertToSystemRepresentation(object value, MyCompositeType defaultValue, CultureInfo _)
    {
        if (value == null)
        {
            return defaultValue;
        }

        // We know the value is stored in the database as a JSON string
        var stringValue = value as string;
        if (string.IsNullOrEmpty(stringValue))
        {
            return defaultValue;
        }

        try
        {
            return JsonSerializer.Deserialize<MyCompositeType>(stringValue);
        }
        catch (Exception e)
        {
            throw new InvalidOperationException("An error occurred when deserializing the data type.", e);
        }
    }
}

The data type is now registered and can be assigned to object fields via the field editor. Note that to edit fields based on this data type, you also need to develop corresponding form components.

Data type configuration

During data type registration, you can also configure the following properties that control the behavior of the system when working with the data type in code generators, the field editor, and database queries. 

Field editor

• Hidden – indicates whether the data type is hidden from the field editor interface.
• HasConfigurableDefaultValue – indicates whether the data type needs a configurable default value. Controls the visibility of the default value editor in the field editor interface. See Assign default value editors for custom data types.

Code generators

• TypeAlias – C# type assigned to properties generated from fields based on the data type.
• DefaultValueCode – C# code for the default value of the data type. Provided as a string literal. For example: “String.Empty”

General

• DbType – System.Data.SqlDbType used when generating database queries. Set to the same type as the data type’s sqlType parameter.
• VariableSize – indicates that the type can have variable size. For example, nvarchar(value). If set to true, the field editor interface also offers a Size field that allows users to set the size of the underlying database column.
  • DefaultSize – used when size isn’t provided via the field editor.
• VariablePrecision – indicates that the type can have variable precision (e.g., floats). If set to true, the field editor interface also offers a Precision field that allows users to set the precision of the underlying database column.
  • DefaultPrecision – used when precision isn’t provided via the field editor.

Assign default value editors for custom data types

Most data types assignable via the field editor provide a way to specify a default value for fields of that data type. For custom data types, you can assign a fitting UI form component via RegisterDefaultValueComponent. The method is available in admin module classes (derived from the AdminModule base class) – see Prepare your environment for admin development for more information about admin modules.

The method takes the following parameters:

• dataType – the string identifier of the data type.
• componentIdentifier – the string identifier of the form component used as default value editor.
• Func<object, string> serializationFunction – handles serialization of the form component’s underlying type to it’s string representation.
• Func<string, object> deserializationFunction – handles deserialization from string into the form component’s underlying type.

Call the method during admin module initialization:

using CMS.DataEngine;
using CMS.Helpers;

using Kentico.Xperience.Admin.Base;
using Kentico.Xperience.Admin.Base.Forms;

public class MyAdminModule : AdminModule
{
    public AdminBaseModule()
            : base("My.Xperience.Admin.Module")
    {
    }

    protected override void OnInit()
    {
        base.OnInit();

        // Assigns text input as the default value editor for "mydatatype"
        RegisterDefaultValueComponent("mydatatype", TextInputComponent.IDENTIFIER, 
                                        ValidationHelper.GetValue<string>, value => ValidationHelper.GetValue<string>(value))
    }
}