com.smartgwt.client.data
Class SimpleType

java.lang.Object
  com.smartgwt.client.core.BaseClass
      com.smartgwt.client.data.SimpleType

public class SimpleType
extends BaseClass

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

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 SimpleType.getAtomicValue and SimpleType.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 http://www.w3.org/TR/xmlschema-0/, and XMLTools.loadXMLSchema will create new SimpleType definitions.

An example is here.

Nested Class Summary

static class	SimpleType.SimpleTypeValueExtractor
static class	SimpleType.SimpleTypeValueUpdater

Field Summary

Fields inherited from class com.smartgwt.client.core.BaseClass

config, id, scClassName

Constructor Summary

SimpleType()
Create a new simple type.

SimpleType(JavaScriptObject jsObj)

SimpleType(String name, FieldType inheritsFrom)
Create a new simple type.

SimpleType(String name, SimpleType inheritsFrom)
Create a new simple type.

Method Summary

static Object	applySummaryFunction(Record[] records, ListGridField field, String functionName) Apply a registered summary function to a set of records and a field.
static Object	applySummaryFunction(Record[] records, ListGridField field, SummaryFunctionType summaryFunction) Apply a standard SummaryFunctionType to a set of records and a field.
JavaScriptObject	create()
String	getInheritsFrom() Name of another SimpleType from which this type should inherit.
JavaScriptObject	getJsObj()
String	getName() Name of the type, used to refer to the type from field.type.
static SimpleType	getOrCreateRef(JavaScriptObject jsObj)
static SimpleType	getType(String typeName) Retrieve a simpleType definition by type name
boolean	isCreated()
void	register() Explicitly register this SimpleType with the system so that it can be used / referenced by remote DataSources.
static void	registerSummaryFunction(String functionName, SummaryFunction summaryFunction) Registers a new SummaryFunction by name.
static void	setDefaultSummaryFunction(String typeName, String functionName) Set a default summary function for some field type.
static void	setDefaultSummaryFunction(String typeName, SummaryFunctionType summaryFunction) Set a default summary function for some field type.
void	setEditFormatter(SimpleTypeFormatter formatter) Formatter for values of this type when displayed in a freeform text editor such as a TextItem
void	setEditorType(FormItem editorType) Default FormItem configuration for editing values of this type.
Object	setEditParser(SimpleTypeParser parser) Specify a parser to convert some user-edited value to an underlying data value of this type.
void	setInheritsFrom(FieldType inheritsFrom) Name of another SimpleType from which this type should inherit.
void	setInheritsFrom(String inheritsFrom) Name of another SimpleType from which this type should inherit.
void	setJavaScriptObject(JavaScriptObject jsObj)
void	setName(String name) Name of the type, used to refer to the type from field.type.
void	setNormalDisplayFormatter(SimpleTypeFormatter formatter) Normal formatter for values of this type used in a StaticTextItem or DetailViewer.
void	setReadOnlyEditorType(FormItem editorType) Classname of the FormItem that should be the default for editing values of this type (eg "SelectItem").
void	setShortDisplayFormatter(SimpleTypeFormatter formatter) Formatter for values of this type when compact display is required, for example, in a ListGrid or TreeGrid.
Object	setSimpleTypeValueExtractor(SimpleType.SimpleTypeValueExtractor extractor) Specify an extractor to extract an atomic value (such as a string or number) from some arbitrary live data value.
Object	setSimpleTypeValueUpdater(SimpleType.SimpleTypeValueUpdater updater) Specify an updater to update a live data value with an edited atomic value (such as a string or number).
void	setValidators(Validator... validators) Validators to apply to value of this type.
void	setValidOperators(OperatorId... operators) Set of search operators valid for this type.
void	setValueMap(Map valueMap) List of legal values for this type, like valueMap.
void	setValueMap(String... valueMap) List of legal values for this type, like valueMap.

Methods inherited from class com.smartgwt.client.core.BaseClass

destroy, doAddHandler, error, error, errorIfNotCreated, fireEvent, getAttribute, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsElement, getAttributeAsFloat, getAttributeAsInt, getAttributeAsJavaScriptObject, getAttributeAsMap, getAttributeAsString, getAttributeAsStringArray, getConfig, getHandlerCount, getID, getOrCreateJsObj, getRef, getScClassName, onInit, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setID, setProperty, setProperty, setProperty, setProperty, setScClassName

