If this field is editable, this property will be passed to editors displayed for cells within this field as iconHeight. If this property unset, the iconHeight property from the editor can be picked up from iconHeight instead.

If this field is editable, this property will be passed to editors displayed for cells within this field as iconWidth. If this property unset, the iconWidth property from the editor can be picked up from iconWidth instead.

If we're showing the filterEditor (listGrid.showFilterEditor is true), this property determines whether this list should be filtered every time the user edits the value of the filter editor for this field.

Custom titleStyle to apply to this field's header button instead of headerTitleStyle. Note that this will typically only have an effect if headerButtonConstructor is set to StretchImgButton or a subclass thereof.

If this field has type [ListGridFieldType] set to "image" and the URL for the image displayed is not absolute, the path of the URL will be relative to this string Alternatively, if this field displays any valueIcons, this prefix will be applied to the beginning of any valueIcons when determining the URL for the image.

If any cells in this field are showing a value icon (see: valueIcons) or this is has ListGridFieldType set to "image", this the value of this property will be appended to the end of the URL for the icon displayed. Typical usage might be to append a file type such as ".gif" to the filename of the image. For editable fields, this property will also be passed through to any editors as imageURLSuffix.

If optionDataSource is set for this ListGridField, criteria specified in this attribute will be passed to the dataSource when performing the fetch operation to determine data-value to display-value mappings

If this field has an optionDataSource specified and
autoFetchDisplayMap is set, this attribute
provides a way to customize the dataSource request issued to fetch the display map from
the option dataSource.

If this field has an optionDataSource specified and autoFetchDisplayMap is set, this attribute provides a way to customize the operationId passed to dataSource.fetchData() when retrieving the display map from the option dataSource.

For fields with an optionDataSource, where autoFetchDisplayMap is true, this property will govern the textMatchStyle attribute of the DSRequest parameter passed to DataSource.fetchData() when retrieving the remote data set to be used as a basis for this field's valueMap.

When the user edits cells in this field, is this value required to be non-empty in order for validation to pass. Note: for databound listGrids, this property may be specified on the DataSourceField, enabling both client and server side validation.

If showGroupSummary is true, should this field show a summary value in a summary row when the grid is grouped? If unset, this field will show a summary value in the summary row if an explicit summaryFunction is specified or if a default summary function is defined for the specified field type.

If we're showing a valueIcon for this field should it appear to the left or the right of the text? By default the icon will appear to the left of the textual value - set this to "right" to show the icon on the right of the text.

If this field is editable, this property will be passed to editors displayed for cells within this field as iconHeight. If this property unset, the iconHeight property from the editor can be picked up from iconHeight instead.

If this field is editable, this property will be passed to editors displayed for cells within this field as iconWidth. If this property unset, the iconWidth property from the editor can be picked up from iconWidth instead.

If we're showing the filterEditor (listGrid.showFilterEditor is true), this property determines whether this list should be filtered every time the user edits the value of the filter editor for this field.

Custom titleStyle to apply to this field's header button instead of headerTitleStyle. Note that this will typically only have an effect if headerButtonConstructor is set to StretchImgButton or a subclass thereof.

If this field has type [ListGridFieldType] set to "image" and the URL for the image displayed is not absolute, the path of the URL will be relative to this string Alternatively, if this field displays any valueIcons, this prefix will be applied to the beginning of any valueIcons when determining the URL for the image.

If any cells in this field are showing a value icon (see: valueIcons) or this is has ListGridFieldType set to "image", this the value of this property will be appended to the end of the URL for the icon displayed. Typical usage might be to append a file type such as ".gif" to the filename of the image. For editable fields, this property will also be passed through to any editors as imageURLSuffix.

If optionDataSource is set for this ListGridField, criteria specified in this attribute will be passed to the dataSource when performing the fetch operation to determine data-value to display-value mappings

Derive a ValueMap by fetching records from another DataSource and extracting the valueField and displayField in the loaded records, to derive one valueMap entry per record loaded from the optionDataSource.

If this field has an optionDataSource specified and
autoFetchDisplayMap is set, this attribute
provides a way to customize the dataSource request issued to fetch the display map from
the option dataSource.

If this field has an optionDataSource specified and autoFetchDisplayMap is set, this attribute provides a way to customize the operationId passed to dataSource.fetchData() when retrieving the display map from the option dataSource.

For fields with an optionDataSource, where autoFetchDisplayMap is true, this property will govern the textMatchStyle attribute of the DSRequest parameter passed to DataSource.fetchData() when retrieving the remote data set to be used as a basis for this field's valueMap.

When the user edits cells in this field, is this value required to be non-empty in order for validation to pass. Note: for databound listGrids, this property may be specified on the DataSourceField, enabling both client and server side validation.

If showGroupSummary is true, should this field show a summary value in a summary row when the grid is grouped? If unset, this field will show a summary value in the summary row if an explicit summaryFunction is specified or if a default summary function is defined for the specified field type.

If we're showing a valueIcon for this field should it appear to the left or the right of the text? By default the icon will appear to the left of the textual value - set this to "right" to show the icon on the right of the text.

Array of legal values for this field, or an Object where each property maps a stored value to a user-displayable value. Note that if this field is editable (see canEdit, canEdit), editors displayed for this field will pick up their valueMap either from this value or from editorValueMap.

Array of legal values for this field, or an Object where each property maps a stored value to a user-displayable value. Note that if this field is editable (see canEdit, canEdit), editors displayed for this field will pick up their valueMap either from this value or from editorValueMap.

ListGridField

Method Detail

getOrCreateRef

setApplyAfterSummary

public void setApplyAfterSummary(java.lang.Boolean applyAfterSummary)

If userFormula is set for this field, and this grid is showing group summaries or a grid summary, this property determines what field value should be present in those summary rows. Should the field apply the user-formula to the calculated summary row, or should it apply a standard grid or group summary to the user-formula values displayed in the grid?

getApplyAfterSummary

public java.lang.Boolean getApplyAfterSummary()

If userFormula is set for this field, and this grid is showing group summaries or a grid summary, this property determines what field value should be present in those summary rows. Should the field apply the user-formula to the calculated summary row, or should it apply a standard grid or group summary to the user-formula values displayed in the grid?

setAutoFitWidthApproach

When a user requests column autofitting via the header contextmenu or via a mouse gesture, what autofit approach is used. If set, this setting overrides the autoFitWidthApproach specified at the ListGrid level.

Parameters:

autoFitWidthApproach - Default value is null

getAutoFitWidthApproach

When a user requests column autofitting via the header contextmenu or via a mouse gesture, what autofit approach is used. If set, this setting overrides the autoFitWidthApproach specified at the ListGrid level.

Returns:

AutoFitWidthApproach

setAutoFreeze

public void setAutoFreeze(java.lang.Boolean autoFreeze)

Whether this field should be automatically frozen when other fields are frozen. When true, the field will be automatically frozen to the extreme of the grid. The automatically generated checkbox, expansion and rowNumber fields are examples of fields that specify autoFreeze: true.

getAutoFreeze

public java.lang.Boolean getAutoFreeze()

Whether this field should be automatically frozen when other fields are frozen. When true, the field will be automatically frozen to the extreme of the grid. The automatically generated checkbox, expansion and rowNumber fields are examples of fields that specify autoFreeze: true.

setCanDragResize

Whether this field can be dragResized using the mouse. If unset, the default behavior is governed by canResizeFields.

Parameters:

canDragResize - Default value is null

getCanDragResize

public java.lang.Boolean getCanDragResize()

Whether this field can be dragResized using the mouse. If unset, the default behavior is governed by canResizeFields.

Returns:

Boolean

setCanEdit

public void setCanEdit(java.lang.Boolean canEdit)

Can this field be edited? May be overridden by setting the 'canEdit' property at the listGrid level. If not explicitly set and this grid is bound to a dataSource, the canEditFieldAttribute may be used to set default editability at the field level.

getCanEdit

public java.lang.Boolean getCanEdit()

