Class idx.grid.PropertyFormatter

Extends dijit._Container, dijit._TemplatedMixin, dijit._Widget.
Property formatter widget. Provides a widgt that formats an object as text. This widget can use standard formatting mechanisms for messages, numbers, and dates, but can also use a specified function for custom formatting. Typically, each object property is individually automatically formatted based off type and the developer need only provide a message template for combining the properties. This is especially useful within the idx.grid.PropertyGrid widget.
Defined in: <idx\grid\PropertyFormatter.js>.

Constructor Summary

Constructor Attributes	Constructor Name and Description
	idx.grid.PropertyFormatter()

Field Summary

Field Attributes	Field Name and Description
	altSyntax Set this to true to leveage the "$[.
	autoDestroyWidgetFormats Set this to true if you are providing widgets as the format via the custom format function and you want the old widgets to be automatically destroyed when a different widget is provided on reformatting.
	currencyFormatOptions The currency formatting options to use with dojo.number.format().
	data The data object for this instance.
	dateFormatOptions The date formatting options to use with dojo.date.locale.format().
	dateTimeFormatOptions The date-time formatting options to use with dojo.date.locale.format() If this is not provided, then it uses a default value.
	decimalFormatOptions The decimal formatting options to use with dojo.number.format().
	disabled Set this to completely disable the contained EditController (if any).
	editController A reference to the idx.widget.EditController to be used for this instance.
	emptyFormat The text to use to format any part of the result that is null.
	format The format string for combining the properties into text.
	formatFunc Overrides the "format" attribute by providing a function to call to format the data object directly.
	fromEditFunc The function called when populating the value of the form widget(s) when inline editing.
	integerFormatOptions The integer formatting options to use with dojo.number.format().
	percentFormatOptions The percent formatting options to use with dojo.number.format().
	properties A comma separated list of property names from the data object to be formatted by this instance.
	propertyContainer The object (usually parent object) to use as a fall-back for getting formatting options when none are specified for this instance.
	propertyName The property name assigned to this instance so a container can use this instance to format one of its properties.
	readOnly Set this to make the property formatter read only.
	timeFormatOptions The time formatting options to use with dojo.date.locale.format() If this is not provided, then it uses a default value.
	toEditFunc The function called when populating the value of the form widget(s) when inline editing.

Method Summary

Method Attributes	Method Name and Description
	addChild(widget, indexIndex) Extends parent method by calling a method to set up the map editors.
	buildRendering()
	constructor(args, node) Constructor Handles the reading any attributes passed via markup.
	destroy() Ensure the handles are removed
	focus() Method providing for focusing this widget.
	isEditorValid() Function to check if all editors mapped to properties that are contained within have valid values.
	onChange(data, formatter) Called whenever the value value changes with the new data value that was assigned through editing.
	onEditBegin() Called to signal the edit controller has transitioned to edit mode.
	onEditCancel() Called to signal the property formatter has cancelled editing.
	onEditorChange(property, value, formatter) Called when the PropertyFormatter is in edit mode and one of the editors have been modified but the "save" action has not neccessarily been taken yet.
	onRefresh(data, formatter, grid) Called after the PropertyFormatter is reformatted (typically with a new value).
	postCreate()
	postMixInProperties() Overrides dijit._Widget.postMixInProperties()
	prepareEditorValue(propName) Called to prepare a valud for editing
	refresh() Public method for refreshing the formatted value.
	removeChild(widget, indexIndex) Extends parent method by calling a method to set up the map editors.
	saveEditorValue(propName, value) Called to save a value to data
	startup() Called at startup to set state,format and update contained editors.

Constructor Detail

idx.grid.PropertyFormatter()

Field Detail

{Boolean} altSyntax

Set this to true to leveage the "$[...]" syntax in your format string instead of the "${...}" syntax. This should be set to true whenever declarative markup is used within a dijit._TemplatedMixin widget template in order to avoid problems with dijit._TemplatedMixin attempting to perform the replacement for you.

Default Value:: false

{Boolean} autoDestroyWidgetFormats

Set this to true if you are providing widgets as the format via the custom format function and you want the old widgets to be automatically destroyed when a different widget is provided on reformatting. Set this to false if you are manually handling the destruction of the formatter widgets you create via the formatFunc function. This will also control whether or not the created formatter widgets are automatically destroyed when the PropertyFormatter is destroyed. If you are not using custom formatter widgets via the formatFunc attribute, then this setting is not relevant.

Default Value:: true

{Object} currencyFormatOptions

The currency formatting options to use with dojo.number.format().

Default Value:: null

{Object} data

The data object for this instance.

Default Value:: null

{Object} dateFormatOptions

The date formatting options to use with dojo.date.locale.format(). If this is not provided, then it uses a default value.

Default Value:: null

{Object} dateTimeFormatOptions

The date-time formatting options to use with dojo.date.locale.format() If this is not provided, then it uses a default value.

Default Value:: null

{Object} decimalFormatOptions

The decimal formatting options to use with dojo.number.format(). If this is not provided, then it uses a default value.

Default Value:: null

disabled

Set this to completely disable the contained EditController (if any).

{Object} editController

A reference to the idx.widget.EditController to be used for this instance. If none is specified, but editors exist, then an internal one will be automatically created and displayed inline. See idx.widget.EditController.

Default Value:: null

{String} emptyFormat