Methods inherited from class java.lang.Object

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

Constructor Detail

SimpleType

public SimpleType(JavaScriptObject jsObj)

SimpleType

public SimpleType()

Create a new simple type.

Parameters:

name - the name of the simple type

inheritsFrom - the type it inherits from

SimpleType

public SimpleType(String name,
                  FieldType inheritsFrom)

Create a new simple type.

Parameters:

name - the name of the simple type

inheritsFrom - the type it inherits from

SimpleType

public SimpleType(String name,
                  SimpleType inheritsFrom)

Create a new simple type.

Parameters:

name - the name of the simple type

inheritsFrom - the type it inherits from

Method Detail

getOrCreateRef

public static SimpleType getOrCreateRef(JavaScriptObject jsObj)

setJavaScriptObject

public void setJavaScriptObject(JavaScriptObject jsObj)

create

public JavaScriptObject create()

Specified by:

create in class BaseClass

setInheritsFrom

public void setInheritsFrom(String inheritsFrom)
                     throws IllegalStateException

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.

Parameters:

inheritsFrom - . See String. Default value is null

Throws:

IllegalStateException - this property cannot be changed after the underlying component has been created

See Also:

Custom Types Example

getInheritsFrom

public String getInheritsFrom()

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.

Returns:

. See String

See Also:

Custom Types Example

setName

public void setName(String name)
             throws IllegalStateException

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

Parameters:

name - . See String. Default value is null

Throws:

IllegalStateException - this property cannot be changed after the underlying component has been created

getName

public String getName()

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

Returns:

. See String

getType

public static SimpleType getType(String typeName)

Retrieve a simpleType definition by type name

Parameters:

typeName - the name of the simpleType to return

Returns:

simple type object

register

public void register()

Explicitly register this SimpleType with the system so that it can be used / referenced by remote DataSources.

setValidators

public void setValidators(Validator... validators)
                   throws IllegalStateException

Validators to apply to value of this type.

Parameters:

validators - validators Default value is null

Throws:

IllegalStateException - this property cannot be changed after the underlying component has been created

setValueMap

public void setValueMap(String... valueMap)
                 throws IllegalStateException

List of legal values for this type, like valueMap.

Parameters:

valueMap - valueMap Default value is null

Throws:

IllegalStateException - this property cannot be changed after the underlying component has been created

setValueMap

public void setValueMap(Map valueMap)
                 throws IllegalStateException

List of legal values for this type, like valueMap.

Parameters:

valueMap - valueMap Default value is null

Throws:

IllegalStateException - this property cannot be changed after the underlying component has been created

setEditorType

public void setEditorType(FormItem editorType)
                   throws IllegalStateException

Default FormItem configuration for editing values of this type.

You can create a simple custom FormItem by adding default com.smartgwt.client.widgets.form.fields.FormItem#setIcons, icons that launch custom value picking dialogs (an example is in the QuickStart Guide, Chapter 9, Extending Smart GWT). By setting simpleType.editorType to an instance of your custom FormItem, forms will automatically use the custom FormItem, as will grids performing com.smartgwt.client.widgets.grid.ListGrid#getCanEdit, grid editing.

Parameters:

editorType - editorType Default value is null

Throws:

IllegalStateException - this property cannot be changed after the underlying component has been created

setReadOnlyEditorType

public void setReadOnlyEditorType(FormItem editorType)
                           throws IllegalStateException

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 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 canEdit.

Parameters:

editorType - editorType Default value is null

Throws:

IllegalStateException - this property cannot be changed after the underlying component has been created

setValidOperators

public void setValidOperators(OperatorId... operators)
                       throws IllegalStateException

Set of search operators valid for this type.

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

Parameters:

operators - validOperators Default value is null

Throws:

IllegalStateException - this property cannot be changed after the underlying component has been created

setInheritsFrom

public void setInheritsFrom(FieldType inheritsFrom)
                     throws IllegalStateException

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.

Parameters:

inheritsFrom - inheritsFrom Default value is null

Throws:

IllegalStateException - this property cannot be changed after the underlying component has been created

setNormalDisplayFormatter

public void setNormalDisplayFormatter(SimpleTypeFormatter formatter)