Can this field be edited? May be overridden by setting the 'canEdit' property at the listGrid level. If not explicitly set and this grid is bound to a dataSource, the canEditFieldAttribute may be used to set default editability at the field level.

getCanGroupBy

setCanHide

public void setCanHide(java.lang.Boolean canHide)

If set to false, this field will be omitted from the column picker that appears in the header context menu when canPickFields is enabled. This means that the end user will not be able to hide it if it's currently shown, or show it if it's currently hidden.

If this property is set to false, and the advanced field picker is shown, if the field is hidden, the field will not show in the list of available fields. If the field is visible, it will be displayed in the list of currently visible fields, but the advanced field picker user interface will disallow hiding it.

getCanHide

public java.lang.Boolean getCanHide()

If set to false, this field will be omitted from the column picker that appears in the header context menu when canPickFields is enabled. This means that the end user will not be able to hide it if it's currently shown, or show it if it's currently hidden.

If this property is set to false, and the advanced field picker is shown, if the field is hidden, the field will not show in the list of available fields. If the field is visible, it will be displayed in the list of currently visible fields, but the advanced field picker user interface will disallow hiding it.

setCanHilite

Determines whether this field can be hilited. Set to false to prevent this field from appearing in HiliteEditor.

Parameters:

canHilite - Default value is null

getCanHilite

public java.lang.Boolean getCanHilite()

Determines whether this field can be hilited. Set to false to prevent this field from appearing in HiliteEditor.

Returns:

Boolean

setCanReorder

public void setCanReorder(java.lang.Boolean canReorder)

Whether this field can be reordered using the mouse. If unset, the default behavior is governed by canReorderFields. Note that setting this property to false will lock this field from being moved - that is, the user is prevented from moving this field directly by dragging with the mouse, or by dropping another field onto this field. However, unless this field is at the extreme edge of the grid, or all fields between it and the extreme edge of the grid are also canReorder: false, (ie, if there are unlocked fields on either side of this field), then it is possible that this locked field may be reordered automatically, as a result of the user dragging one unlocked field onto another unlocked field.

Parameters:

canReorder - Default value is null

getCanReorder

public java.lang.Boolean getCanReorder()

Whether this field can be reordered using the mouse. If unset, the default behavior is governed by canReorderFields. Note that setting this property to false will lock this field from being moved - that is, the user is prevented from moving this field directly by dragging with the mouse, or by dropping another field onto this field. However, unless this field is at the extreme edge of the grid, or all fields between it and the extreme edge of the grid are also canReorder: false, (ie, if there are unlocked fields on either side of this field), then it is possible that this locked field may be reordered automatically, as a result of the user dragging one unlocked field onto another unlocked field.

Returns:

Boolean

setCanSort

public void setCanSort(java.lang.Boolean canSort)

Enables or disables sorting by this column. If false, interactive sorting via header-clicks or menu-items will have no effect, but direct scripted calls to sort() or setSort() will work as expected.

setCanSortClientOnly

When true, this field can only be used for sorting if the data is entirely client-side.

Parameters:

canSortClientOnly - Default value is false

getCanSortClientOnly

public java.lang.Boolean getCanSortClientOnly()

When true, this field can only be used for sorting if the data is entirely client-side.

Returns:

Boolean

setCanToggle

public void setCanToggle(java.lang.Boolean canToggle)

Allows a boolean or valueMapped field to be edited without going into edit mode. When this attribute is set, clicking on the field will change the value - for boolean fields toggling between true and false, and for valueMapped fields, advancing the value to the next option in the valueMap.

To enable this feature, canEdit must be set to true. For boolean type fields canToggle is true by default, meaning setting canEdit to true implies the user can toggle the value via a single click without going into edit mode. You can disable this by explicitly setting canToggle to false for a boolean field. Note that you can enable toggling only (without allowing the user to edit other fields) by just setting grid.editEvent:"none".

If editEvent is set to "click", when the user clicks on the field, the value will be toggled, and inline editing will be triggered as usual. Otherwise the toggled value will be saved immediately to the server, or if autoSaveEdits has been set to false, will be stored as an edit value for the record.

getCanToggle

public java.lang.Boolean getCanToggle()

Allows a boolean or valueMapped field to be edited without going into edit mode. When this attribute is set, clicking on the field will change the value - for boolean fields toggling between true and false, and for valueMapped fields, advancing the value to the next option in the valueMap.

To enable this feature, canEdit must be set to true. For boolean type fields canToggle is true by default, meaning setting canEdit to true implies the user can toggle the value via a single click without going into edit mode. You can disable this by explicitly setting canToggle to false for a boolean field. Note that you can enable toggling only (without allowing the user to edit other fields) by just setting grid.editEvent:"none".

If editEvent is set to "click", when the user clicks on the field, the value will be toggled, and inline editing will be triggered as usual. Otherwise the toggled value will be saved immediately to the server, or if autoSaveEdits has been set to false, will be stored as an edit value for the record.

setCellAlign

Horizontal alignment for cells in this field's column: "left", "right" or "center". If null, alignment is derived from align. If this field is editable, the alignment of cells in the body will also be reflected in any editors for the field.

getCellAlign

Horizontal alignment for cells in this field's column: "left", "right" or "center". If null, alignment is derived from align. If this field is editable, the alignment of cells in the body will also be reflected in any editors for the field.

setDateFormatter

The timeFormatter may also be used to format underlying Date values as times (ommitting the date part entirely). If both dateFormatter and timeFormatter are specified on a field, for fields specified as type "time" the timeFormatter will be used, otherwise the dateFormatter

If field.dateFormatter and field.timeFormatter is unspecified, date display format may be defined at the component level via ListGrid.dateFormatter, or for fields of type "datetime"ListGrid.datetimeFormatter. Otherwise the default is to use the system-wide default short date format, configured via Date.setShortDisplayFormat(). Specify any valid DateDisplayFormat to change the format used by this item.

If this field is editable the dateFormatter will also be passed to the editor created to edit this field. Note that you can also specify an explicit inputFormat which will be passed through to the editor as well, though this is not typically required as the input format should be automatically derived by the Smart GWT system for standard DateDisplayFormats.

getDateFormatter

The timeFormatter may also be used to format underlying Date values as times (ommitting the date part entirely). If both dateFormatter and timeFormatter are specified on a field, for fields specified as type "time" the timeFormatter will be used, otherwise the dateFormatter

If field.dateFormatter and field.timeFormatter is unspecified, date display format may be defined at the component level via ListGrid.dateFormatter, or for fields of type "datetime"ListGrid.datetimeFormatter. Otherwise the default is to use the system-wide default short date format, configured via Date.setShortDisplayFormat(). Specify any valid DateDisplayFormat to change the format used by this item.

If this field is editable the dateFormatter will also be passed to the editor created to edit this field. Note that you can also specify an explicit inputFormat which will be passed through to the editor as well, though this is not typically required as the input format should be automatically derived by the Smart GWT system for standard DateDisplayFormats.

setDefaultWidth

Optional "default width" for this field. If set, this value will be returned by the ListGrid.getDefaultFieldWidth() method, and used as the autoFit size for the field's content.

Parameters:

defaultWidth - Default value is null

getDefaultWidth

public java.lang.Integer getDefaultWidth()

Optional "default width" for this field. If set, this value will be returned by the ListGrid.getDefaultFieldWidth() method, and used as the autoFit size for the field's content.

Returns:

Integer

setDisplayField

public void setDisplayField(java.lang.String displayField)

Specifies the optionDataSource field used to retrieve the display values that are to be mapped from the internal values specified by valueField.

If no optionDataSource is defined for the field, the cell will display the displayField value for the current record instead of the underlying value for this field. This approach can be used for situations where field values need a stored value to displayed value mapping, but the set of all possible values is too large to load as a com.smartgwt.client.types.ValueMap - see optionDataSource for more details on this approach. Note that if this field is editable this will also be applied to this field's editors. This sample illustrates this approach achieved via a server-side SQL join.

getDisplayField

public java.lang.String getDisplayField()