The text to use to format any part of the result that is null. By default, null values are left as empty-string.

Default Value:: ""

{String} format

The format string for combining the properties into text. After the individual properties are formatted according to their type, they are substituted into this string using processing similar to the dojo.string.substitute() method to replace the tokens for their respective formatted property values. NOTE: The specified format string can use "${...}" tokens OR may use "$[...]" token if the "altSyntax" attribute is set to true. The alternate syntax is useful if the PropertyGrid or formatter is being used inside of a dijit._TemplatedMixin widget where "${...}" is already used to replace templated items with widget properties.

Default Value:: ""

{Object} formatFunc

Overrides the "format" attribute by providing a function to call to format the data object directly. The data object itself is passed to this function and it is expected to return a string.

Default Value:: null

{Function} fromEditFunc

The function called when populating the value of the form widget(s) when inline editing. This allows for the value to be interpretted before populating the form widget. The function is passed three parameters. The first parameter is the name of the property (useful if multiple properties are being edited) and the second value is the actual data value obtained from the form widget and the third is the current data object (which should not be modified but is available for reading). The return value is an object whose fields are used to set the fields of the data referenced by the property formatter.

Default Value:: null

{Object} integerFormatOptions

The integer formatting options to use with dojo.number.format(). If this is not provided, then it uses a default value.

Default Value:: null

{Object} percentFormatOptions

The percent formatting options to use with dojo.number.format().

Default Value:: null

{String} properties

A comma separated list of property names from the data object to be formatted by this instance. This can be a single property name, a simple list of property names, or a property name with type name in parentheses following it.

     For example:
       EXAMPLE 1 (single property name): "givenName"
       EXAMPLE 2 (list of property names):  "givenName,surname,age,birthDate"
       EXAMPLE 3 (property with type): "startTime(tim)"
       EXAMPLE 4 (assorted list):  "givenName,surname,age(int),birthDate(dat)"

       The legal format types are:
          - txt:      assumes literal text (default for string properties)   
          - dat:      uses date formatting (default for date properties)
          - tim:      uses time formatting
          - dtm:      uses date-time formatting
          - dec:      uses decimal formatting (default for numbers w fractional)
          - int:      uses integer formatting (defualt for numbers w/o fractional)
          - pct:      uses percentage formatting
          - cur:      uses currency formatting 
          - obj: 	  used for composite objects (formats as json)

Default Value:: ""

{Object} propertyContainer

The object (usually parent object) to use as a fall-back for getting formatting options when none are specified for this instance. If the fallback does not provide what we need, then we may fall back to idx.resources or use a default value.

Default Value:: null

{String} propertyName

The property name assigned to this instance so a container can use this instance to format one of its properties.

Default Value:: ""

readOnly

Set this to make the property formatter read only. If not in edit mode then the "Edit" link will be hidden. If in edit mode then the Edit Controller will be disable its "Save" button and only enable its "Cancel" button.

{Object} timeFormatOptions

The time formatting options to use with dojo.date.locale.format() If this is not provided, then it uses a default value.

Default Value:: null

{Function} toEditFunc

Default Value:: null

Method Detail

addChild(widget, indexIndex)

Extends parent method by calling a method to set up the map editors.

Parameters:
{dijit._Widget} widget
{int} indexIndex

See:: dijit._Widget.addChild

buildRendering()

See:: dijit._Widget.buildRendering

constructor(args, node)

Constructor Handles the reading any attributes passed via markup.

Parameters:
{Object} args
{Object} node

destroy()

Ensure the handles are removed

focus()

Method providing for focusing this widget. This method ensures the proper child element obtains focus. This is especially important when used with an EditController to ensure a sensible field is focused for edit.

isEditorValid()

Function to check if all editors mapped to properties that are contained within have valid values.

onChange(data, formatter)

Called whenever the value value changes with the new data value that was assigned through editing. This exists so others can connect to this method.

Parameters:
{Object} data
{PropertyFormatter} formatter

onEditBegin()

Called to signal the edit controller has transitioned to edit mode.

onEditCancel()

Called to signal the property formatter has cancelled editing.

onEditorChange(property, value, formatter)

Called when the PropertyFormatter is in edit mode and one of the editors have been modified but the "save" action has not neccessarily been taken yet. This may be used to trigger a call to "isValid()" to check if the current value contained is in fact a valid value.

Parameters:
property: The property name that the editor is bound to.
value: The new value assigned to the property.
formatter: The PropertyFormatter that triggered the event.

onRefresh(data, formatter, grid)

Called after the PropertyFormatter is reformatted (typically with a new value).

Parameters:
data
formatter
grid

postCreate()

See:: dijit._Widget.postCreate

postMixInProperties()

Overrides dijit._Widget.postMixInProperties()

See:: dijit._Widget.postMixInProperties

{Object} prepareEditorValue(propName)

Called to prepare a valud for editing

Parameters:
{String} propName

Returns:: {Object} data

refresh()

Public method for refreshing the formatted value. This triggers a call to "onRefresh"

removeChild(widget, indexIndex)

Extends parent method by calling a method to set up the map editors.

Parameters:
{dijit._Widget} widget
{int} indexIndex

See:: dijit._Widget.removeChildd

saveEditorValue(propName, value)

Called to save a value to data

Parameters:
{String} propName
{Object} value

startup()

Called at startup to set state,format and update contained editors.

See:: dijit._Widget.startup