tutorials

We saw in the earlier article about using itemEditors in a flex datagrid. Now, Lets dive a little deeper into doing some more complex things with itemEditors in a flex datagrid. Before we get started, let us get introduced to the events that are most critical when we are performing an edit operation in a flex datagrid.

(Description of each of these events are available in the livedocs, readers are requested to check up)

itemEditBegin – Fired when you click on an editable cell of the datagrid (also when the editedItemPosition is set on an editable DataGrid)

itemEditBeginning - Fired when the mouse is released

itemEditEnd - Fired when the edit is committed / editor is destroyed there by terminating the edit session.

Now, Lets get back to our scenario. Let us take a simple example – We have a datagrid with a numeric stepper used as an itemEditor similar to the example stated in the part I of this article. Now, let us add an additional functionality of adding a validation to the data that gets entered in the itemEditor. Take a look at the example attached along with this post to see this in action.

Let us dig into the code now:

<mx:DataGrid editable=”true” id=”datagrid” x=”105″ y=”85″ height=”176″ width=”317″ dataProvider=”{arr}” itemEditEnd=”doValidation(event)”>
<mx:columns>
<mx:DataGridColumn headerText=”Data” dataField=”disp” editable=”false”/>
<mx:DataGridColumn headerText=”Available” dataField=”value” editable=”false”/>
<!– itemEditor is set to our class CustomNumericStepper. Always remember to set the editorDataField to the dataField on which the operation is performed–>
<mx:DataGridColumn headerText=”Order Qty” dataField=”order” itemEditor=”CustomNumericStepper” editorDataField=”value”/>

</mx:columns>
</mx:DataGrid>

when the itemEditEnd event of the DataGrid fires, we invoke a method call doValidation() which performs the validation of rhe data entered in the editor. So,whats the logic for validation? We validate if the new value that is getting entered in the column is less than or equal to the value in the available column. on fail, we will throw an alert indicating the error to the user. showError() method is used to achieve this.

//Validate the data entered / stepped in the itemEditor
private function doValidation(event:DataGridEvent):void
{

//Storing the selection made in the itemEditor to a variable
var selectedData:Object = CustomNumericStepper(datagrid.itemEditorInstance).value
//Store the upper bound to compare
var upperBound:Number = event.target.selectedItem.value;
//Compare if the entered value is > upper bound
if(selectedData > upperBound)
{
//Destroy the instance of the itemEditor by calling destroyEditor()
datagrid.destroyItemEditor()
//Call preventDefault() so that the new value is NOT committed
event.preventDefault();
//Invoke a method to display an error message
showError(upperBound);
}
}
//Display the error message
private function showError(value:Number):void
{
//Show the error message in an Alert Box
Alert.show(”Please Enter a value less than “+value)
}

So, whats doValidation() doing?

doValidation() receives the datagrid event as its parameter. The first step is to store the Object corresponding the edited item into a variable – selectedData

Now we find out what is the upper bound to validate against. This is the value in the available column for the current record that we are editing. Now we store that value to another variable – upperBound

Lets check if selectedData > uppedBound. On this condition being satisfied, we do the following steps.

Destroy the editor instance – destroyItemEditor() is called. This is to close the editor
Prevent committing of the data – event.preventDefault() is called. This prevents the default action that a particular event triggers. In this case, the committing of the data is prevented.
Finally, showError() method is called to alert the error message to the user.

There we go! We have a simple working sample of applying a validation to an itemEditor of a flex datagrid up and running.

View Sample | Download Source

Alex has written two wonderful posts in his blog about working with itemRenderers. Along with itemRenderers another extremely useful feature in flex is itemEditors. itemEditors provide a highly efficient and clean way of providing custom editors for editing data in components like List and DataGrid.

Take this example: You have a Datagrid with two columns (Product, Available and Order Qty). Avaliable & Order Qty columns contain numeric data. You want to allow the user to make an order by selecting the Order Qty column by entering a value for the number of pieces he wants to order in the column.