Specifies the optionDataSource field used to retrieve the display values that are to be mapped from the internal values specified by valueField.

If no optionDataSource is defined for the field, the cell will display the displayField value for the current record instead of the underlying value for this field. This approach can be used for situations where field values need a stored value to displayed value mapping, but the set of all possible values is too large to load as a com.smartgwt.client.types.ValueMap - see optionDataSource for more details on this approach. Note that if this field is editable this will also be applied to this field's editors. This sample illustrates this approach achieved via a server-side SQL join.

setDisplayValueFromRecord

If a displayField is set, should this field show record values from the displayField?

If displayField is specified, and there is no separate optionDataSource, by default we will show display-field values from the same record. Setting this property to false would disable this behavior.

Alternatively, if there is a optionDataSource (and autoFetchDisplayMap is false), the displayField would be ignored for the field and the underlying record[fieldName] value would be displayed to the user. This property may be set to true to override this behavior and pick up values from the displayField for display in this field even when there is an optionDataSource set.

Note that this property has no effect on fields with an explicitly specified valueMap, or with an optionDataSource where autoFetchDisplayMap is true.

Note : This is an advanced setting

Parameters:

displayValueFromRecord - Default value is null

getDisplayValueFromRecord

public java.lang.Boolean getDisplayValueFromRecord()

If a displayField is set, should this field show record values from the displayField?

If displayField is specified, and there is no separate optionDataSource, by default we will show display-field values from the same record. Setting this property to false would disable this behavior.

Alternatively, if there is a optionDataSource (and autoFetchDisplayMap is false), the displayField would be ignored for the field and the underlying record[fieldName] value would be displayed to the user. This property may be set to true to override this behavior and pick up values from the displayField for display in this field even when there is an optionDataSource set.

Note that this property has no effect on fields with an explicitly specified valueMap, or with an optionDataSource where autoFetchDisplayMap is true.

Returns:

Boolean

setEditorIconHeight

public void setEditorIconHeight(java.lang.Integer editorIconHeight)

If this field is editable, this property will be passed to editors displayed for cells within this field as iconHeight. If this property unset, the iconHeight property from the editor can be picked up from iconHeight instead.

getEditorIconHeight

public java.lang.Integer getEditorIconHeight()

If this field is editable, this property will be passed to editors displayed for cells within this field as iconHeight. If this property unset, the iconHeight property from the editor can be picked up from iconHeight instead.

setEditorIconWidth

public void setEditorIconWidth(java.lang.Integer editorIconWidth)

If this field is editable, this property will be passed to editors displayed for cells within this field as iconWidth. If this property unset, the iconWidth property from the editor can be picked up from iconWidth instead.

getEditorIconWidth

public java.lang.Integer getEditorIconWidth()

If this field is editable, this property will be passed to editors displayed for cells within this field as iconWidth. If this property unset, the iconWidth property from the editor can be picked up from iconWidth instead.

setEditorImageURLPrefix

When some cell in this field is being edited, this property can be used to apply an explicit imageURLPrefix to the editor in question. This can be used to modify the valueIcons within the editor. If unset, but imageURLPrefix is specified, that will be used instead.

getEditorImageURLPrefix

public java.lang.String getEditorImageURLPrefix()

When some cell in this field is being edited, this property can be used to apply an explicit imageURLPrefix to the editor in question. This can be used to modify the valueIcons within the editor. If unset, but imageURLPrefix is specified, that will be used instead.

setEditorImageURLSuffix

When some cell in this field is being edited, this property can be used to apply an explicit imageURLSuffix to the editor in question. This can be used to modify the valueIcons within the editor. If unset, but imageURLPrefix is specified, that will be used instead.

getEditorImageURLSuffix

public java.lang.String getEditorImageURLSuffix()

When some cell in this field is being edited, this property can be used to apply an explicit imageURLSuffix to the editor in question. This can be used to modify the valueIcons within the editor. If unset, but imageURLPrefix is specified, that will be used instead.

setEditorValueIconHeight

When some cell in this field is being edited, setting this property will specify the height for value icons in the cell's editor. If unset, the editor's valueIcon width and height will be determined in the same way as it would be for a static cell.

getEditorValueIconHeight

public java.lang.Integer getEditorValueIconHeight()

When some cell in this field is being edited, setting this property will specify the height for value icons in the cell's editor. If unset, the editor's valueIcon width and height will be determined in the same way as it would be for a static cell.

setEditorValueIcons

When some cell in this field is being edited, setting this property will specify the value icons to display in the cell's editor. If unset, the editor's valueIcons will be determined in the same way as it would be for a static cell.

setEditorValueIconWidth

When some cell in this field is being edited, setting this property will specify the width for value icons in the cell's editor. If unset, the editor's valueIcon width and height will be determined in the same way as it would be for a static cell.

getEditorValueIconWidth

public java.lang.Integer getEditorValueIconWidth()

When some cell in this field is being edited, setting this property will specify the width for value icons in the cell's editor. If unset, the editor's valueIcon width and height will be determined in the same way as it would be for a static cell.

setEscapeHTML

public void setEscapeHTML(java.lang.Boolean escapeHTML)

By default HTML values in ListGrid cells will be interpreted by the browser. Setting this flag to true will causes HTML characters to be escaped, meaning the raw value of the field (for example "<b>AAA</b>") is displayed to the user rather than the interpreted HTML (for example "AAA")

Parameters:

escapeHTML - Default value is null

getEscapeHTML

public java.lang.Boolean getEscapeHTML()

By default HTML values in ListGrid cells will be interpreted by the browser. Setting this flag to true will causes HTML characters to be escaped, meaning the raw value of the field (for example "<b>AAA</b>") is displayed to the user rather than the interpreted HTML (for example "AAA")

setExportFieldWidth

public void setExportFieldWidth(boolean exportFieldWidth)

When exporting data to Excel/OpenOffice format using ListGrid.exportData() or ListGrid.exportClientData() with exportFieldWidths set, set this flag false to cause this field to "opt out" of width export. Fields that opt out in this way have the corresponding spreadsheet column autosized (ie, made just wide enough that content is not clipped).

This setting has no effect if listGrid.exportFieldWidths is not set.

Parameters:

exportFieldWidth - Default value is true

getExportFieldWidth

public boolean getExportFieldWidth()

When exporting data to Excel/OpenOffice format using ListGrid.exportData() or ListGrid.exportClientData() with exportFieldWidths set, set this flag false to cause this field to "opt out" of width export. Fields that opt out in this way have the corresponding spreadsheet column autosized (ie, made just wide enough that content is not clipped).

setExportRawValues

public void setExportRawValues(java.lang.Boolean exportRawValues)

Dictates whether the data in this field should be exported raw by exportClientData(). If set to true for a field, the values in the field-formatters will not be executed for data in this field. Decreases the time taken for large exports.

Parameters:

exportRawValues - Default value is null

getExportRawValues

public java.lang.Boolean getExportRawValues()

Dictates whether the data in this field should be exported raw by exportClientData(). If set to true for a field, the values in the field-formatters will not be executed for data in this field. Decreases the time taken for large exports.

setFilterEditorValueMap

If this listGrid is showing a filter row, this property can be used to specify a mapping of internal data to/from display values to be in the appropriate filter row form item.

Parameters:

filterEditorValueMap - Default value is null

setFilterOnKeypress

public void setFilterOnKeypress(java.lang.Boolean filterOnKeypress)

If we're showing the filterEditor (listGrid.showFilterEditor is true), this property determines whether this list should be filtered every time the user edits the value of the filter editor for this field.

Note : This is an advanced setting

Parameters:

filterOnKeypress - Default value is null

getFilterOnKeypress

public java.lang.Boolean getFilterOnKeypress()

If we're showing the filterEditor (listGrid.showFilterEditor is true), this property determines whether this list should be filtered every time the user edits the value of the filter editor for this field.

Returns:

Boolean

setFilterOperator

With the FilterEditor showing, the Operator to use when matching values for this field.

