Understanding Flex itemEditors – Part 1: Inline itemEditors

I recently completed a series on itemRenderers ― customizations to list controls that format the display of the list contents. Displaying and rendering content is a very effective UI technique and with Flex you can do nearly anything you can imagine.

This is Part 1 of a new series covering itemEditors, which allow data to be changed directly inside of a list control. This first article covers inline itemEditors, which are very simple, though quite useful, components you write directly inside your MXML files. Later articles in the series will cover more complex editing, validation, events, and using itemRenderers as itemEditors.

The TextInput editor

Editing directly in list controls is convenient. Imagine a DataGrid of warehouse inventory where you can adjust the content right in the grid without needing a special pop-up (see Figure 1). The list controls have a built in editor, a TextInput control, that appears whenever the user clicks in an editable area, either a row (for a List), a branch (for a Tree), or a cell (for a DataGrid). All you need to do is set the list control's editable property to true. For a DataGrid you can exclude a column from being edited by setting the DataGridColumn's editable property to false.

itemEditors differ from itemRenderers in that only one instance of the itemEditor is seen, just on the cell being edited. The itemEditor is not seen until the cell to be edited receives input focus. Then the itemRenderer is hidden and the itemEditor is moved to that position, sized to fit the area, and given the data for the record. When editing is finished (by moving focus to another location), the list control copies the new value from the editor to the dataProvider record.

In the application shown in Figure 1, when the user clicks in a cell of the "Part #" column, the dataProvider[row][dataField] value is given to the text property of the itemEditor (TextInput) control. When editing is finished, the text property value from the itemEditor (TextInput) control is copied to the dataProvider[row][dataField]. The dataProvider, being a collection, dispatches an event in response to the update.

While the default TextInput control makes a fine editor, it really only works for the most simple of cases. It works fine for String values, for example, such as a book title, author name, or product number. If you need more control or want to validate the user's input, then you need to take matters into your own hands.

Flex Controls as itemEditors

Here is how you make an itemEditor which only accepts numeric values:

The restrict and maxChars properties ensure that age values are constrained to three-digit numbers.

The CheckBox is another common control to use for an itemEditor, because it is useful for editing Boolean values. Figure 2 shows an example of using the CheckBox to edit the values for an "In Stock" column of an inventory program.

Here is the code to make it work:

In this example the content of the cells in this column are rendered using a labelFunction (inStockLabeler), which can display descriptive strings such as "Yes", "No", "In Stock", or "Out of Stock". The itemEditor property is set to the mx.controls.CheckBox class. And there is another, equally important, property set on the DataGridColumn: editorDataField. This field indicates the property of the itemEditor class to use to fetch the value when editing is finished. In this case it is the CheckBox's selected property. When editing is finished, the DataGrid will use the CheckBox's selected property to replace the inStock property in the data record.

At this point, you may wonder why the example with the TextInput did not supply the editorDataField property. That is because the default value for editorDataField is "text" which just happens to be the name of the property on the TextInput control holding the value.

You can use this same technique with a number of Flex controls. Here is one for an order quantity column using NumericStepper, as shown in Figure 3:

Notice the editorDataField is "value" - the property of the NumericStepper that holds the current value of the control. Make sure you use the fully-qualified class name for the itemEditor property or else the compiler will not be able to find the class and flag the line with an error.

A more complex editor

Now suppose you want to do something a little more complex that doesn't have a ready-made Flex control available. Here is one which allows the user to enter a credit card number using four separate four-digit fields (see Figure 4):

Here is the code to make it work:

This inline itemEditor follows the same rules as other itemEditors and names the editorDataField as "value". The component chosen for the itemEditor is the HBox, which does not have a "value" property. To make this itemEditor work, a getter function named value is created to return the concatenation of the four input fields. Now when the user is finished editing the cell, the DataGrid can call upon the value property of the itemEditor and it will receive the combined fields.

Note the super.data = value in the data setter function. The data property - really the data getter function - is used extensively behind the scenes in the List controls and elsewhere in the framework (not to mention your own code). If you don't set the internal value of data using super.data, then the data getter function will return a null value and, most likely, cause your application to crash.

You can also see that I have overridden the data setter function. In that function I split up the credit card number among the four TextInput fields. This is the technique used to display the data to be edited. The editorDataField is the property used to retrieve the new value.

Where to go from here

In this article you've seen how to create an inline itemEditor by simply naming a class and by creating a complex class right within the MXML tags. Naming the property of the editor class that contains the final editor value allows the DataGrid to retrieve the value from the editor instance and replace the current value in the data.

Part 2 of this series covers more complex itemEditors and editing events.