com.smartgwt.client.docs.serverds

## Class SimpleType

- java.lang.Object
- - com.smartgwt.client.docs.serverds.SimpleType

-     public class SimpleType
      extends java.lang.Object

  An atomic type such as a string or number, that is generally stored, displayed and manipulated as a single value.

  This class is not meant to be created and used, it is actually documentation of settings allowed in a DataSource descriptor (.ds.xml file), for use with Smart GWT Pro Edition and above. See `com.smartgwt.client.docs.serverds` for how to use this documentation.

  SimpleTypes can be created at any time, and subsequently referred to as a `field type` in `DataSources` and `DataBoundComponents`. This allows you to define `validation`, `formatting` and `editing` behaviors for a type to be reused across all `DataBoundComponents`.

  The SimpleType class also allows data to be stored in some opaque format but treated as simple atomic values as far as Smart GWT components are concerned by implementing `getAtomicValue()` and `updateAtomicValue()` methods. For example, if some record has a field value set to a javascript object with the following properties:

        { stringValue:"A String", length: 9 }

  this value could be treated as a simple string by defining a SimpleType with `inheritsFrom` set to `"text"` and a custom `getAtomicValue()` method that simply extracted the "stringValue" attribute from the data object. DataBoundComponents would then display the string value, and use it for sorting and other standard databinding features.

  Note that the term "simpleType" is used in the same sense as in XML Schema, and `XMLTools.loadXMLSchema()` will create new SimpleType definitions.

  When using the Smart GWT Server, SimpleTypes can be defined server-side, and should be defined server-side if validators are going to be declared so that the server will enforce validation. To define server-side SimpleTypes using Component XML you should create file {typeName}.type.xml in the following format:

          <SimpleType name="{typeName}" inheritsFrom="{otherSimpleType}"
                         editorType="{FormItemClassName}">
            <validators>
              <!-- validator definition just like DataSourceField -->
            </validators>
          </SimpleType>

  .. and place this file alongside your DataSource files (.ds.xml) files - in any of folders listed in `project.datasources` property in `server.properties`.

  SimpleTypes can be loaded via DataSourceLoader or `loadDS JSP tags` and should be loaded before the definitions of any DataSources that use them (so generally put all SimpleType definitions first).

  Define validators in the server-side type definition, for example:

          <SimpleType name="countryCodeType" inheritsFrom="text">
            <validators>
              <validator type="lengthRange" min="2" max="2"
                errorMessage="Length of country code should be equal to 2." />
              <validator type="regexp" expression="[A-Z][A-Z]"
                errorMessage="CountryCode should have only uppercase letters." />
            </validators>
          </SimpleType>

  For client-side formatters, add these to the type definition after loading it from the server, for example:

            SimpleType.getType("independenceDateType").setShortDisplayFormatter(new SimpleTypeFormatter() {
              public String format(Object value, DataClass field, DataBoundComponent component, Record record) {
                if (value == null) return null;
                return "<i>" + (((java.util.Date) value).getYear() + 1900) + "</i>";
              }
            });

  Note that formatters must be added to the SimpleType definition before any DataBoundComponent binds to a DataSource that uses the SimpleType.

  An example is here.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `java.lang.Boolean` | `canEdit` Default value for `DataSourceField.canEdit` for fields of this type.
    `java.lang.Boolean` | `canFilter` Default value for `DataSourceField.canFilter` for fields of this type.
    `java.lang.String` | `defaultGroupingMode` In components that support grouping, the default mode from the available `groupingModes` to use when grouping values of this type.
    `OperatorId` | `defaultOperator` The default `search-operator` for this data-type.
    `FormItem` | `editorType` Classname of the FormItem that should be the default for editing values of this type (eg "SelectItem").
    `FormatString` | `exportFormat` `FormatString` used during exports for numeric or date formatting.
    `DataSourceField` | `fieldProperties` These are properties that are essentially copied onto any DataSourceField where the property is applied.
    `FormItem` | `filterEditorType` Classname of the FormItem that should be used to edit values of this type if it appears in a filter row.
    `FormatString` | `format` `FormatString` for numeric or date formatting.
    `java.util.Map` | `groupingModes` A set of key-value pairs that represent the names and titles of the grouping modes available to values of this type, for use in components that support grouping.
    `Identifier` | `inheritsFrom` Name of another SimpleType from which this type should inherit.
    `Identifier` | `name` Name of the type, used to refer to the type from `field.type`.
    `ReadOnlyDisplayAppearance` | `readOnlyDisplay` Default `readOnlyDisplay` for fields of this type.
    `FormItem` | `readOnlyEditorType` Classname of the FormItem that should be used to display values of this type when a field is marked as `canEdit false` and the field is displayed in an editor type component like a DynamicForm.
    `Validator[]` | `validators` Validators to apply to value of this type.
    `OperatorId[]` | `validOperators` Set of `search-operators` valid for this `SimpleType`.
    `java.util.Map` | `valueMap` List of legal values for this type, like `DataSourceField.valueMap`.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SimpleType()`

  - ### Method Summary

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### readOnlyDisplay

          public ReadOnlyDisplayAppearance readOnlyDisplay

      Default `readOnlyDisplay` for fields of this type.

      For more sophisticated management of read-only behavior, see `readOnlyEditorType`.

      Default value is null

    - #### groupingModes

          public java.util.Map groupingModes

      A set of key-value pairs that represent the names and titles of the grouping modes available to values of this type, for use in components that support grouping.

      Some types provide a set of builtin groupingModes, as covered `here`.

      Use `setGroupValueFunction()` and `setGroupTitleFunction()` to implement custom grouping logic for each of the grouping modes you provide.

      Default value is null

    - #### inheritsFrom

          public Identifier inheritsFrom

      Name of another SimpleType from which this type should inherit.

      Validators, if any, will be combined. All other SimpleType properties default to the inherited type's value.

      Default value is null

    - #### name

          public Identifier name

      Name of the type, used to refer to the type from `field.type`.

      Default value is null

    - #### validOperators

          public OperatorId[] validOperators

      Set of `search-operators` valid for this `SimpleType`.

      If not specified, the `inherited` type's operators will be used, finally defaulting to the default operators for the basic types (eg, integer).

      Default value is null

      See Also:
        `AdvancedFilter overview and related methods`

    - #### readOnlyEditorType

          public FormItem readOnlyEditorType

      Classname of the FormItem that should be used to display values of this type when a field is marked as `canEdit false` and the field is displayed in an editor type component like a DynamicForm.

      May be overridden by `DataSourceField.readOnlyEditorType`.

      Default value is null

    - #### canFilter

          public java.lang.Boolean canFilter

      Default value for `DataSourceField.canFilter` for fields of this type.

      This impacts client-side behavior only and may be used to explicitly enable editing in filter interfaces, even if `editing is disabled`.

      This property is set to true for the "sequence" SimpleType by default.

      Default value is null

    - #### editorType

          public FormItem editorType

      Classname of the FormItem that should be the default for editing values of this type (eg "SelectItem").

      You can create a simple custom FormItem by adding default `FormItem.icons` that launch custom value picking dialogs (an example is in the QuickStart Guide, Chapter 9, Extending Smart GWT). By setting simpleType.editorType to the name of your custom FormItem, forms will automatically use the custom FormItem, as will grids performing `inline editing`.

      Default value is null

    - #### valueMap

          public java.util.Map valueMap

      List of legal values for this type, like `DataSourceField.valueMap`.

      Default value is null

    - #### defaultGroupingMode

          public java.lang.String defaultGroupingMode

      In components that support grouping, the default mode from the available `groupingModes` to use when grouping values of this type.

      Default value is null

    - #### canEdit

          public java.lang.Boolean canEdit

      Default value for `DataSourceField.canEdit` for fields of this type.

      This impacts client-side behavior only and is a way to simply disallow editing of this field type by default within `editors`.

      This property is set to false for the "sequence" SimpleType by default.

      Default value is null

    - #### exportFormat

          public FormatString exportFormat

      `FormatString` used during exports for numeric or date formatting. See `DataSourceField.exportFormat`.

      Default value is null

      See Also:
        `ExportFormatting overview and related methods`

    - #### filterEditorType

          public FormItem filterEditorType

      Classname of the FormItem that should be used to edit values of this type if it appears in a filter row.

      May be overridden by `DataSourceField.filterEditorType`.

      Default value is null

    - #### fieldProperties

          public DataSourceField fieldProperties

      These are properties that are essentially copied onto any DataSourceField where the property is applied. The supported properties are only client-side properties.

      Default value is null

    - #### defaultOperator

          public OperatorId defaultOperator

      The default `search-operator` for this data-type.

      Default value is null

      See Also:
        `AdvancedFilter overview and related methods`

    - #### format

          public FormatString format

      `FormatString` for numeric or date formatting. See `DataSourceField.format`.

      Default value is null

      See Also:
        `ExportFormatting overview and related methods`

    - #### validators

          public Validator[] validators

      Validators to apply to value of this type.

      Default value is null

      See Also:
        `Validation overview and related methods`

  - ### Constructor Detail

    - #### SimpleType

          public SimpleType()