Note that you can set all FilterEditor fields to default to either substring or exact match via autoFetchTextMatchStyle, but if you want a mix of exact vs substring match on different fields, you need to use this property, and your ListGrid will produce AdvancedCriteria rather than the simpler Criteria format. This is automatically and transparently handled by the Smart GWT Server's SQLDataSource and HibernateDataSource in Power Edition or above, but if you have your own filtering implementation, it will need to be able to handle AdvancedCriteria.

Parameters:

filterOperator - Default value is null

getFilterOperator

With the FilterEditor showing, the Operator to use when matching values for this field.

Note that you can set all FilterEditor fields to default to either substring or exact match via autoFetchTextMatchStyle, but if you want a mix of exact vs substring match on different fields, you need to use this property, and your ListGrid will produce AdvancedCriteria rather than the simpler Criteria format. This is automatically and transparently handled by the Smart GWT Server's SQLDataSource and HibernateDataSource in Power Edition or above, but if you have your own filtering implementation, it will need to be able to handle AdvancedCriteria.

setGroupGranularity

Groups will be formed based on ranges of values of size groupGranularity. For example, if groupGranularity were 1000, groups would be 0-1000, 1000-2000, etc.

Parameters:

groupGranularity - Default value is null

getGroupGranularity

public java.lang.Integer getGroupGranularity()

Granularity of grouping for numeric fields.

Groups will be formed based on ranges of values of size groupGranularity. For example, if groupGranularity were 1000, groups would be 0-1000, 1000-2000, etc.

Returns:

Integer

setGroupingMode

public void setGroupingMode(java.lang.String groupingMode)

For a field that allows multiple grouping modes, the current grouping mode.

This property is set when a user chooses a particular grouping mode, and may be set on ListGrid creation to affect the initial grouping.

Parameters:

groupingMode - Default value is null

getGroupingMode

public java.lang.String getGroupingMode()

For a field that allows multiple grouping modes, the current grouping mode.

This property is set when a user chooses a particular grouping mode, and may be set on ListGrid creation to affect the initial grouping.

Returns:

String

setGroupingModes

public void setGroupingModes(java.util.Map groupingModes)

If set, provides several possible styles of grouping that are valid for this field. For example, a field of type:"date" might be able to be grouped by week, month, or by day of week.

If groupingModes are present and grouping is enabled, the menu for this field includes a submenu of possible grouping modes generated from the groupingModes valueMap. When the user selects a particular grouping mode, field.groupingMode is set to the user's chosen mode, and this choice can be detected via the field parameter to ListGridField.getGroupValue() in order to provide different modes of grouping.

The user may also choose to group records without specifying a grouping mode, in this case, the defaultGroupingMode is used.

Note that getGroupValue, groupingModes et al can be specified on SimpleType declarations, and the different grouping modes that are offered automatically for various common types are defined this way.

Parameters:

groupingModes - Default value is null

getGroupingModes

public java.util.Map getGroupingModes()

If set, provides several possible styles of grouping that are valid for this field. For example, a field of type:"date" might be able to be grouped by week, month, or by day of week.

If groupingModes are present and grouping is enabled, the menu for this field includes a submenu of possible grouping modes generated from the groupingModes valueMap. When the user selects a particular grouping mode, field.groupingMode is set to the user's chosen mode, and this choice can be detected via the field parameter to ListGridField.getGroupValue() in order to provide different modes of grouping.

The user may also choose to group records without specifying a grouping mode, in this case, the defaultGroupingMode is used.

Note that getGroupValue, groupingModes et al can be specified on SimpleType declarations, and the different grouping modes that are offered automatically for various common types are defined this way.

Returns:

Map

setGroupPrecision

public void setGroupPrecision(java.lang.Integer groupPrecision)

For fields of type:"float" or derived from float, number of digits after the decimal point to consider when grouping.

For example, groupPrecision:2 indicates that 45.238 and 45.231 group together, but 45.22 and 45.27 are separate.

setHeaderHoverDelay

If unset, any hoverDelay will be used for both header hovers and hovers shown over cells in the grid's body.

Parameters:

headerHoverDelay - Default value is null

getHeaderHoverDelay

public java.lang.Integer getHeaderHoverDelay()

Delay in ms for hovers shown over this field's header.

If unset, any hoverDelay will be used for both header hovers and hovers shown over cells in the grid's body.

Returns:

Integer

setHeaderTitle

public void setHeaderTitle(java.lang.String headerTitle)

Optional title for the header button for this field. If specified this will be displayed in the header button instead of title or name. Set to an empty string to suppress the title in the header button entirely.

getHeaderTitle

public java.lang.String getHeaderTitle()

Optional title for the header button for this field. If specified this will be displayed in the header button instead of title or name. Set to an empty string to suppress the title in the header button entirely.

setHeaderTitleStyle

public void setHeaderTitleStyle(java.lang.String headerTitleStyle)

Custom titleStyle to apply to this field's header button instead of headerTitleStyle. Note that this will typically only have an effect if headerButtonConstructor is set to StretchImgButton or a subclass thereof.

getHeaderTitleStyle

public java.lang.String getHeaderTitleStyle()

Custom titleStyle to apply to this field's header button instead of headerTitleStyle. Note that this will typically only have an effect if headerButtonConstructor is set to StretchImgButton or a subclass thereof.

setHidden

public void setHidden(java.lang.Boolean hidden)

Marks field as initially hidden. The user will still be able to show the field via a context menu. This may be suppressed by setting canHide to false, or by setting canPickFields to false to suppress the field-picker entirely.

To mark a field as completely hidden (not shown to a user at all, in any component), set hidden instead.

getHidden

public java.lang.Boolean getHidden()

Marks field as initially hidden. The user will still be able to show the field via a context menu. This may be suppressed by setting canHide to false, or by setting canPickFields to false to suppress the field-picker entirely.

To mark a field as completely hidden (not shown to a user at all, in any component), set hidden instead.

setHiliteIconSize

public void setHiliteIconSize(java.lang.Integer hiliteIconSize)

Default width and height of hilite icons in this field. Takes precedence over hiliteIconWidth, hiliteIconHeight and hiliteIconSize specified at the component level. Can be overridden via hiliteIconWidth and hiliteIconHeight

getHiliteIconSize

public java.lang.Integer getHiliteIconSize()

Default width and height of hilite icons in this field. Takes precedence over hiliteIconWidth, hiliteIconHeight and hiliteIconSize specified at the component level. Can be overridden via hiliteIconWidth and hiliteIconHeight

setHoverWrap

public void setHoverWrap(java.lang.Boolean hoverWrap)

This property may be set to customize the wrap attribute for the canvas shown when the mouse hovers over cells in this field. Note that this causes a soft-wrap - if set, the hover text will wrap at word boundaries.

getHoverWrap

public java.lang.Boolean getHoverWrap()

This property may be set to customize the wrap attribute for the canvas shown when the mouse hovers over cells in this field. Note that this causes a soft-wrap - if set, the hover text will wrap at word boundaries.

setIcon

public void setIcon(java.lang.String icon)

Optional icon to show next to the title for this field. Should be set to a URL to an image. Relative paths will be evaluated starting at the imgDir of this component. This URL is partial - it may be updated to indicate the current disabled (etc) state of the field.

getIcon

public java.lang.String getIcon()

Optional icon to show next to the title for this field. Should be set to a URL to an image. Relative paths will be evaluated starting at the imgDir of this component. This URL is partial - it may be updated to indicate the current disabled (etc) state of the field.

setIconHeight

public void setIconHeight(java.lang.Integer iconHeight)

If icon is specified, this property can be used to specify the height of the icon to be displayed in the ListGrid header button. (See iconHeight) If this field is editable, and editorIconHeight is unset, this property will be passed onto the editors for this field as iconWidth, which will effect the default size for icons displayed in the editor.

getIconHeight

public java.lang.Integer getIconHeight()

If icon is specified, this property can be used to specify the height of the icon to be displayed in the ListGrid header button. (See iconHeight) If this field is editable, and editorIconHeight is unset, this property will be passed onto the editors for this field as iconWidth, which will effect the default size for icons displayed in the editor.