Normal formatter for values of this type used in a StaticTextItem or DetailViewer.

A formatter can make itself configurable on a per-component or per-field basis by checking properties on the component or field. For example, a formatter for account IDs may want to omit a prefix in views where it is redundant, and could check a flag detailViewer.omitAccountIdPrefix for this purpose.

Parameters:

formatter - the formatter

setShortDisplayFormatter

public void setShortDisplayFormatter(SimpleTypeFormatter formatter)

Formatter for values of this type when compact display is required, for example, in a ListGrid or TreeGrid.

A formatter can make itself configurable on a per-component or per-field basis by checking properties on the component or field. For example, a formatter for account IDs may want to omit a prefix in views where it is redundant, and could check a flag listGridField.omitAccountIdPrefix for this purpose.

Parameters:

formatter - the formatter

setEditFormatter

public void setEditFormatter(SimpleTypeFormatter formatter)

Formatter for values of this type when displayed in a freeform text editor such as a TextItem

See also #parseInput for parsing an edited text value back to a data value.

Parameters:

formatter - the formatter

setEditParser

public Object setEditParser(SimpleTypeParser parser)

Specify a parser to convert some user-edited value to an underlying data value of this type. This parser is called when storing out values edited in a freeform editor such as a TextItem. Typically this will convert from the format produced by #editFormatter back to a data value.

Parameters:

parser - the parser

setSimpleTypeValueExtractor

public Object setSimpleTypeValueExtractor(SimpleType.SimpleTypeValueExtractor extractor)

Specify an extractor to extract an atomic value (such as a string or number) from some arbitrary live data value. If defined this method will be called for every field value of the specified type in order to convert from the raw data value to an atomic type to be used for standard DataBinding features such as sorting and editing.

Parameters:

extractor - the extractor

setSimpleTypeValueUpdater

public Object setSimpleTypeValueUpdater(SimpleType.SimpleTypeValueUpdater updater)

Specify an updater to update a live data value with an edited atomic value (such as a string or number). If defined this updater's updateAtomicValue method will be called when the user edits data in a field of this type, allowing the developer to convert from the atomic type to a raw data value for storage.

Parameters:

extractor - the updater

isCreated

public boolean isCreated()

Overrides:

isCreated in class BaseClass

getJsObj

public JavaScriptObject getJsObj()

Overrides:

getJsObj in class BaseClass

registerSummaryFunction

public static void registerSummaryFunction(String functionName,
                                           SummaryFunction summaryFunction)

Registers a new SummaryFunction by name. After calling this method, developers may specify the name passed in as a standard summaryFunction (for example in ListGridField.setSummaryFunction()). Note that if the specified name conflicts with one of the built in SummaryFunctionType values, a RuntimeException will be thrown.

Parameters:

functionName - name for the SummaryFunction

summaryFunction - new SummaryFunction implementation

applySummaryFunction

public static Object applySummaryFunction(Record[] records,
                                          ListGridField field,
                                          SummaryFunctionType summaryFunction)

Apply a standard SummaryFunctionType to a set of records and a field.

Parameters:

records - records to obtain the summary value for

field - field on which the summary function is being run

summaryFunction - standard summary function identifier

Returns:

result of the summary function.

applySummaryFunction

public static Object applySummaryFunction(Record[] records,
                                          ListGridField field,
                                          String functionName)

Apply a registered summary function to a set of records and a field.

Parameters:

records - records to obtain the summary value for

field - field on which the summary function is being run

functionName - name under which the summary function is registered. See {@link #registerSummaryFunction(String, SummaryFunction)

Returns:

result of the summary function.

setDefaultSummaryFunction

public static void setDefaultSummaryFunction(String typeName,
                                             SummaryFunctionType summaryFunction)

Set a default summary function for some field type.

Parameters:

typeName - name of the field type. If this is the name of a custom SimpleType, the developer may need to ensure the type is #register(),registered.

summaryFunction - standard summary function type for this data type

setDefaultSummaryFunction

public static void setDefaultSummaryFunction(String typeName,
                                             String functionName)

Set a default summary function for some field type.

Parameters:

typeName - name of the field type. If this is the name of a custom SimpleType, the developer may need to ensure the type is #register(),registered.

summaryFunction - name under whithc the summary function is registered. See registerSummaryFunction(String, SummaryFunction)