class sap.ui.base.DataType

Control sample: sap.ui.base.DataType
Visiblity: public
UX Guidelines:
Implements:
Available since: N/A
Extends:
Module: sap/ui/base/DataType
Application Component: CA-UI5-COR

Represents the type of properties in a ManagedObject class.

Each type provides some metadata like its qualified name or its base type in case of a derived type. Array types provide information about the allowed type of components in an array, enumeration types inform about the set of their allowed keys and values.

Each type has a method to check whether a value is valid for a property of that type.

Already defined types can be looked up by calling DataType.getType, new types can only be created by calling the factory method DataType.createType, calling the constructor will throw an error.


Constructor


Methods Overview

Method Description
sap.ui.base.DataType.createType

Derives a new type from a given base type.

Example:


  var fooType = DataType.createType('foo', {
      isValid : function(vValue) {
          return /^(foo(bar)?)$/.test(vValue);
      }
  }, DataType.getType('string'));

  fooType.isValid('foo'); // true
  fooType.isValid('foobar'); // true
  fooType.isValid('==foobar=='); // false

If mSettings contains an implementation for isValid, then the validity check of the newly created type will first execute the check of the base type and then call the given isValid function.

Array types and enumeration types cannot be created with this method. They're created on-the-fly by DataType.getType when such a type is looked up.

Note: The creation of new primitive types is not supported. When a type is created without a base type, it is automatically derived from the primitive type any.

Note: If a type has to be used in classes tagged with @ui5-metamodel, then the implementation of isValid must exactly have the structure shown in the example above (single return statement, regular expression literal of the form /^(...)$/, calling /regex/.test() on the given value). Only the inner part of the regular expression literal can be different.

getBaseType

The base type of this type or undefined if this is a primitive type.

getComponentType

Returns the component type of this type or undefined if this is not an array type.

getDefaultValue

The default value for this type. Each type must define a default value.

getEnumValues

Returns the object with keys and values from which this enum type was created or undefined if this is not an enum type.

getName

The qualified name of the data type.

getPrimitiveType

Returns the most basic (primitive) type that this type has been derived from.

If the type is a primitive type by itself, this is returned.

sap.ui.base.DataType.getType

Looks up the type with the given name and returns it.

See Defining Control Properties for a list of the built-in primitive types and their semantics.

The lookup consists of the following steps:

  • When a type with the given name is already known, it will be returned
  • When the name ends with a pair of brackets ([]), a type with the name in front of the brackets (name.slice(0,-2)) will be looked up and an array type will be created with the looked-up type as its component type. If the component type is undefined, undefined will be returned
  • When a global property exists with the same name as the type and when the value of that property is an instance of DataType, that instance will be returned
  • When a global property exists with the same name as the type and when the value of that property is a plain object (its prototype is Object), then an enum type will be created, based on the keys and values in that object. The parseValue method of the type will accept any of the keys in the plain object and convert them to the corresponding value; isValid will accept any of the values from the plain object's keys. The defaultValue will be the value of the first key found in the plain object
  • When a global property exist with any other, non-falsy value, a warning is logged and the primitive type 'any' is returned
  • If no such global property exist, an error is logged and undefined is returned

UI Libraries and even components can introduce additional types. This method only checks for types that either have been defined already, or that describe arrays of values of an already defined type or types whose name matches the global name of a plain object (containing enum keys and values). This method doesn't try to load modules that might contain type definitions. So before being able to lookup and use a specific type, the module containing its definition has to be loaded. For that reason it is suggested that controls (or ManagedObject classes in general) declare a dependency to all modules (typically some/lib/library.js modules) that contain the type definitions needed by the specific control or class definition.

isArrayType

Whether this type is an array type.

isEnumType

Whether this type is an enumeration type.

sap.ui.base.DataType.isInterfaceType
isValid

Checks whether the given value is valid for this type.

To be implemented by concrete types.

normalize

Normalizes the given value using the specified normalizer for this data type.

If no normalizer has been set, the original value is returned.

parseValue

Parses the given string value and converts it into the specific data type.

sap.ui.base.DataType.registerInterfaceTypes

Registers the given array of type names as known interface types. Only purpose is to enable the #isInterfaceType check.

setNormalizer

Set or unset a normalizer function to be used for values of this data type.

When a normalizer function has been set, it will be applied to values of this type whenever #normalize is called. ManagedObject.prototype.setProperty calls the normalize method before setting a new value to a property (normalization is applied on-write, not on-read).

The fnNormalize function has the signature

  fnNormalize(value:any) : any