setIconWidth

public void setIconWidth(java.lang.Integer iconWidth)

If icon is specified, this property can be used to specify the width of the icon to be displayed in the ListGrid header button. (See iconWidth) If this field is editable, and editorIconWidth is unset, this property will be passed onto the editors for this field as iconWidth, which will effect the default size for icons displayed in the editor.

getIconWidth

public java.lang.Integer getIconWidth()

If icon is specified, this property can be used to specify the width of the icon to be displayed in the ListGrid header button. (See iconWidth) If this field is editable, and editorIconWidth is unset, this property will be passed onto the editors for this field as iconWidth, which will effect the default size for icons displayed in the editor.

setImageURLPrefix

public void setImageURLPrefix(java.lang.String imageURLPrefix)

If this field has type [ListGridFieldType] set to "image" and the URL for the image displayed is not absolute, the path of the URL will be relative to this string Alternatively, if this field displays any valueIcons, this prefix will be applied to the beginning of any valueIcons when determining the URL for the image.

getImageURLPrefix

public java.lang.String getImageURLPrefix()

If this field has type [ListGridFieldType] set to "image" and the URL for the image displayed is not absolute, the path of the URL will be relative to this string Alternatively, if this field displays any valueIcons, this prefix will be applied to the beginning of any valueIcons when determining the URL for the image.

setImageURLSuffix

public void setImageURLSuffix(java.lang.String imageURLSuffix)

If any cells in this field are showing a value icon (see: valueIcons) or this is has ListGridFieldType set to "image", this the value of this property will be appended to the end of the URL for the icon displayed. Typical usage might be to append a file type such as ".gif" to the filename of the image. For editable fields, this property will also be passed through to any editors as imageURLSuffix.

getImageURLSuffix

public java.lang.String getImageURLSuffix()

If any cells in this field are showing a value icon (see: valueIcons) or this is has ListGridFieldType set to "image", this the value of this property will be appended to the end of the URL for the icon displayed. Typical usage might be to append a file type such as ".gif" to the filename of the image. For editable fields, this property will also be passed through to any editors as imageURLSuffix.

setIncludeFrom

public void setIncludeFrom(java.lang.String includeFrom)

Indicates this field's values should be fetched from another, related DataSource. The individual field will inherit settings such as field.type and field.title from the related DataSource just like fields from the primary DataSource.

When fechData() is called, the automatically created DSRequest will specify additionalOutputs requesting the field, and any Criteria generated by the component will likewise refer to the field from the related DataSource.

It's an error to use this property if the ListGrid does not have a DataSource at all. The related DataSource must be loaded or a warning will be logged and the field definition ignored.

This value is expected to be set to the following format dataSourceID.fieldName where dataSourceID is the ID of the related dataSource and fieldName is the name of the field from that dataSource from which you wish to retrieve values. Note that if this property is set and field.name is not explicitly specified, this field's name will default to the fieldName value from this property.

Note about automatic cache updates: "update" and "add" operations submitted automatically by this ListGrid will include dsRequest.additionalOutputs to ensure all data necessary for cache updates is returned by the server.

If your grid shows data that can be edited elsewhere in the UI (not by inline editing), to avoid problems with ResultSet automatic cache synchronization, you may need to switch from using listGridField.includeFrom to dataSourceField.includeFrom. This is because server responses to "add" and "update" operations which are initiated outside of this grid do not know about the listGridField.includeFrom setting, and so will not automatically return data for fields included in this way. Switching to dataSourceField.includeFrom ensures the field is always included in server responses, avoiding the issue.

Parameters:

includeFrom - Default value is null

getIncludeFrom

public java.lang.String getIncludeFrom()

Indicates this field's values should be fetched from another, related DataSource. The individual field will inherit settings such as field.type and field.title from the related DataSource just like fields from the primary DataSource.

When fechData() is called, the automatically created DSRequest will specify additionalOutputs requesting the field, and any Criteria generated by the component will likewise refer to the field from the related DataSource.

It's an error to use this property if the ListGrid does not have a DataSource at all. The related DataSource must be loaded or a warning will be logged and the field definition ignored.

This value is expected to be set to the following format dataSourceID.fieldName where dataSourceID is the ID of the related dataSource and fieldName is the name of the field from that dataSource from which you wish to retrieve values. Note that if this property is set and field.name is not explicitly specified, this field's name will default to the fieldName value from this property.

Note about automatic cache updates: "update" and "add" operations submitted automatically by this ListGrid will include dsRequest.additionalOutputs to ensure all data necessary for cache updates is returned by the server.

If your grid shows data that can be edited elsewhere in the UI (not by inline editing), to avoid problems with ResultSet automatic cache synchronization, you may need to switch from using listGridField.includeFrom to dataSourceField.includeFrom. This is because server responses to "add" and "update" operations which are initiated outside of this grid do not know about the listGridField.includeFrom setting, and so will not automatically return data for fields included in this way. Switching to dataSourceField.includeFrom ensures the field is always included in server responses, avoiding the issue.

Returns:

String

setIncludeInRecordSummary

If a listGrid is showing a field of type summary, should this field be passed to the recordSummaryFunction when calculating the summary value to display. If unset, fields are included if they are of type "integer" or "float" only (since most summary functions perform numeric calculations). See also includeInRecordSummaryFields.

Parameters:

includeInRecordSummary - Default value is null

getIncludeInRecordSummary

public java.lang.Boolean getIncludeInRecordSummary()

If a listGrid is showing a field of type summary, should this field be passed to the recordSummaryFunction when calculating the summary value to display. If unset, fields are included if they are of type "integer" or "float" only (since most summary functions perform numeric calculations). See also includeInRecordSummaryFields.

Returns:

Boolean

setIsRemoveField

public void setIsRemoveField(java.lang.Boolean isRemoveField)

If set to true and canRemoveRecords is true, this field will be rendered as the remove-field for this grid. In most common usage scenarios this field will essentially be a placeholder indicating where the remove field should be rendered, meaning properties other than isRemoveField, such as name or title, may be left unset.

getIsRemoveField

public java.lang.Boolean getIsRemoveField()

If set to true and canRemoveRecords is true, this field will be rendered as the remove-field for this grid. In most common usage scenarios this field will essentially be a placeholder indicating where the remove field should be rendered, meaning properties other than isRemoveField, such as name or title, may be left unset.

May be explicitly specified at the field level or at the grid level. If not explicitly specified space will be left for fields with align set to "left" or "right", but not for fields with align set to "center".

Note : This is an advanced setting

Parameters:

leaveHeaderMenuButtonSpace - Default value is null

setLinkText

public void setLinkText(java.lang.String linkText)

The HTML to display in cells of this field if the fieldType is set to link.

This property sets linkText that will be the same for all records. You can set linkText on a per-record basis via linkText.

setLinkURLPrefix

If this field has type [ListGridFieldType] set to "link", setting this property will apply a standard prefix to the link URL for cells in this field.

Note : This is an advanced setting

Parameters:

linkURLPrefix - Default value is null

getLinkURLPrefix

public java.lang.String getLinkURLPrefix()

If this field has type [ListGridFieldType] set to "link", setting this property will apply a standard prefix to the link URL for cells in this field.

Returns:

String

setLinkURLSuffix

public void setLinkURLSuffix(java.lang.String linkURLSuffix)

If this field has type [ListGridFieldType] set to "link", setting this property will apply a standard suffix to the link URL for cells in this field.

Note : This is an advanced setting

Parameters:

linkURLSuffix - Default value is null

getLinkURLSuffix

public java.lang.String getLinkURLSuffix()

If this field has type [ListGridFieldType] set to "link", setting this property will apply a standard suffix to the link URL for cells in this field.

Returns:

String

setMultiple

public void setMultiple(java.lang.Boolean multiple)

Indicates that this field should always be Array-valued. This property will be passed through to the generated edit-item when editing the field - so if valueMap is set, the default editor will be a SelectItem with multiple set to true.

