public class DataSourceField
extends java.lang.Object
com.smartgwt.client.docs.serverds for how to use this documentation.Metadata about a DataSourceField, including its type and validators.
| Modifier and Type | Field and Description |
|---|---|
java.lang.Boolean |
autoGenerated
Indicates this field value is auto-generated by data base or ORM provider.
|
boolean |
autoQuoteCustomExpressions
If explicitly set to false, switches off automatic quoting and escaping of values in custom
expressions that are derived from Velocity evaluations.
|
java.lang.Boolean |
canEdit
Controls whether, by default, DataBoundComponents consider this field editable.
|
java.lang.Boolean |
canExport
Dictates whether the data in this field be exported.
|
java.lang.Boolean |
canFilter
Should the user be able to filter data by this field? Effects whether this field will show up
in dataBoundComponents with UI for filtering data.
|
java.lang.Boolean |
canSave
Whether values in this field can be updated and saved to the dataSource.
|
boolean |
canSortClientOnly
When true, this field can only be used for sorting if the data is entirely client-side.
|
java.lang.Boolean |
canView
If false, this property indicates that this field is considered "server only".
|
java.lang.Boolean |
childrenProperty
If true, this property indicates that this field will hold an explicit array of child nodes
for the current node.
|
java.lang.String |
childTagName
For a field that is
multiple:"true", controls the name of the XML tag used for each subelement during DataSource.xmlSerialize. |
java.lang.Boolean |
creatorOverrides
Indicates that normal declarative security rules specified on this field are waived for rows
that were created by the current user, as described in the discussion of
dataSource.creatorOverrides. |
java.lang.String |
customCriteriaExpression
This property indicates that this field should be represented by a custom expression
embedded in the WHERE clause of the generated SQL, instead of the generated expression
containing this field name that would ordinarily be used.
|
java.lang.String |
customInsertExpression
This property is similar to
customUpdateExpression; its value is used during "add" operations. |
java.lang.String |
customSelectExpression
This property indicates that this field represents a custom expression that should be
embedded in the generated SQL instead of a reference to this field.
|
java.lang.Boolean |
customSQL
For a DataSource with
serverType "sql" or "hibernate", indicates that this field should be omitted by default from
all SQL or Hibernate operations, and will only be used with custom queries. |
java.lang.String |
customUpdateExpression
This property specifies the value to use to update this column on "update" operations.
|
java.lang.Integer |
decimalPad
Applies only to fields of type "float" and enforces a minimum number of digits shown after the
decimal point.
|
java.lang.Integer |
decimalPrecision
Applies only to fields of type "float" and affects how many significant digits are shown.
|
boolean |
detail
Whether this field should be considered a "detail" field by a
DataBoundComponent. |
java.lang.String |
displayField
Name of another field in this DataSource that should be used as the display value for this
field.
|
DateDisplayFormat |
displayFormat
The default date formatter to use for displaying this field.
|
FormItem |
editorType
Sets the default FormItem to be used whenever this field is edited (whether in a grid, form, or
other component).
|
VelocityExpression |
editRequires
Indicates that the specified
VelocityExpression must evaluate
to true if writes to this field are to be allowed. |
java.lang.Boolean |
editRequiresAuthentication
Whether a user must be authenticated in order to write to this field.
|
java.lang.String |
editRequiresRole
Comma-separated list of user roles that are allowed to write to this field.
|
java.lang.Boolean |
encodeInResponse
When set for a field with binary data, binary data will be delivered as a Base64 encoded
string.
|
java.lang.Boolean |
escapeHTML
When data values are displayed in DataBound components, by default strings will be interpreted
as HTML by the browser in most cases.
|
java.lang.String |
exportTitle
Optional different field-title used for exports.
|
java.lang.String |
fkColumnCode
Only applicable to the built-in SQL DataSource
|
java.lang.String |
fkTableCode
Only applicable to the built-in SQL DataSource
|
java.lang.String |
foreignKey
Declares that this field holds values that can be matched to values from another DataSource
field, to create a relationship between records from different DataSources or even records
within the same DataSource.
|
java.lang.String |
group
For use in
ComponentSchema, indicates what group to place the
property in when editing in Visual Builder. |
boolean |
hidden
Whether this field should be hidden from users by default within a DataBound component.
|
boolean |
ignore
Whether this field should be completely excluded from this dataSource, as if it had never been
defined.
|
java.lang.Boolean |
ignoreTextMatchStyle
NOTE: Only applicable to
clientOnly DataSources and the built-in SQL
DataSource available in Pro, Power and Enterprise versions of Smart GWT. |
java.lang.Integer |
imageHeight
Height of the image-content of this field.
|
java.lang.Integer |
imageSize
Width and height of the image-content of this field.
|
java.lang.Integer |
imageWidth
Width of the image-content of this field.
|
java.lang.Boolean |
inapplicable
For use in
ComponentSchema, a field inherited from another schema can be
redeclared with this property set in order to indicate that the property should not be used. |
java.lang.String |
includeFrom
Indicates this field should be fetched from another, related DataSource.
|
VelocityExpression |
initRequires
Indicates that the specified
VelocityExpression must evaluate
to true if initializations of this field are to be allowed. |
java.lang.Boolean |
initRequiresAuthentication
Whether a user must be authenticated in order to initialize to this field.
|
java.lang.String |
initRequiresRole
Comma-separated list of user roles that are allowed to initialize this field.
|
java.lang.String |
javaClass
For use with the Smart GWT server when populating Java Beans / POJOs based on data contained in
a DSRequest,
javaClass specifies the fully qualified Java className to be created
and passed to the setter for the Java Bean Property with the same name as this field. |
java.lang.String |
javaCollectionClass
See
javaClass - when
auto-populating of Java Beans / POJOs based on inbound DSRequest data, for a field of type
Collection or Map, javaCollectionClass can be used to specify a particular
concrete class to use. |
java.lang.String |
javaKeyClass
See
javaClass - when
auto-populating of Java Beans / POJOs based on inbound DSRequest data, for a field of Map
type, javaKeyClass can be used to specify a particular concrete class for the map
keys. |
JoinType |
joinType
This property is only applicable to fields of SQL DataSources that also specify a
foreignKey property; it is
ignored for all other fields. |
java.lang.Integer |
length
Maximum number of characters allowed.
|
java.lang.Boolean |
lenientXPath
Indicates that getting
valueXPath for this field should not perform any validation at all and will return null for
non existing XPaths. |
java.lang.Integer |
maxFileSize
For fields of a type that are represented by binary data initially uploaded from a file
(currently "binary" and "imageFile", see
FieldType), this
sets the maximum file size allowed, in bytes. |
java.lang.String |
mimeType
For a
binary field, sets a fixed mime type for
all files stored to this field. |
java.lang.Boolean |
multiple
Indicates that this field should always be Array-valued.
|
java.lang.String |
name
Name for this field.
|
java.lang.String |
nativeName
Only applicable to "sql" dataSources.
|
java.lang.Boolean |
nillable
Controls whether an explicit null-valued Record attribute for this field
should result in
xsi:nil being used to transmit the value when serializing
to XML, like so: |
java.lang.Integer |
precision
Applies only to fields of type "float" or "integer" and affects how many significant digits are
shown.
|
boolean |
primaryKey
Indicates either that this field holds a value unique across all records in this
DataSource, or that it is one of a number of fields marked as primary keys, and the
combination of the values held in all of those fields is unique across all records in the
DataSource.
|
java.lang.Boolean |
propertiesOnly
For use in
ComponentSchema for fields that contain other
components, this flag
suppresses auto-construction for subcomponents that appear under this field. |
FormItem |
readOnlyEditorType
Sets the default FormItem to be used if this field is marked as
canEdit false and displayed in an
editor component such as a DynamicForm. |
java.lang.Boolean |
required
Indicates this field must be non-null in order for a record to pass validation.
|
java.lang.Object |
rootValue
For a field that is a foreignKey establishing a tree relationship, what value indicates a
root-level node.
|
java.lang.String |
sequenceName
For a DataSource with
serverType:"sql" with a field of type
"sequence", the name of the SQL sequence that should be used when inserting new records into
this table. |
java.lang.Boolean |
showFileInline
For a field of type:"imageFile", indicates whether to stream the image and display it inline or
to display the View and Download icons.
|
java.lang.String |
sqlDateFormat
For fields of type "date", "time", and "datetime" that specify an
sqlStorageStrategy of
"number" or "text", this property allows you to specify the format Smart GWT should use to map
to/from the underlying value stored in the database. |
java.lang.String |
sqlFalseValue
For fields of type "boolean" that specify a
sqlStorageStrategy of
"singleChar", this is the value to persist for false values. |
java.lang.String |
sqlStorageStrategy
For certain field types, indicates the strategy to be used to store values to the underlying
SQL column.
|
java.lang.String |
sqlTrueValue
For fields of type "boolean" that specify a
sqlStorageStrategy of
"singleChar", this is the value to persist for true values. |
HashAlgorithm |
storeWithHash
If set, causes the field to be securely hashed before saving on an "add" or "update"
operation.
|
java.lang.String |
tableName
Only applicable to "sql" dataSources, setting
tableName indicates that this field
will be coming from another table by way of a customized SQL query. |
java.lang.String |
title
Default user-visible title for this field.
|
FieldType |
type
Type of this field.
|
VelocityExpression |
updateRequires
Indicates that the specified
VelocityExpression must evaluate
to true if updates to this field are to be allowed. |
java.lang.Boolean |
updateRequiresAuthentication
Whether a user must be authenticated in order to update to this field.
|
java.lang.String |
updateRequiresRole
Comma-separated list of user roles that are allowed to update this field.
|
java.lang.String |
uploadFieldName
Used by the
BatchUploader to map a field in an upload file
to this dataSourceField. |
Validator[] |
validators
Validators to be applied to this field.
|
OperatorId[] |
validOperators
List of operators valid on this field.
|
java.util.Map |
valueMap
A ValueMap is a set of legal values for a field.
|
java.lang.String |
valueMapEnum
Fully qualified Java className of an Enum that should be used to derive this field's ValueMap.
|
XPathExpression |
valueWriteXPath
Alternative XPath expression used to set the field's value.
|
XPathExpression |
valueXPath
XPath expression used to retrieve the field's value.
|
VelocityExpression |
viewRequires
Indicates that the specified
VelocityExpression must evaluate
to true if values for the field are to be fetched. |
java.lang.Boolean |
viewRequiresAuthentication
Whether a user must be authenticated in order to fetch this field.
|
java.lang.String |
viewRequiresRole
Comma-separated list of user roles that are allowed to fetch this field.
|
java.lang.Boolean |
xmlAttribute
Indicates that
DataSource.xmlSerialize
should serialize this value as an XML attribute. |
| Constructor and Description |
|---|
DataSourceField() |
public java.lang.String sqlFalseValue
sqlStorageStrategy of
"singleChar", this is the value to persist for false values. Note that the common use cases of
storing booleans as T/F, Y/N and 1/0 are already catered for without the need for this
property.sqlStorageStrategy of
"string", this is the value to persist for false values that require using the entire value.
Default value is null
sqlStorageStrategy,
sqlTrueValuepublic java.lang.Object rootValue
Note that the rootValue may be overridden on a specific
ResultTree instance by setting rootNode, or if the ResultTree is auto-generated by a TreeGrid, by setting treeRootValue. This allows a
component to navigate a subtree of the hierarchical data from this dataSource starting at a
particular node.
Default value is null
public java.lang.Boolean inapplicable
ComponentSchema, a field inherited from another schema can be
redeclared with this property set in order to indicate that the property should not be used.
This is primarily used to influence VisualBuilder. For
simple type properties, this avoids the property appearing in the Component Editor.
For
fields that hold subcomponents, this prevents inappropriate drag and drop. For example, a
custom class called MyDialog may automatically create a series of children, and
not allow arbitrary other children to be added. In this case, the inherited property children should be marked inapplicable in order
to prevent arbitrary components being dropped onto a MyDialog instance.
Default value is null
public java.lang.Boolean canView
dataBoundComponent, it will
be droppedcanEdit, no updates to the field
are allowed from the client. If you explicitly add a value for the field to, eg, a record
you are passing to DataSource.updateData, the server will strip the value out of the record before processing
the update request. canView:false is not the same thing as hidden. Use
canView:false when you want to prevent the client from ever seeing a field's
definition or values; use hidden:true if it is fine from a security perspective
that a field's definition and values are sent to the browser, but the field should not by
default appear in user interface elements (but could do in some cases, like a special screen
for advanced users or administrators, for example). Note that this property must be set explicitly to false to have an effect; a null or undefined setting is treated the same as true.
This property is used to implement field-level view security: failing a viewRequiresAuthentication, viewRequiresRole or viewRequires test is
equivalent to setting canView:false on the field (and, indeed, from the client's
perspective, the field has had canView:false set).
Default value is null
public java.lang.String javaKeyClass
javaClass - when
auto-populating of Java Beans / POJOs based on inbound DSRequest data, for a field of Map
type, javaKeyClass can be used to specify a particular concrete class for the map
keys. If not specified, and a concrete type cannot be discovered using Java Reflection,
java.lang.Object is used. Note that javaKeyClass take precedence over
generics if both are used.
Default value is null
public java.lang.String group
ComponentSchema, indicates what group to place the
property in when editing in Visual Builder.
Default value is null
public java.lang.Boolean canFilter
Default value is null
public Validator[] validators
Validators are applied whenever there is an attempt to save changes to a field.
For the available set of built-in validators, and how to define
a custom validator, see the Validator class.
Default value is null
public java.lang.String mimeType
binary field, sets a fixed mime type for
all files stored to this field. Should be set to a standard mime type string, for example,
"text/plain" for a .txt file. This is useful if a binary field only stored one type of file and you chose not to store filenames, since the extension of the file name is normally used to determine the mime type.
Default value is null
public java.lang.String viewRequiresRole
requiresRole for further
details of Smart GWT's declarative role-based security. Please also see fetchRequiresAuthentication for details of how declarative field-level security settings can
be overridden per-request.
Default value is null
public java.lang.Boolean showFileInline
Default value is null
public java.lang.Boolean escapeHTML
If set, this property will be picked up by components bound to this dataSource, notifying them that any HTML characters should be escaped when displaying values for this field.
Default value is null
ListGridField.getEscapeHTML()public java.lang.Boolean initRequiresAuthentication
Default value is null
public java.lang.String valueMapEnum
This has the same behavior of auto-deriving a valueMap from a Java Enum as
autoDeriveSchema except
it applies only to one field.
If you enable autoDeriveSchema there is no need
to set valueMapEnum for Enum fields unless you want to actually override
the behavior to use a different Enum for the field (eg, a superclass Enum that is more
restrictive).
Default value is null
public boolean detail
DataBoundComponent. Detail fields won't be shown by default in
a DataBoundComponent where showDetailFields is false.
This allows for some DataBound components, like a ListGrid, to show a summary view of records which displays
only the most commonly viewed fields by default, while other DataBoundComponents, like a
DetailViewer, show all fields by default.
In
addition, the formItem.showIf
property is supported in multiple components for conditional visibility - see for example
ListGridField.showIf and FormItem.showIf).
Default value is false
public OperatorId[] validOperators
If not specified, all operators that are valid for the field type are allowed.
Default value is null
public java.lang.Boolean xmlAttribute
DataSource.xmlSerialize
should serialize this value as an XML attribute. Note this does not need to be declared in order for DataSource records to be derived from XML data: a field will be populated with either an attribute or subelement with matching name.
Default value is null
public java.lang.String fkTableCode
This read-only attribute is a secure
and unique hashed version of the name of the table underlying a dataSource that this
dataSourceField is a foreign key to. It is used automatically by client-side framework code to link dataSources
together by foreign key, by matching fkTableCodes with tableCodes. This is necessary if we
automatically discovered a foreign key relationship by inspecting the database schema, as a
result of a DataSource specifying autoDeriveSchema: true. We use
a secure hash rather than the table name itself for security reasons - sending the actual
table name to the client would be considered an information leakage that could encourage
attempts at injection attacks.
Default value is null
DataSource.tableCode,
fkColumnCodepublic java.lang.Integer decimalPrecision
For example, with decimalPrecision 3, if the field value is 343.672677, 343.673 is shown.
If the value is 125.2, 125.2 is shown - decimalPrecision will not cause extra zeros to be
added. Use decimalPad for
this.
A number is always shown with its original precision when edited.
Default value is null
public java.lang.String updateRequiresRole
NOTE: This property only prevents a field from being updated; initialization will still
be allowed. You should only use this property if you have a special requirement; ordinarily,
use editRequiresRole, which applies security for both types of write.
Default value is null
public java.lang.String customCriteriaExpression
customCriteriaExpression something like this (in Oracle):
BITAND(myField, $criteria.myField)+0 = $criteria.myField
Or this (in MySQL or SQL Server):
myField & $criteria.myField = $criteria.myField
As this example shows, a customCriteriaExpression is expected to be a complete
logical expression that provides both sides of the comparison. After Velocity processing,
this example would result in SQL similar to this (for the MySQL case); the colored part
comes entirely from the customCriteriaExpression:
SELECT myField, myOtherField FROM myTable WHERE myField & 32 =
32
customCriteriaExpression can also be used with AdvancedCriteria.
Note that the point mentioned above, about a customCriteriaExpression being a
complete logical expression that provides both sides of the comparison still applies. This
means that when you use customCriteriaExpression in conjunction with
AdvancedCriteria, you effectively switch off support for different
OperatorIds to be used on that field, unless you use Velocity
expressions
containing the special $criteriaOperator variable (see below).
When you use customCriteriaExpression with AdvancedCriteria, the
way you access criteria values differs slightly. One option is to use the
$advancedCriteria Velocity variable, as described in the "Using AdvancedCriteria"
section of the custom querying overview.
However, this
variable only returns the value from the first Criterion that
uses the field,
as found by depth-first search. If your AdvancedCriteria contains multiple
references to this field, this will not be satisfactory. Therefore, specifically for
customCriteriaExpression, we provide another Velocity variable,
$criteriaValue. This variable means "the value on a Criterion referencing
this field". An example may serve to clarify this:
Assume you need to extend the above example to filter records where a certain bit is set
OR a certain other bit is set. An AdvancedCriteria like this would be
required (note that the choice of "equals" as the operator in these clauses is completely
arbitrary - as discussed above, the operator is ignored when we have a
customCriteriaExpression, so it would make no difference to the end product
if we had used different operators here):
{ _constructor: "AdvancedCriteria", operator: "or", criteria: [
{ fieldName: "myField", operator: "equals", value: 32 },
{ fieldName: "myField", operator: "equals", value: 64 },
]
}
If you used the customCriteriaExpression from above unchanged with this criteria,
the following SQL would be generated (in the MySQL case):
SELECT myField, myOtherField FROM myTable WHERE myField & null = null OR myField & null =
null
This is because $criteria is a variable that only works correctly with simple
criteria. If you changed the $criteria references in the expression to
$advancedCriteria, the generated SQL would be:
SELECT myField, myOtherField FROM myTable WHERE myField & 32 = 32 OR myField & 32 =
32
This is because $advancedCriteria always returns the first value it finds for
a particular field, as described above. However, if you change the expression so it reads:
myField & $criteriaValue = $criteriaValue
you will now get the correct SQL generated:
SELECT myField, myOtherField FROM myTable WHERE myField & 32 = 32 OR myField & 64 =
64
Similar to $criteriaValue, we provide a special variable,
$criteriaOperator. This is intended for use in Velocity expressions, so that
your customCriteriaExpression can process different operators in different ways.
How you choose to interpret an operator is entirely up to you; this variable is both
advanced and rarely used. This example is contrived and does not show a usage that would be
remotely likely in a real application, but it does show how to use the variable in a Velocity
expression:
myField #if ($criteriaOperator == "greaterThan") & #else | #end
$criteriaValue = $criteriaValue
For simple criteria, note that $criteriaOperator will vary depending on field
type and the textMatchStyle in force, as
follows:
customCriteriaExpressions, and the
usual context variables are available. Note
that the results
of Velocity evaluations are automatically quoted and escaped by default; this behavior can
be switched off - see autoQuoteCustomExpressions, and
particularly note the warnings about its use.
Note that this property only applies to users of the Smart GWT server using dataSources of type "sql".
Default value is null
public java.lang.Boolean ignoreTextMatchStyle
clientOnly DataSources and the built-in SQL
DataSource available in Pro, Power and Enterprise versions of Smart GWT. Use this flag to
inhibit the normal use of TextMatchStyle for this field. A
field with this flag set will always be tested for exact equality in generated queries, even
for filter-style queries where normal behavior would be to use a substring match or similar.
Default value is null
public boolean primaryKey
primaryKey field per DataSource, and ideally
this field should be of type
"sequence". A DataSource that can only perform the "fetch" operation does not
require a primaryKey unless it contains binary
fields. If a DataSource allows modification of DataSource records through add, update and
remove DataSource operations, or it contains one or more binary fields, one or more fields
must be marked as the primary key.
Smart GWT requires a primary key value to uniquely identify records when communicating updates or deletions to the server. There is no requirement that the primaryKey field be mapped to an actual "primary key" in your object model, web service, or database (though this is the most obvious and natural thing to do, of course). The only requirement is that the combined values of the primaryKey fields be unique for a given browser instance for the lifetime of the page.
If using Smart GWT's SQL engine and generating SQL tables using the Admin Console, the table column generated from a
primaryKey field will have a unique constraint applied in the database table and, if the field
is of type "sequence", the database column will also be created as an "identity column" in
those databases that implement sequence-type handling with identity columns.
Default value is false
public java.lang.Integer length
NOTE:
For DataSources of type "sql", this property has a bearing on the type of column we use when
the underlying table is created by a DataSource import in the Admin Console. Below a certain
length (which is database-specific, see below), we use standard VARCHAR columns;
above that length, we use an alternate strategy (again, database-specific). For these long
fields, we sometimes also generate different SQL for "update" and "add" operations, using JDBC
"?" replacement parameters rather than embedding values directly in the generated SQL; whether
or not this is done depends entirely on what the underlying database product and/or JDBC
driver will allow.
Table of field length limits for supported databases:
| Database product | VARCHAR limit * | Type used above limit |
| HSQLDB | None | - |
| IBM DB2 | 4000 | CLOB |
| Firebird | 32767 | BLOB with subtype 1 |
| Informix | 255 / 32739 | LVARCHAR / TEXT ** |
| Microsoft SQL Server | 8000 | TEXT |
| MySQL | 255 / 65535 / 16M | TEXT / MEDIUMTEXT / LONGTEXT *** |
| Oracle | 4000 | CLOB |
| PostgreSQL | 4000 | TEXT |
** Informix has a limit of just 255 characters for VARCHAR, but has a native LVARCHAR type which supports nearly 32K characters without needing to fall back on long datatypes. Therefore, with that one product, we have two thresholds for a change in storage type.
*** MySQL has a limit of 255 characters for VARCHAR, 65,535 characters for TEXT and 16,777,215 for MEDIUMTEXT; therefore, with that one product, we have three thresholds for a change in storage type.
Default value is null
public HashAlgorithm storeWithHash
Default value is null
public java.lang.String javaCollectionClass
javaClass - when
auto-populating of Java Beans / POJOs based on inbound DSRequest data, for a field of type
Collection or Map, javaCollectionClass can be used to specify a particular
concrete class to use. If not specified, and a concrete Collection or Map class cannot be
discovered using Java Reflection, the following concrete classes are used: java.util.ArrayList is used for fields of type List java.util.HashSet is used for fields of type Set java.util.LinkedList is used for fields of type Queue org.apache.commons.collections.map.LinkedMap is used for fields of type
Map java.util.ArrayList is used for fields that are otherwise of
type Collection javaCollectionClass to java.util.LinkedList but your setter method
accepts a java.util.ArrayList, you will get a ClassCastException.
Default value is null
public java.lang.String javaClass
javaClass specifies the fully qualified Java className to be created
and passed to the setter for the Java Bean Property with the same name as this field.
javaClass is used both when manually calling DataSource.setProperties() and when
auto-populating POJO arguments of a DMI method. The Java class to
create does not normally have to be specified: Smart GWT will use Java reflection to inspect
the type of argument expected by a setter method and will attempt conversion of inbound data to
that type. As described in the documentation for DataTools.setProperties(), this works for
almost all typical cases. However field.javaClass is useful for:
javaClass should be
set instead.javaClass needs to be specified. Note that javaClass will take
precedence over generics if both are used. Also note that javaCollectionClass can
be specified if a particular Collection or Map type is needed, and javaKeyClass can be specified
for a field of type java.util.Map.DataSource.getPropertyJavaClass() in the server documentation for
details.
Default value is null
public boolean autoQuoteCustomExpressions
By default, any part of a customSelectExpression, customCriteriaExpression, customUpdateExpression or customInsertExpression that comes ultimately from evaluating a Velocity expression, will be
automatically quoted and escaped according to the syntax of the underlying database. We do
this because "raw" values are vulnerable to SQL injection attacks.
However, it is
possible that the exact SQL logic you desire for a custom expression cannot be expressed
without access to the raw, unquoted value. To work around this, you can either use the special
$rawValue context variable, or you can set
this property to false to switch off auto-quoting completely for all custom expressions on this
field.
Warning: Bear in mind that it is dangerous to use raw values. There
are some cases where using the raw value is necessary, but even so, all such cases are likely
to be vulnerable to injection attacks. Generally, the presence of $rawValue in a
custom expression, or any fields with autoQuoteCustomExpressions: false
specified, should be viewed as a red flag.
Default value is true
public java.lang.String exportTitle
Default value is null
public java.lang.Boolean nillable
xsi:nil being used to transmit the value when serializing
to XML, like so:
<book>
<title>Beowulf</title>
<author xsi:nil="true"/>
</book>
If nillable is not set, no XML element will be generated for
the explicit null value.
Default value is null
public java.lang.String displayField
Typically used for editable foreignKey fields: the
foreignKey field stores an ID value, and this ID value is the right value to use
when editing (typically by a SelectItem with
optionDataSource
set). However, when the foreignKey field is viewed read-only, it should display a
name, title or other friendly value from the related record. In order to accomplish this, a
second, hidden field carries the display value, and the foreignKey field has
displayField set to this second, hidden field.
For a more in-depth discussion,
see includeFrom.
Default value is null
public JoinType joinType
foreignKey property; it is
ignored for all other fields. Indicates the type of join to make between the tables
underlying this DataSource and the other DataSource referred to in the foreignKey
property, when resolving includeFrom fields. The default value of null is the same as specifying "inner". Note,
outer joins are allowed for all supported database products only if you are using ANSI-style joins, which is not the
case by default. If you are using the older strategy of additional join expressions in the
WHERE clause, outer joins are only supported for database products that provide a proprietary
native syntax for expressing outer joins. Those products are:
Default value is null
public VelocityExpression updateRequires
VelocityExpression must evaluate
to true if updates to this field are to be allowed. If the specified expression does not
evaluate to true, the field will be removed from the request as described for editRequiresAuthentication. In addition to the normal context variables available to
Velocity expressions in Smart GWT, expressions you write for field-level requires
clauses - updateRequires, viewRequires, editRequires and initRequires - can reference
two additional variables: $fieldName and $dsName. These are the
names of the dataSource and field currently undergoing requires checks. They are
helpful because they allow you to write a generic checker function that can be used to handle
requires checks for multiple fields and dataSources.
NOTE: This
property only prevents update of a field; initialization will still be allowed. You should
only use this property if you have a special requirement; ordinarily, use editRequires, which applies
security for both types of write.
Default value is null
public java.lang.Boolean editRequiresAuthentication
This property affects two things. Firstly, the server determines when the
DataSource is first loaded if we have an authenticated user; if we don't, the field is marked
canEdit: false. Secondly, when an insert or update request is received from the
client, the server removes the field from the values clause before the request is
processed.
Note that you can override this behavior. The canEdit setting can
be overridden on the the client-side DataSource like any other client-side property. The
value-removing behavior can be overridden on a per-request basis by providing a DMI that
re-adds values for the fields you want for that particular request to the values object (the
values originally sent up by the client are available on the DSRequest). See the server-side
Javadocs for DSRequest.getValues() and
DSRequest.getClientSuppliedValues().
Default value is null
public java.lang.String childTagName
multiple:"true", controls the name of the XML tag used for each subelement during DataSource.xmlSerialize. If unset, the
default tag name is "value" for a field of simple type, and for a field of DataSource type, is
the tagName or ID of the DataSource (as though xmlSerialize() were called on the
child DataSource).
Default value is null
public java.lang.String uploadFieldName
BatchUploader to map a field in an upload file
to this dataSourceField. This is only necessary if the dataSourceField's name and title
differ from the name of the field in the upload file (Smart GWT will automatically map upload
fields using the dataSourceField's title, if possible, if it does not get a direct match on
field name).
Default value is null
public java.lang.Boolean customSQL
serverType "sql" or "hibernate", indicates that this field should be omitted by default from
all SQL or Hibernate operations, and will only be used with custom queries. Having marked a field as
customSQL you can refer to it via $criteria.fieldName or
$values.fieldName in customized queries.
The following are situations where you
would not use customSQL:
includeFrom instead sqlStorageStrategy for
some common cases, or customSelectExpression, customUpdateExpression and customInsertExpression for full customization excludeCriteriaFields
instead Use customSQL in situations like:
operationIds, and the field is
only used in some of them; in that case, consider using customFields to selectively
re-introduce SQL generation for the field only in operations where it's used. Default value is null
public java.lang.String title
This will be picked up by DataBound components and other views over this DataSource.
Note this property frequently does not need to be set
since autoDeriveTitles
(on by default) usually picks an appropriate user-visible title if you have a reasonable naming
convention for your field names.
Note that if this field is being displayed in a ListGrid bound to this dataSource, the headerTitle attribute may be
used to specify a different string for display in the listGrid column header.
Default value is null
public java.lang.String customInsertExpression
customUpdateExpression; its value is used during "add" operations. If you do not specify this
property, but do specify a customUpdateExpression, the
customUpdateExpression is used instead. Everything that applies to
customUpdateExpression also applies to this property, including the observation
that fields which specify a customSelectExpression but no corresponding customUpdateExpression or
customInsertExpression, will be ignored when adding new records.
Note that this property only applies to users of the Smart GWT server using dataSources of type "sql".
Default value is null
public VelocityExpression editRequires
VelocityExpression must evaluate
to true if writes to this field are to be allowed. If the specified expression does not
evaluate to true, the field will be removed from the request as described for editRequiresAuthentication. In addition to the normal context variables available to
Velocity expressions in Smart GWT, expressions you write for field-level requires
clauses - editRequires, viewRequires, initRequires and updateRequires - can
reference two additional variables: $fieldName and $dsName. These
are the names of the dataSource and field currently undergoing requires checks.
They are helpful because they allow you to write a generic checker function that can be used to
handle requires checks for multiple fields and dataSources.
NOTE: This
property prevents both initialization and updates for a field. If you have a need to prevent
just initialization or just updates, you can use initRequires or updateRequires.
Default value is null
public java.lang.Boolean encodeInResponse
When encodeInResponse is not set normal responses will not contain
values for binary fields at all. Instead, UI components, such as TileGrid issue a second binary fetch for binary data when
appropriate, and APIs such as downloadFile and viewFile can be
used to programmatically trigger downloads.
Only applicable to fields of a type that are
represented by binary data (currently "binary" and "imageFile", see FieldType).
Default value is null
public java.lang.String sqlStorageStrategy
Fields of type "boolean"
The default strategy for boolean fields is
to assume the underlying type of the field is text and store boolean true and false values as
the character strings "true" and "false". The following additional strategies are available:
sqlTrueValue
and sqlFalseValue
sqlTrueValue and sqlFalseValue
Fields of type "date", "time", and "datetime"
The default strategy for these types
is to use a native type that supports date and time values to the nearest second; the actual
type used varies by database. The following additional strategies are available:
sqlDateFormat on the field; if no format is specified, the framework defaults to "yyyyMMdd".
Fields of type "text"
NOTE: This section is only applicable for users of Microsoft SQL Server. The "ntext" strategy is ignored for all other databases.
If you are integrating with Microsoft SQL Server, you may run into an issue with that database and double-byte character sets. Although the documentation indicates that string values are sent to the database as Unicode by default, they may undergo conversion at the database end, depending on the collation settings of the database. This Microsoft support article describes the situation, which is that Unicode is converted to the code page of the database before being used, in order to "provide backward compatibility with existing applications".
To work
around this, we provide an sqlStorageStrategy of "ntext". Fields that declare
this strategy are inserted into queries using the "N syntax", like so:
UPDATE MyTable SET MyTextColumn = N'some text' WHERE MyPK = N'some
key'
This syntax overrides defaults and forces the database to treat strings as Unicode.
Note that declaring a field to be of type "ntext" is exactly equivalent to specifying type "text" and an
sqlStorageStrategy of "ntext". If you declare a field of type "ntext" when the
back-end database is something other than SQL Server, it will be treated as a normal field of
type "text".
This property only applies to users of the Smart GWT server using dataSources of type "sql".
Default value is null
public VelocityExpression initRequires
VelocityExpression must evaluate
to true if initializations of this field are to be allowed. If the specified expression does
not evaluate to true, the field will be removed from the request as described for editRequiresAuthentication. In addition to the normal context variables available to
Velocity expressions in Smart GWT, expressions you write for field-level requires
clauses - initRequires, viewRequires, editRequires and updateRequires - can
reference two additional variables: $fieldName and $dsName. These
are the names of the dataSource and field currently undergoing requires checks.
They are helpful because they allow you to write a generic checker function that can be used to
handle requires checks for multiple fields and dataSources.
NOTE: This
property only prevents initialization of a field; updates will still be allowed. You should
only use this property if you have a special requirement; ordinarily, use editRequires, which applies
security for both types of write.
Default value is null
public java.lang.Boolean viewRequiresAuthentication
The way this behavior works is to remove the field from the expressed or
implied list of fields to return. A list of fields can be expressed using outputs or outputs; in the absence of those, the entire set
of fields defined in the DataSource is implied. You can override this behavior on a
per-request basis by providing a DMI that just re-adds the names of the fields you want for
that particular request to the "consolidated outputs". See the server-side Javadoc for
DSRequest.getConsolidatedOutputs().
In addition to this behavior of trimming
off values in fetched records, a field that fails a field-level security check (either this one
or one of the two more specific checks, viewRequiresRole and viewRequires) will be altered
in the version of the dataSource returned to the client by the <loadDS>
JSP tag or DataSourceLoader servlet.
canView:false, and
thus effectively be inert and unusable on the clienthidden. By default,
this means that DataBoundComponents will not show the
field, though this can be overridden for individual components. If you do choose to unhide
the field, bear in mind that it will never actually show any data, because the underlying
security test has still failedviewRequiresAuthentication on a field implies editRequiresAuthentication. You override this behavior simply by specifying some kind
of edit constraint for the field, either a different one (eg, "users" can view a field, but
only "managers" can update it) or a blank one (if you have some unusual requirement whereby
users are not allowed to view a field, but they can update it).
Default value is null
public java.lang.Integer imageWidth
ViewFileItem as
an editor.
Default value is null
public java.lang.Boolean canExport
ListGrid fields.
Default value is null
public java.lang.String foreignKey
The format of foreignKey is
<dataSourceId>.<fieldName>.
For a foreignKey within the same dataSource, you can omit the dataSourceId
and just specify <fieldName>.
For example, to create a tree relationship within a DataSource:
isc.DataSource.create({
ID:"supplyItem",
fields : [
{name:"itemId", type:"sequence", primaryKey:true},
{name:"parentId", type:"integer", foreignKey:"itemId"},
...
]
});
foreignKey declarations also allow other automatic behaviors by
DataBoundComponents, such as ListGrid.fetchRelatedData.
For SQLDataSources foreign keys can be automatically discovered from SQL tables if
autoDeriveSchema is set.
Default value is false
public java.lang.Boolean multiple
XML or JSON data is singular,
it will be wrapped in an Array.
For simple Criteria, the criteria value is compared to each field value in the
multiple:true field, according to the
textMatchStyle. If any
field value matches the
filter value, the field is considered to match the criteria.
For AdvancedCriteria, for normal search operators the field
value is considered as matching the Criterion if any of the field values
match the Criterion. Specifically, this is true of all operators that have an
operatorValueType of "fieldType" or
"valueRange".
For operators that compare against other fields in same record, such as "equalsField",
if the other field is not multiple:true, matching works the same as for
normal operators, that is, as if criterion.value directly contained the value
rather than the name of another field.
If the other field is also multiple:true, only "equalsField", "notEqualsField",
"iEqualsField" and "iNotEqualsField" are allowed (any other operator will
cause a warning and be ignored) and the set of values in the field must be identical (aside
from case, for operators prefixed with "i") and in identical order to match.
For the inSet operator, the field matches if there is any intersection between
the field values and the array of values provided in criterion.value.
notInSet is the reverse.
Finally, for "isNull" and "isNotNull", an empty Array is considered non-null. For example,
if you use dataFormat:"json" and the field value is provided to the browser as
[] (JSON for an empty Array), the field is considered non-null.
Specifically for XML serialization and deserialization, multiple:true behaves
similarly to the
SOAP array idiom,
that is,
there will be a "wrapper element" named after the field name, whose contents will be several
elements of the specified field.type.
For example, members is declared
with type:"Canvas",
multiple:true. The correct XML format is thus:
<VLayout>
<members>
<Canvas ID="myCanvas" ... />
<ListGrid ID="myGrid" .../>
<Toolstrip ID="myToolStrip" ... />
</members>
</VLayout>
See childTagName for
customizing the tagName used for subelements.
Default value is null
public java.lang.String sqlDateFormat
sqlStorageStrategy of
"number" or "text", this property allows you to specify the format Smart GWT should use to map
to/from the underlying value stored in the database. The string provided must be a valid
SimpleDateFormat pattern string. For fields of type "datetime" and "time" that specify
an sqlStorageStrategy of "number", two special sqlDateFormat values are supported:
This property and the "number" and "text" strategies for date/datetime fields are provided to allow transparent two-way mapping of legacy date values that are stored in numeric or text columns respectively rather than a true "date" column. You would not ordinarily use them in the absence of a legacy database.
Note that this property only applies to users of Smart GWT server and data sources of type "sql".
Default value is null
public java.lang.Boolean creatorOverrides
dataSource.creatorOverrides.
This setting overrides dataSource.creatorOverrides, for this field only. Note
that field-level creatorOverrides is conceptually slightly different to the
setting at DataSource and OperationBinding levels. To give the example of a fetch operation,
at the other two levels, it results in a limited set of rows being returned, rather than a
security exception being thrown. At the field-level, it results in values for individual
fields being present in those rows, rather than them being stripped out on the server.
Default value is null
public java.lang.String editRequiresRole
requiresRole for further details of Smart GWT's declarative role-based security. Please also
see editRequiresAuthentication for details of how declarative field-level security settings can be
overridden per-request. NOTE: This property prevents both initialization and updates
for a field. If you have a need to prevent just initialization or just
updates, you can use initRequiresRole or updateRequiresRole.
Default value is null
public java.lang.Boolean canEdit
false to draw this field read-only. For a field that should never be changed
from the UI, consider using canSave instead, which will both mark a field as non-editable and reject any attempt to
programmatically change the value on the server (when using the Smart GWT Server).
This
attribute may not effect all dataBoundComponents - the canEditFieldAttribute
may be set at the component level to look for a different attribute on the dataSourceField, and
components allow developers to explicitly override this default (see canEdit. canEdit for example).
Default value is null
public java.lang.String sequenceName
serverType:"sql" with a field of type
"sequence", the name of the SQL sequence that should be used when inserting new records into
this table.
Note that this is never required for SQL tables that are generated from Smart GWT DataSources (a default sequence name of tableName + "_" + columnName is chosen, but see the notes below regarding this), and is never required for databases where inserting null into a sequence column is sufficient (MySQL, SQL Server, DB2 and others).
You would only need to set sequenceName if you are integrating with a pre-existing table stored in a database where the sequence must be named for insertion to work (Oracle, Postgres, Firebird) OR you are trying to use the same sequence across multiple DataSources.
Note: If you specify the sql.{database type}.sequence.name.prefix and/or
sql.{database type}.sequence.name.suffix properties in your
server.properties
file,the generated sequence name will include the prefix and/or
suffix. For example, with a prefix of "order_system_" and a suffix of "_seq", the sequence
generated for column "orderNumber" on table "orders" would be:
order_system_orders_orderNumber_seq
Default value is null
public DateDisplayFormat displayFormat
Default value is null
public java.lang.String customSelectExpression
partialName where this value is set to
SUBSTR(surname, 2), the generated SQL would look similar to this:
SELECT ... SUBSTR(surname, 2) AS partialName ...
Note that adding "AS partialName" as shown above is required - this is how the framework
identifies the expression as producing a value for this particular DataSourceField when
results are received from the database.
Fields with customSelectExpression set can be used for sorting and filtering in
the normal way, but they are only applicable to update-type operations if you also provide a
corresponding customUpdateExpression and/or
customInsertExpression. See the documentation
for those methods for the rules of how they are applied.
You can use Velocity expressions in your customSelectExpressions, and the
usual context variables are available. Note
that the results
of Velocity evaluations are automatically quoted and escaped by default; this behavior can
be switched off - see autoQuoteCustomExpressions, and
particularly note the warnings about its use.
Note that this property only applies to users of the Smart GWT server using dataSources of type "sql".
Default value is null
public FormItem readOnlyEditorType
canEdit false and displayed in an
editor component such as a DynamicForm. This property may also be specified at the type
level by specifying readOnlyEditorType.
Default value is null
public java.lang.Integer imageSize
ViewFileItem as an editor.
Default value is null
public java.lang.Integer decimalPad
For example, a field value of 343.1, 343.104 and 343.09872677 would all be shown as 343.10 if decimalPad is 2.
The original unpadded value is always shown when the value is edited.
Default value is null
public java.lang.Boolean autoGenerated
Default value is null
public FormItem editorType
If unset, a FormItem will be automatically chosen based on the type of
the field, by the rules explained here.
Default value is null
public java.lang.Integer maxFileSize
FieldType), this
sets the maximum file size allowed, in bytes.
Default value is null
public VelocityExpression viewRequires
VelocityExpression must evaluate
to true if values for the field are to be fetched. If the specified expression does not
evaluate to true, the field will be dropped as described for viewRequiresAuthentication. In addition to the normal context variables available to
Velocity expressions in Smart GWT, expressions you write for field-level requires
clauses - viewRequires, editRequires, initRequires and updateRequires - can
reference two additional variables: $fieldName and $dsName. These
are the names of the dataSource and field currently undergoing requires checks.
They are helpful because they allow you to write a generic checker function that can be used to
handle requires checks for multiple fields and dataSources.
Default value is null
public java.lang.String tableName
tableName indicates that this field
will be coming from another table by way of a customized SQL query. By default, the SQL generator will not include this field in generated SQL for "add" or "update" operations. It will include the field in the SELECT clause and WHERE clause of customized "fetch" operations, where it is expected that you will make the table available via a custom <tableClause> as shown in this sample.
The table name will also be used to qualifying the
column name unless qualifyColumnNames or qualifyColumnNames has
been disabled.
Note: This property is only required when including fields from
tables other than the default table specified by tableName.
Default value is null
nativeNamepublic boolean hidden
See detail for fields that should be
hidden in a summary view such as a ListGrid, but still
available to the user.
NOTE: This property is not a security setting - data
for hidden fields is still delivered to the client, it just isn't shown to the user. If you
wish to make sure that only appropriate data reaches the client, use outputs, canView:false on the field, or a
field-level declarative security setting like viewRequiresRole.
Default value is false
public java.lang.Integer precision
For example, a field value of 343.1, 343.104 and 343.09872677 would all be shown as 343.10 if precision is 5.
The original value is always shown when the value is edited.
Default value is null
public java.lang.Boolean propertiesOnly
ComponentSchema for fields that contain other
components, this flag
suppresses auto-construction for subcomponents that appear under this field.
For example, the VLayout schema sets this for its
members
property, so that when a VLayout is constructed via XML as follows:
<VLayout>
<members>
<ListGrid ID="myGrid" .../>
<Toolstrip ID="myToolStrip" ... />
</members>
</VLayout>
The ListGrid and ToolStrip do not construct themselves automatically. Instead, the VLayout
receives the properties of the ListGrid and ToolStrip as ordinary JavaScript Objects, with
the special property _constructor set to the name of the class that should be
constructed.
Default value is null
public java.lang.String includeFrom
The incluedFrom attribute should be of the form
"dataSourceId.fieldName", for example:
<field includeFrom="supplyItem.itemName"/>
A foreignKey declaration
must exist between the two DataSources, establishing either
a 1-to-1 relationship or a many-to-1 relationship from this DataSource to the related
DataSource. The inclusion can be indirect (traverse multiple DataSources) so long as there
is a chain of foreignKey declarations from the target DataSource to the
DataSource where the includeFrom field is declared.
name will default to the name of
the included field, or you can
specify a different name.
If both DataSources are SQLDataSources, HibernateDataSources or JPADataSources (with Hibernate as the provider) the related data will be retrieved via a SQL join and criteria and sort directions applied to the field work normally (they become part of the generated SQL query).
Otherwise, the related data will be retrieved via performing a DSRequest against
the related DataSource once the data from the primary DataSource has been retrieved. In
this case, criteria or sorting directions applied to the included field are only allowed if
data paging is not in use (for example dataFetchMode:"basic"); otherwise,
criteria and sort direction are ignored for the included field and a warning is logged on
the server.
Editing included fields
An included field is canEdit:false by default. Note that
included fields are not updatable, even if you set canEdit:true; the server will simply drop
values for included fields if client code sends them.
When thinking about editing an included field value, typically what is really intended is to
edit the value of the foreignKey field. For example, take the scenario of a
system that tracks accounts and the employees assigned to manage them. Given a DataSource
"account" related one-to-one with DataSource "employee" by a "managerId" foreignKey field,
we might declare an includeFrom so that the name of the account manager can
be shown with each "account" record.
Editing the manager's name while viewing the account would be intended to pick a new account manager, and not to change the legal name of the employee who happens to be the current account manager.
To correctly set up this scenario, declare an includeFrom field that is hidden,
but is used as the displayField for the foreign key
field:
<field name="managerId" foreignKey="employee.id" displayField="managerName"/> <field name="managerName" includeFrom="employee.name" hidden="true"/>Now:
includeFrom field
optionDataSource
set to "employees": it will allow
picking a different "employee" record from the "employee" DataSource
editorType="ComboBoxItem" on the
"managerId" field to allow typeahead search of the "employee" DataSource.
Default value is null
public java.lang.Integer imageHeight
ViewFileItem as
an editor.
Default value is null
public java.lang.String name
The field name is also the property in each DataSource record which holds the value for this field.
Must be unique across all fields within the DataSource as well as a valid JavaScript identifier, as specified by ECMA-262 Section 7.6.
NOTE: The StringUtil.isValidID() function can be used to test whether a name is a valid JavaScript identifier.
Default value is null
Basics overview and related methodspublic FieldType type
Field type may imply automatic validators (for example, an integer field cannot accept the value "foo"). Field type also affects the default behaviors of DataBound components, for example, if a field is declared as type "date", components that edit that field will automatically choose a date-editing interface with pop-up date picker.
Default value is null
Basics overview and related methodspublic java.lang.Boolean required
Note that
required should not be set for a server-generated field, such as a sequence, or
validation will fail on the client.
Default value is null
public java.lang.Boolean canSave
If set to
false, this field will default to being non-editable in standard editing
components (DynamicForm, editable ListGrid), but will be editable when displayed for filtering
purposes only (in a SearchForm or ListGrid filter editor. If
canEdit is explicitly
specified it will take precedence over this client-side behavior, but the server will still
enforce the no-save policy (described below).
NOTE: If you are using Smart GWT Server and
have specified canSave: false for a field in a DataSource definition
(.ds.xml file), this is enforced on the server. This means that we will strip
out any attempt to set the value of such a field before trying to process any update or add
request, similar to what happens when a field-level
declarative security check fails.
Default value is null
public XPathExpression valueXPath
This XPath expression will be evaluated in the scope of the record objects selected by
the recordXPath. For XML data
(dataFormat:"xml") this means a
call to
XMLTools.selectString passing the
selected XML element. For JSON data
(dataFormat:"json"), this means
a call to
XMLTools.selectObjects passing the
selected JSON object.
In the absence of a valueXPath, for JSON data the value for the field will
be the value of the same-named property in the record object selected by
recordXPath.
For XML data, the value will be the attribute or subelement named after the field name. For example, for a field "author" on a record element <book>, the following structures require no valueXPath:
<book author="Mark Jones"/>
<book>
<author>Mark Jones</author>
</book>
If valueXPath is not required for your field because of the default handling
described above, don't specify it, as it's slightly slower.
To learn about XPath, try the following search: http://www.google.com/search?q=xpath+tutorial
Using valueXPath with the Smart GWT server
If you're using the Smart GWT server to return data via the DSResponse object (or indirectly doing so using DataSource DMI), the valueXPath you specify on the DataSource fields will be applied to the data you return via the JXPath library.
If you are returning Java Beans as your DSResponse data, normally each dataSource field
receives the value of the same-named Java Bean property, that is, a field "zipCode" is
populated by looking for "getZipCode()" on the objects passed as DSResponse data. You can
use valueXPath to retrieve properties from subobjects, so long as a chain of
getter methods exists that corresponds to the valueXPath. For example, a valueXPath of
"address/zipCode" expects to call "getAddress()" on the bean(s) passed to
DSResponse.setData(), followed by "getZipCode()" on whatever object "getAddress()" returns.
When you are saving data, the inbound DSRequest values, available as a Java Map, will use just dataSource field names as Map keys, not the valueXPath used to derive them. However, to achieve bidirectional valueXPath binding, you can use the server-side method dataSource.setProperties() to use the valueXPath when setting properties on your server object model. When applied as a setter, an XPath like "address/zipCode" attempts "getAddress()" followed by "setZipCode()" on the returned object. JXPath also has some ability to auto-create intervening objects if they are missing, such as auto-creating an "address" subobject when applying "address/zipCode" as a valueXPath.
See the JXPath library documentation for complete details, including other types of server object models supported, such as server-side XML.
Default value is null
public java.lang.Boolean updateRequiresAuthentication
Default value is null
public java.lang.Boolean lenientXPath
valueXPath for this field should not perform any validation at all and will return null for
non existing XPaths. Otherwise warning message will be logged for non-existing XPath or with
null objects in the middle of XPath. NOTE: this applies to server-side processing of valueXPath only.
Default value is null
public boolean canSortClientOnly
Default value is false
public java.lang.String sqlTrueValue
sqlStorageStrategy of
"singleChar", this is the value to persist for true values. Note that the common use cases of
storing booleans as T/F, Y/N and 1/0 are already catered for without the need for this
property.sqlStorageStrategy of
"string", this is the value to persist for true values that require using the entire value.
Default value is null
sqlStorageStrategy,
sqlFalseValuepublic java.lang.String nativeName
nativeName is useful for disambiguating in cases where you have customized
SQL. For example, assume you are joining two tables - call them product and
supplier - that both contain a column called "name". Only one field in the
DataSource can be called "name"; to disambiguate, we need to specify both
tableName and
nativeName. A field declaration
like this would be needed:
<field name="supplierName" type="text" tableName="supplier" nativeName="name" />
You may also wish to use this property to map legacy column names to more meaningful field
names in the DataSource. For example:
<field name="productName" type="text" nativeName="PRDNM" />
Default value is null
tableNamepublic java.util.Map valueMap
The valueMap can be specified as either an Array of legal values, or as an
Object where each property maps a stored value to a user-displayable value.
To enforce that a field should be constrained to only the values in the valueMap, either
declare field.type as "enum", or
use a
ValidatorType of "isOneOf" with explicitly listed values.
Otherwise,
although a normal SelectItem control will only
allow values from the valueMap to be
entered, other controls such as a ComboBox will allow other values
to be entered.
In XML, a valueMap that specifies only a list of legal values is specified as follows:
<valueMap>
<value>Pens & Pencils</value>
<value>Stationery</value>
<value>Computer Products</value>
<value>Furniture</value>
<value>Misc</value>
</valueMap>
A ValueMap that specifies stored values mapped to user-visible values is specified as
follows:
<valueMap>
<value ID="1">Pens & Pencils</value>
<value ID="2">Stationery</value>
<value ID="3">Computer Products</value>
<value ID="4">Furniture</value>
<value ID="5">Misc</value>
</valueMap>
Default value is null
public XPathExpression valueWriteXPath
If is not set, then dataSourceField.valueXPath is
used, see its description for details.
Default value is null
public java.lang.String customUpdateExpression
customSelectExpression to provide bi-directional mapping between application data formats and
persisted data formats. Or, it can be used unilaterally as a means of silently enforcing data
rules - for example, ensuring that all values for a given field are in upper case. You can
use Velocity expressions in your customUpdateExpressions, and the usual context variables are available. Note that the
results of Velocity evaluations are automatically quoted and escaped by default; this behavior
can be switched off - see autoQuoteCustomExpressions, and particularly note the warnings about its use.
The value must be a string that will end up as a valid SQL snippet after Velocity evaluation. The following examples are valid:
"'Hello world'""$values.someTextField.toUpperCase()""SUBSTR(ANOTHER_COLUMN,
1, 10)""SUBSTR($values.someTextField.toUpperCase(), 1, 10)""SOME_NUMERIC_COLUMN * 1000""$values.someDateField.getMonth()
+ 1" When an
"update" operation runs, any fields that specify customSelectExpression but do not specify customUpdateExpression will be ignored.
When an "add" operation runs, this property acts as a default for any fields that do not
specify a customInsertExpression; similar to update, any fields that specify a customSelectExpression
but do not specify either a customUpdateExpression or customInsertExpression, will be ignored
when "add" operations run.
Note that this property only applies to users of the Smart GWT server using dataSources of type "sql".
Default value is null
public boolean ignore
If set to true, the field will be entirely omitted when serving a DataSource derived from a server-side definition (typically a .ds.xml file) to the client.
Default value is false
public java.lang.String initRequiresRole
NOTE: This property only prevents initialization of a field; updates
will still be allowed. You should only use this property if you have a special requirement;
ordinarily, use editRequiresRole, which applies security for both types of write.
Default value is null
public java.lang.String fkColumnCode
This read-only attribute is a secure
and unique hashed version of the name of the matching column in the table underlying a
dataSource that this dataSourceField is a foreign key to. It is used
automatically by client-side framework code to link dataSources together by foreign key. This
is necessary if we automatically discovered a foreign key relationship by inspecting the
database schema, as a result of a DataSource specifying autoDeriveSchema: true. We use
a secure hash rather than the column name itself for security reasons - sending the actual
column name to the client would be considered an information leakage that could encourage
attempts at injection attacks.
Default value is null
DataSource.tableCode,
fkTableCodepublic java.lang.Boolean childrenProperty
childrenField to this field's
name.
Default value is false