Option 1: You can simply pop the default itemEditor of a Datagrid / List, which is a TextInput where the user can key in the number.
Option 2: You can pop a custom itemEditor.In this case, using a NumericStepper makes a lot of sense because it lets the user increment / decrement a value and also allow him to type in just like in a textinput.

I have used Option 2, to implement the solution.

So, Why itemEditors and not itemRenderers?
You can set a NumericStepper as an itemRenderer and set the rendererIsEditor property to true. But in that case the renderers are pre-created, they are *always* displayed evcen when you are not editing it and lastly, you have to write your own logic to persist the data after editing the cell. (That surely seems like more work than using itemEditors for our current problem.)

Lets Get back to itemEditors - Take a look at the example attached along with this post which uses a NumericStepper as its itemEditor. You can see that the NumericStepper is popped when you click on the cell in the Order Qty column and the editor is destroyed when you click on anywhere else / change the focus. Also note that the value that you entered / stepped is now committed and the DataGrid display is updated.

Lets do a little digging into the code
As you can see, there is *very little* code that is written to implement this solution.

Step 1 – Set up the data: (see inline code comments)

//DataGrid event, fired when the itemEditing is performed
import mx.events.DataGridEvent;
//Used for populating the datagrid
import mx.collections.ArrayCollection;
//Used to display the Alert
import mx.controls.Alert;
//ArrayCollection that will hold the data
[Bindable]private var arr:ArrayCollection
private function populateData():void
{
//Create an array with dummy product names
var prodarray:Array = ['Apple','Orange','Peach','Grapes','Guava','Mango','Raspberry','Strawberry','Watermelon','Passionfruit']
//Create an arraycollection
arr = new ArrayCollection()
//Loop to create 10 records
for(var i:int=0;i<10;i++)
{
//create a random number
var rnd:Number = Math.round(Math.random()*100);
//Create an object to insert into the array collection
var obj:Object = {value:rnd, disp:prodarray[i],order:0}
//Add the object to array collection
arr.addItem(obj)
}

}

Step 2: Create the Datagrid and set up the itemEditor.

The following lines of code create an instance of Datagrid with 3 columns, and we set the itemEditor and editorDataField properties to the third column. (See inline comments)

One important point to be remembered here. The DataGrid or List always looks for the default property text on the itemEditors unless you specify the editorDataField property to the appropriate value. In this case editorDataField will be value since we will be altering the value property when we increment / decrement a NumericStepper. If we were to use a TextArea, the property should be set to text. If you forget to set this property, then prepare yourself for some erratic behavior

<!– DataGrid Instance, dataProvider is bound to ‘arr’- the arraycollection. –>
<mx:DataGrid editable=”true” id=”datagrid” x=”56″ y=”104″ height=”176″ width=”317″ dataProvider=”{arr}”>
<mx:columns>
<mx:DataGridColumn headerText=”Product” dataField=”disp”/>
<mx:DataGridColumn headerText=”Available” dataField=”value”/>
<!– itemEditor is set to our class CustomNumericStepper. Always remember to set the editorDataField to the dataField on which the operation is performed–>
<mx:DataGridColumn headerText=”Order Qty” dataField=”order” itemEditor=”CustomNumericStepper” editorDataField=”value” />
</mx:columns>
</mx:DataGrid>

Step 3: Create the custom itemEditor

I have created a CustomNumericStepper class which extends from NumericStepper. (CustomNumericStepper.as). This class contains just two properties, the maximum and the stepSize. The maximum is set to 150, assuming that we will *not* be stocking more than 150 fruits of each type (well, we will change this assumption soon, accommodating a more realistic calculation, but lets keep it this way for the sake of simplicity )

package
{
import mx.controls.NumericStepper;

public class CustomNumericStepper extends NumericStepper
{
public function CustomNumericStepper():void
{
super();
//Set the properties
stepSize=1;
maximum=150;
}
}
}

Note: I chose to write this as a .as file, you could very well use an MXML component to achieve the same results.

We are all set to go!

View the Sample | Download Source

and right click on the application to view / download the full source.

Coming up next: Doing more with itemEditors – applying formatters & validators to itemEditors