Note that for databound grids it typically makes sense to set multiple rather than setting the property directly on the ListGridField object.

getMultiple

public java.lang.Boolean getMultiple()

Indicates that this field should always be Array-valued. This property will be passed through to the generated edit-item when editing the field - so if valueMap is set, the default editor will be a SelectItem with multiple set to true.

Note that for databound grids it typically makes sense to set multiple rather than setting the property directly on the ListGridField object.

setName

public void setName(java.lang.String name)

Name of this field. Must be unique within this ListGrid as well as a valid JavaScript identifier, as specified by ECMA-262 Section 7.6 (the StringUtil.isValidID() function can be used to test whether a name is a valid JavaScript identifier).

The name of field is also the property in each record which holds the value for that field.

If a dataSource is specified and the DataSource has a field with the same name, the ListGridField and DataSourceField are merged so that properties on the ListGridField

Parameters:

name - Default value is null

getName

public java.lang.String getName()

Name of this field. Must be unique within this ListGrid as well as a valid JavaScript identifier, as specified by ECMA-262 Section 7.6 (the StringUtil.isValidID() function can be used to test whether a name is a valid JavaScript identifier).

The name of field is also the property in each record which holds the value for that field.

If a dataSource is specified and the DataSource has a field with the same name, the ListGridField and DataSourceField are merged so that properties on the ListGridField

Returns:

String

setOptionCriteria

If optionDataSource is set for this ListGridField, criteria specified in this attribute will be passed to the dataSource when performing the fetch operation to determine data-value to display-value mappings

Parameters:

optionCriteria - Default value is null

getOptionCriteria

If optionDataSource is set for this ListGridField, criteria specified in this attribute will be passed to the dataSource when performing the fetch operation to determine data-value to display-value mappings

Returns:

Criteria

setOptionOperationId

public void setOptionOperationId(java.lang.String optionOperationId)

If this field has an optionDataSource specified and autoFetchDisplayMap is set, this attribute provides a way to customize the operationId passed to dataSource.fetchData() when retrieving the display map from the option dataSource.

Parameters:

optionOperationId - Default value is null

getOptionOperationId

public java.lang.String getOptionOperationId()

If this field has an optionDataSource specified and autoFetchDisplayMap is set, this attribute provides a way to customize the operationId passed to dataSource.fetchData() when retrieving the display map from the option dataSource.

Returns:

String

setOptionTextMatchStyle

For fields with an optionDataSource, where autoFetchDisplayMap is true, this property will govern the textMatchStyle attribute of the DSRequest parameter passed to DataSource.fetchData() when retrieving the remote data set to be used as a basis for this field's valueMap.

Parameters:

optionTextMatchStyle - Default value is null

getOptionTextMatchStyle

For fields with an optionDataSource, where autoFetchDisplayMap is true, this property will govern the textMatchStyle attribute of the DSRequest parameter passed to DataSource.fetchData() when retrieving the remote data set to be used as a basis for this field's valueMap.

Returns:

TextMatchStyle

setPartialSummary

public void setPartialSummary(java.lang.Boolean partialSummary)

Only applies to fields of type "summary". This attribute is set on a summary field, when calculating the summary value from some record, the summary function will only be passed the fields before this summary field. This may be useful for displaying running totals across a record.

getPartialSummary

public java.lang.Boolean getPartialSummary()

Only applies to fields of type "summary". This attribute is set on a summary field, when calculating the summary value from some record, the summary function will only be passed the fields before this summary field. This may be useful for displaying running totals across a record.

getPrompt

setRequired

public void setRequired(java.lang.Boolean required)

When the user edits cells in this field, is this value required to be non-empty in order for validation to pass. Note: for databound listGrids, this property may be specified on the DataSourceField, enabling both client and server side validation.

getRequired

public java.lang.Boolean getRequired()

When the user edits cells in this field, is this value required to be non-empty in order for validation to pass. Note: for databound listGrids, this property may be specified on the DataSourceField, enabling both client and server side validation.

setShowGridSummary

public void setShowGridSummary(java.lang.Boolean showGridSummary)

If showGridSummary is true, should this field show a summary value. If unset, this field will show a summary value in the summary row if an explicit summaryFunction is specified or if a default summary function is defined for the specified field type.

Parameters:

showGridSummary - Default value is null

getShowGridSummary

public java.lang.Boolean getShowGridSummary()

If showGridSummary is true, should this field show a summary value. If unset, this field will show a summary value in the summary row if an explicit summaryFunction is specified or if a default summary function is defined for the specified field type.

Returns:

Boolean

setShowGroupSummary

public void setShowGroupSummary(java.lang.Boolean showGroupSummary)

If showGroupSummary is true, should this field show a summary value in a summary row when the grid is grouped? If unset, this field will show a summary value in the summary row if an explicit summaryFunction is specified or if a default summary function is defined for the specified field type.

Parameters:

showGroupSummary - Default value is null

getShowGroupSummary

public java.lang.Boolean getShowGroupSummary()

If showGroupSummary is true, should this field show a summary value in a summary row when the grid is grouped? If unset, this field will show a summary value in the summary row if an explicit summaryFunction is specified or if a default summary function is defined for the specified field type.

setSortByDisplayField

For a field with displayField configured, should client-side sorting be performed on the display field value? Unless explicitly set to false the display field value is used.

Parameters:

sortByDisplayField - Default value is null

getSortByDisplayField

public java.lang.Boolean getSortByDisplayField()

For a field with displayField configured, should client-side sorting be performed on the display field value? Unless explicitly set to false the display field value is used.

Returns:

Boolean

setSortByMappedValue

public void setSortByMappedValue(java.lang.Boolean sortByMappedValue)

If valueMap is set, and the grid is sorted by this field, should the data be sorted by the underlying data value or the mapped display value. If unset, will sort by display value. Set to false to sort by underlying data value. Note that this has no effect if a ListGridField.sortNormalizer() has been specified.

Parameters:

sortByMappedValue - Default value is null

getSortByMappedValue

public java.lang.Boolean getSortByMappedValue()

If valueMap is set, and the grid is sorted by this field, should the data be sorted by the underlying data value or the mapped display value. If unset, will sort by display value. Set to false to sort by underlying data value. Note that this has no effect if a ListGridField.sortNormalizer() has been specified.

Returns:

Boolean

setSortDirection

Specifies the default sorting direction for this column. If specified on the default sort field for the listGrid, sorting occurs automatically, otherwise this will be the default direction when the user clicks the field header, or calls ListGrid.sort() without specifying an explicit sort direction.

getSortDirection

Specifies the default sorting direction for this column. If specified on the default sort field for the listGrid, sorting occurs automatically, otherwise this will be the default direction when the user clicks the field header, or calls ListGrid.sort() without specifying an explicit sort direction.

setSummaryTitle

Deprecated.Rather than customizing the summaryTitle developers should typically use the headerTitle attribute to show a different title in the column header button than the title used elsewhere.

Optional long summary title for this field, provided in addition to title. This gives the developer an option to use a very short, or empty title for the ListGrid column (where space may be a factor), but have a longer value available to be used elsewhere.

By default this value will be used for the title of the context-menu item for showing/hiding the listGrid field when the user right-clicks on the ListGrid header.

getSummaryTitle

Deprecated.Rather than customizing the summaryTitle developers should typically use the headerTitle attribute to show a different title in the column header button than the title used elsewhere.

Optional long summary title for this field, provided in addition to title. This gives the developer an option to use a very short, or empty title for the ListGrid column (where space may be a factor), but have a longer value available to be used elsewhere.

By default this value will be used for the title of the context-menu item for showing/hiding the listGrid field when the user right-clicks on the ListGrid header.

Returns:

Optional string method to return a long summary title for this field, if a dynamic summary title is required for this field.

setSummaryValue

public void setSummaryValue(java.lang.String summaryValue)

The value to display for a ListGridField when it appears in the summaryRow. The default for normal fields is null and for special fields, like the checkboxField, the default is to show a blank value (a non-breaking space).

getSummaryValue

public java.lang.String getSummaryValue()