It will be called with a value for this type and should return a normalized value (which also must be valid for the this type). There's no mean to reject a value. The this context of the function will be this type.

This method allows applications or application frameworks to plug-in a generic value normalization for a type, e.g. to convert all URLs in some app-specific way before they are applied to controls. It is not intended to break-out of the value range defined by a type.

sap.ui.base.DataType.createType

Derives a new type from a given base type.

Example:


  var fooType = DataType.createType('foo', {
      isValid : function(vValue) {
          return /^(foo(bar)?)$/.test(vValue);
      }
  }, DataType.getType('string'));

  fooType.isValid('foo'); // true
  fooType.isValid('foobar'); // true
  fooType.isValid('==foobar=='); // false

If mSettings contains an implementation for isValid, then the validity check of the newly created type will first execute the check of the base type and then call the given isValid function.

Array types and enumeration types cannot be created with this method. They're created on-the-fly by DataType.getType when such a type is looked up.

Note: The creation of new primitive types is not supported. When a type is created without a base type, it is automatically derived from the primitive type any.

Note: If a type has to be used in classes tagged with @ui5-metamodel, then the implementation of isValid must exactly have the structure shown in the example above (single return statement, regular expression literal of the form /^(...)$/, calling /regex/.test() on the given value). Only the inner part of the regular expression literal can be different.

Param Type DefaultValue Description
sName string

Unique qualified name of the new type

mSettings object

Settings for the new type

defaultValue any

Default value for the type (inherited if not given)

isValid function

Additional validity check function for values of the type (inherited if not given)

parseValue function

Parse function that converts a locale independent string into a value of the type (inherited if not given)

vBase sap.ui.base.DataType string 'any'

Base type for the new type

getBaseType

The base type of this type or undefined if this is a primitive type.

getComponentType

Returns the component type of this type or undefined if this is not an array type.

getDefaultValue

The default value for this type. Each type must define a default value.

getEnumValues

Returns the object with keys and values from which this enum type was created or undefined if this is not an enum type.

getName

The qualified name of the data type.

getPrimitiveType

Returns the most basic (primitive) type that this type has been derived from.

If the type is a primitive type by itself, this is returned.

sap.ui.base.DataType.getType

Looks up the type with the given name and returns it.

See Defining Control Properties for a list of the built-in primitive types and their semantics.

The lookup consists of the following steps:

UI Libraries and even components can introduce additional types. This method only checks for types that either have been defined already, or that describe arrays of values of an already defined type or types whose name matches the global name of a plain object (containing enum keys and values). This method doesn't try to load modules that might contain type definitions. So before being able to lookup and use a specific type, the module containing its definition has to be loaded. For that reason it is suggested that controls (or ManagedObject classes in general) declare a dependency to all modules (typically some/lib/library.js modules) that contain the type definitions needed by the specific control or class definition.

Param Type DefaultValue Description
sTypeName string

Qualified name of the type to retrieve

isArrayType

Whether this type is an array type.

isEnumType

Whether this type is an enumeration type.

sap.ui.base.DataType.isInterfaceType

Param Type DefaultValue Description
sType string

name of type to check

isValid

Checks whether the given value is valid for this type.

To be implemented by concrete types.

Param Type DefaultValue Description
vValue any

Value to be checked

normalize

Normalizes the given value using the specified normalizer for this data type.

If no normalizer has been set, the original value is returned.

Param Type DefaultValue Description
oValue any

Value to be normalized

parseValue

Parses the given string value and converts it into the specific data type.

Param Type DefaultValue Description
sValue string

String representation for a value of this type

sap.ui.base.DataType.registerInterfaceTypes

Registers the given array of type names as known interface types. Only purpose is to enable the #isInterfaceType check.

Param Type DefaultValue Description
aTypes string[]

interface types to be registered

setNormalizer

Set or unset a normalizer function to be used for values of this data type.

When a normalizer function has been set, it will be applied to values of this type whenever #normalize is called. ManagedObject.prototype.setProperty calls the normalize method before setting a new value to a property (normalization is applied on-write, not on-read).

The fnNormalize function has the signature

  fnNormalize(value:any) : any
It will be called with a value for this type and should return a normalized value (which also must be valid for the this type). There's no mean to reject a value. The this context of the function will be this type.

This method allows applications or application frameworks to plug-in a generic value normalization for a type, e.g. to convert all URLs in some app-specific way before they are applied to controls. It is not intended to break-out of the value range defined by a type.

Param Type DefaultValue Description
fnNormalizer function

Function to apply for normalizing