The value to display for a ListGridField when it appears in the summaryRow. The default for normal fields is null and for special fields, like the checkboxField, the default is to show a blank value (a non-breaking space).

setSummaryValueTitle

public void setSummaryValueTitle(java.lang.String summaryValueTitle)

If showGridSummary or showGroupSummary is true and the summaryFunction is set to "title", this attribute may be set to a string to display in the group and/or grid summary. If unspecified the title will show up in the summary.

Parameters:

summaryValueTitle - Default value is null

getSummaryValueTitle

public java.lang.String getSummaryValueTitle()

If showGridSummary or showGroupSummary is true and the summaryFunction is set to "title", this attribute may be set to a string to display in the group and/or grid summary. If unspecified the title will show up in the summary.

Returns:

String

setSuppressValueIcon

public void setSuppressValueIcon(java.lang.Boolean suppressValueIcon)

If this field has a valueIcons property specified, setting this property to true will prevent the valueIcon being written out into this field's cells.

setTarget

public void setTarget(java.lang.String target)

By default, clicking a link rendered by this item opens it in a new browser window. You can alter this behavior by setting this property. The value of this property will be passed as the value to the target attribute of the anchor tag used to render the link.

If you set listGridField.target to "javascript", the default behavior is to catch and consume mouse-clicks that would result in the link being followed. Instead, the ListGrid.cellClick() event is fired for the containing cell.

Parameters:

target - Default value is "_blank"

getTarget

public java.lang.String getTarget()

By default, clicking a link rendered by this item opens it in a new browser window. You can alter this behavior by setting this property. The value of this property will be passed as the value to the target attribute of the anchor tag used to render the link.

If you set listGridField.target to "javascript", the default behavior is to catch and consume mouse-clicks that would result in the link being followed. Instead, the ListGrid.cellClick() event is fired for the containing cell.

Returns:

String

setTimeFormatter

Time-format to apply to date type values within this field. If specified, any dates displayed in this field will be formatted as times using the appropriate format. This is most commonly only applied to fields specified as type "time" though if no explicit dateFormatter is specified it will be respected for other fields as well.

If unspecified, a timeFormatter may be defined at the component level and will be respected by fields of type "time".

If this field is editable, the timeFormatter will also be passed to the editor created to edit this field as timeFormatter.

getTimeFormatter

Time-format to apply to date type values within this field. If specified, any dates displayed in this field will be formatted as times using the appropriate format. This is most commonly only applied to fields specified as type "time" though if no explicit dateFormatter is specified it will be respected for other fields as well.

If unspecified, a timeFormatter may be defined at the component level and will be respected by fields of type "time".

If this field is editable, the timeFormatter will also be passed to the editor created to edit this field as timeFormatter.

setTitle

Note: if you want to use HTML tags to affect the display of the header, you should do so via headerTitle instead so that other places where the title appears in the UI are not affected. For example, you might set headerTitle to an empty string to suppress the header title on a narrow column, but you would retain the normal title in the title property to avoid a blank menu item in the field picker menu, hilite editor and other contexts.

getTitle

Note: if you want to use HTML tags to affect the display of the header, you should do so via headerTitle instead so that other places where the title appears in the UI are not affected. For example, you might set headerTitle to an empty string to suppress the header title on a narrow column, but you would retain the normal title in the title property to avoid a blank menu item in the field picker menu, hilite editor and other contexts.

setUserFormula

Advanced applications that wish to save formulas separately from a grid's viewState can provide a UserFormula as part of the field definition, and may subsequently access the formula is updated via the ListGrid.formulaUpdated() notification.

Parameters:

userFormula - Default value is null

getUserFormula

Advanced applications that wish to save formulas separately from a grid's viewState can provide a UserFormula as part of the field definition, and may subsequently access the formula is updated via the ListGrid.formulaUpdated() notification.

Returns:

UserFormula

setUserSummary

Advanced applications that wish to save summaries separately from a grid's viewState can provide a UserSummary as part of the field definition, and may subsequently access the summary is updated via the ListGrid.summaryUpdated() notification.

Parameters:

userSummary - Default value is null

getUserSummary

Advanced applications that wish to save summaries separately from a grid's viewState can provide a UserSummary as part of the field definition, and may subsequently access the summary is updated via the ListGrid.summaryUpdated() notification.

Returns:

UserSummary

setValidateOnChange

public void setValidateOnChange(java.lang.Boolean validateOnChange)

If set to true, any validators for this field will be run whenever the value of the field is changed.

setValidators

Array of Validator objects for this field. When the user edits cells in this field, these validators will be applied to the edited value. Note: for databound listGrids, this property may be specified on the DataSourceField, enabling both client and server side validation.

setValueField

public void setValueField(java.lang.String valueField)

Specifies the optionDataSource field used to retrieve the stored values that are to be mapped to the display values (specified by displayField). Note that if this field is editable this will also be applied to this field's editors.

Parameters:

valueField - Default value is null

getValueField

public java.lang.String getValueField()

Specifies the optionDataSource field used to retrieve the stored values that are to be mapped to the display values (specified by displayField). Note that if this field is editable this will also be applied to this field's editors.

setValueIconOrientation

If we're showing a valueIcon for this field should it appear to the left or the right of the text? By default the icon will appear to the left of the textual value - set this to "right" to show the icon on the right of the text. Has no effect if showValueIconOnly is true

getValueIconOrientation

public java.lang.String getValueIconOrientation()

If we're showing a valueIcon for this field should it appear to the left or the right of the text? By default the icon will appear to the left of the textual value - set this to "right" to show the icon on the right of the text. Has no effect if showValueIconOnly is true

If a simple value-to-URL mapping is not enough, you can override ListGrid.getValueIcon() to customize the behavior. You can even specify an empty valueIcons map and use ListGrid.getValueIcon() to return arbitrary icons with no fixed mapping.

valueIcons can either be displayed alongside the normal value or can replace the normal field value so that only the icon is shown. See showValueIconOnly. When placed alongside the value, use valueIconOrientation to control left- vs right-side placement.

If inline editing is enabled for this field, editors displayed for this field will also show valueIcons. This may be overridden by explicitly setting editorValueIcons.

If ListGridField.valueIconClick() is defined for the field, a pointer cursor will be shown when the user rolls over the valueIcon, and the valueIconClick method will execute when the user clicks the icon.

setValueIconSize

public void setValueIconSize(java.lang.Integer valueIconSize)

Default width and height of value icons in this field. Takes precedence over valueIconWidth, valueIconHeight and valueIconSize specified at the ListGrid level. Can be overridden via valueIconWidth and {ListGridField.valueIconHeight}

getValueIconSize

public java.lang.Integer getValueIconSize()

Default width and height of value icons in this field. Takes precedence over valueIconWidth, valueIconHeight and valueIconSize specified at the ListGrid level. Can be overridden via valueIconWidth and {ListGridField.valueIconHeight}

setValueMap

public void setValueMap(java.util.Map valueMap)

Array of legal values for this field, or an Object where each property maps a stored value to a user-displayable value. Note that if this field is editable (see canEdit, canEdit), editors displayed for this field will pick up their valueMap either from this value or from editorValueMap.

setValueMap

public void setValueMap(java.lang.String... valueMap)

Array of legal values for this field, or an Object where each property maps a stored value to a user-displayable value. Note that if this field is editable (see canEdit, canEdit), editors displayed for this field will pick up their valueMap either from this value or from editorValueMap.

Given the raw value for this field as taken from the record Formatter to apply to the static values displayed in cells for this field.

Example usage: formatting a currency value stored in cents (so "100" to "$1.00") The value passed to this method is the raw value for the cell. Takes precedence over formatCellValue defined at the grid level for cells in this field.

Note: this formatter will not be applied to the values displayed in cells being edited. The formatEditorValue() is provided for that purpose.

Parameters:

value - raw value for the cell, from the record for the row

record - Record object for the cell. Note: If this is a new row that has not been saved, in an editable grid, it has no associated record object. In this case the edit values will be passed in as this parameter (see ListGrid.getEditValues())

getFieldTitle

If your derivation of the field title is more complex than specifying a static string, you can specify a getFieldTitle() method on your field to return the title string. Otherwise you can use the title attribute on the field to specify the title.

setGridSummaryCustomizer

setAlign

Horizontal alignment for field's column header: "left", "right" or "center". Applied to the column header title and cells by default. A separate alignment for cells can be specified via cellAlign. If null, values are left-aligned. If this field is editable, the alignment of cells in the body will also be reflected in any editors for the field.

Parameters:

align - align Default value is null

getAlign

Horizontal alignment for field's column header: "left", "right" or "center". Applied to the column header title and cells by default. A separate alignment for cells can be specified via cellAlign. If null, values are left-aligned. If this field is editable, the alignment of cells in the body will also be reflected in any editors for the field.

Returns:

String

setWidth

public void setWidth(int width)

The width of this field, specified as either an absolute number of pixels, a percentage of the remaining space, or "*" to allocate an equal portion of the remaining space. ListGrid field widths may also be set when the fields are instantiated via the listGrid.setFields() method by passing an array of numbers (absolute pixel sizes only) as the second parameter

Parameters:

width - width Default value is "*"

setWidth

public void setWidth(java.lang.String width)

The width of this field, specified as either an absolute number of pixels, a percentage of the remaining space, or "*" to allocate an equal portion of the remaining space. ListGrid field widths may also be set when the fields are instantiated via the listGrid.setFields() method by passing an array of numbers (absolute pixel sizes only) as the second parameter

setDefaultValue

setEditorProperties

FormItem properties to use as a template for the form item created to edit this field. (Only used if this field is editable). Note: If this is not specified, the edit-form item type be the appropriate form item for the data-type of the field.

filterEditorType - FormItem with default properties to be applied when editing in the filter row

setFilterEditorType

public void setFilterEditorType(java.lang.String editorType)

If this ListGrid is showing a filter row, this property can be used to specify the FormItem class to use for the filter form item associated with this field. (Only used if this field is not canFilter:false).

Note: If this is not specified, the edit-form item type may be derived from the 'editorType' property, typically inherited from datasource fields, or from the 'type' of the field (showing the appropriate form item for the data-type).

setFilterEditorType

If this ListGrid is showing a filter row, this property can be used to specify the FormItem class to use for the filter form item associated with this field. (Only used if this field is not canFilter:false).

Note: If this is not specified, the edit-form item type may be derived from the 'editorType' property, typically inherited from datasource fields, or from the 'type' of the field (showing the appropriate form item for the data-type).

setFilterEditorProperties

If this ListGrid is showing a filter row (showFilterEditor : true), this property can be used to specify properties for the appropriate filter form item. If this is not specified, the edit-form item type may be derived from the 'editorType' property, typically inherited from datasource fields, or from the 'type' of the field (showing the appropriate form item for the data-type).

setOptionDataSource

Derive a ValueMap by fetching records from another DataSource and extracting the valueField and displayField in the loaded records, to derive one valueMap entry per record loaded from the optionDataSource.

Unlike the similar use of optionDataSource for pickLists used during editing or filtering, listGridField.optionDataSource causes the entire set of records from the optionDataSource to be fetched, without paging. Hence listGridField.optionDataSource is appropriate only for smaller valueMaps. For very large valueMap situations, such as an accountId field that should be displayed as an accountName where there are thousands of accounts, the recommended approach is:

do not set listGridField.optionDataSource

declare two fields in the DataSource, eg "accountId" and "accountName".

Set the displayField attribute on the data field to the name of the display field.

When fetching records for display in a grid, have your server send back values for both fields, but show only the data field ("accountId") in the grid.

In this case the cells in the accountId field will show the record value from the accountName field. This approach means the valueMap will never be loaded in its entirety, instead, each loaded record contains the valueMapping for that one record, as a pair of fields within the record.

Note that it is key that the server return both the underlying stored value and the display value, as suggested above, because this approach allows the optionDataSource property to be used to provide paged valueMaps during inline editing and showFilterEditor. Note that pickList.optionDataSource is a distinct setting from listGridField.optionDataSource, settable via editorProperties (for editing) and filterEditorProperties (for filtering).

Parameters:

optionDataSource - optionDataSource Default value is null

setShowIfCondition

A function, if provided, is evaluated to conditionally determine whether this field should be displayed. Evaluated on initial draw, then reevaluated on explicit calls to listGrid.refreshFields() or listGrid.setFields().

Use 'showIf:"false"' to set a ListGrid field to initially hidden.

Note that explicit calls to grid.showField() or hideField() will wipe out the showIf expression, as will the end user showing and hiding columns via the header contextMenu.

Also note that fields marked as detail:true will be hidden by default even if ListGrid.showDetailFields is true. To show detail fields inherited from a DataSource, include an explicit field definition for the field and set this property to return true.

Parameters:

showIf - showIf criteria

setOptionFilterContext

If this field has an optionDataSource specified and
autoFetchDisplayMap is set, this attribute
provides a way to customize the dataSource request issued to fetch the display map from
the option dataSource.

Parameters:

optionFilterContext - optionFilterContext Default value is null

getOptionFilterContext

If this field has an optionDataSource specified and
autoFetchDisplayMap is set, this attribute
provides a way to customize the dataSource request issued to fetch the display map from
the option dataSource.

addChangeHandler

If this field is editable, any change handler specified on the ListGridField will be passed onto the editors for this field.

Note that if canToggle is true, the user may change the value of a boolean field without going into edit mode by single clicking on the field. In this case the ListGridField.change and ListGridField.changed handlers will fire but the form and item parameters will be null.

addChangedHandler

If this field is editable, any changed handler specified on the ListGridField will be passed onto the editors for this field. Note that if canToggle is true, the user may change the value of a boolean field without going into edit mode by single clicking on the field. In this case the ListGridField.change and ListGridField.changed handlers will fire but the form and item parameters will be null.

setHeaderButtonProperties

Set the properties of the header button used for this field. The buttonProperties parameter should be the same class as the headerButtonConstructor for the ListGrid (most commonly Button, ImgButton or StretchImgButton, and typically set up in the load_skin.js file for the loaded theme).

addSummaryFunction

If showGridSummary or showGroupSummary is true, this method can be used to specify a SummaryFunction for calculating the summary value to display. Note that by calling this method repeatedly, you can apply more than one summary function to a field. This allows the developer to set up multi-line summaries - each specified summary function result will show up in a separate summary row (either at the bottom of the grid or at the end of each group).

addSummaryFunction

If showGridSummary or showGroupSummary is true, this method can be used to specify a SummaryFunctionType for calculating the summary value to display. Note that by calling this method repeatedly, you can apply more than one summary function to a field. This allows the developer to set up multi-line summaries - each specified summary function result will show up in a separate summary row (either at the bottom of the grid or at the end of each group).

A subset of the ListGrid's fields will be passed to the RecordSummaryFunction. Which fields to include is determined based on includeInRecordSummary

If showGridSummary or showGroupSummary is true, this field's value in the summary row[s] will still be calculated by calling this method. In this case, the record object passed in will contain summary values for each field. If custom handling is required for this case, it may be detected by checking the record object's isGroupSummary and isGridSummary attributes.

A subset of the ListGrid's fields will be passed to the RecordSummaryFunction. Which fields to include is determined based on includeInRecordSummary

If showGridSummary or showGroupSummary is true, this field's value in the summary row[s] will still be calculated by calling this method. In this case, the record object passed in will contain summary values for each field. If custom handling is required for this case, it may be detected by checking the record object's isGroupSummary and isGridSummary attributes.

A subset of the ListGrid's fields will be passed to the RecordSummaryFunction. Which fields to include is determined based on includeInRecordSummary

If showGridSummary or showGroupSummary is true, this field's value in the summary row[s] will still be calculated by calling this method. In this case, the record object passed in will contain summary values for each field. If custom handling is required for this case, it may be detected by checking the record object's isGroupSummary and isGridSummary attributes.