Open the starter file authorBookEditor.fla in Flash. Figure 8-1 shows the interface. The application will populate the ComboBox with authors from the loaded XML object. It will show the books for each author in an editable DataGrid below the author name. A TextArea control will show the contents of the XML object.

A user can add details of a new book, modify a row in the DataGrid, or select a row in the DataGrid to delete a book.

Figure 8.1. The application interface

Create a new layer called actions. Open the Actions panel using the F9 shortcut and add the following code to load the external XML document. If you've worked through the previous exercises, there's nothing new in this code, but I'll explain it after the listing.

import fl.data.DataProvider;
var authorsXML:XML;
var authorList:XML;
var booksList:XML;
var request:URLRequest = new URLRequest("authorsAndBooks.xml");
var loader:URLLoader = new URLLoader();
initApp();
stop();

This script block starts by importing the DataProvider class, which the application will use to populate both the ComboBox and DataGrid controls. The code creates three XML objects. The first is authorsXML, which will store the complete XML tree from the loaded content. The second XML object, authorList, will populate the ComboBox. The third XML object, booksList, will store the books for each author and populate the DataGrid.

The code then creates a URLRequest object called request and a URLLoader object called loader. The URLRequest requests the authorsAndBooks.xml file and assumes that the XML document is in the same folder as the Flash application.

The second-to-last line calls a function named initApp() to set up the application. You'll create this function in the next step. The code block finishes with a stop() action.

The initApp() function sets up the application and loads the external XML document. Add the following code at the bottom of the Actions panel. It contains two other functions, which I'll explain after the listing.

function initApp():void {
  loader.addEventListener(Event.COMPLETE, completeHandler);
  authors_cbo.labelFunction = getFullName;
  loader.load(request);
}
function completeHandler(e:Event):void {
  authorsXML = XML(e.target.data);
  authorList = new XML(authorsXML.authors);
  authors_cbo.dataProvider = new DataProvider(authorList);
  tree_txt.text = authorsXML.toXMLString();
}
function getFullName(item:Object):String{
  return item.authorFirstName + " " + item.authorLastName;
}

First, the initApp() function adds an event listener to the loader object. The listener will respond when the loader dispatches the complete event by calling the function completeHandler(). In other words, this handler function will process the loaded content to make it available to the application.

The initApp() function also sets the labelFunction property for the authors_cbo control so that it can display the full name of each author. The function finishes by calling the load() method of the loader object to request the external XML document.

The completeHandler() function receives an Event as an argument and uses the target.data property of this Event object to locate the loaded data. The first line casts this data as an XML object, assigning it to the authorsXML object. You need to do this because the content is loaded as String data.

The function creates an XML object containing the list of authors by targeting the <authors> element in the XML document with the E4X expression authorsXML.authors. The third line of the completeHandler() function sets the dataProvider property for the ComboBox control to this XML object. The labelFunction for the ComboBox will format the appearance of the data in the ComboBox. The final line displays a String representation of the loaded XML content in the TextArea component called tree_txt.

The getFullName() label function should be familiar to you from the earlier examples. It creates the full name by locating the first and last names of the author in the <authorFirstName> and <authorLastName> elements. It joins these elements with a space in between.

At this point, the application has loaded the XML document and populated the ComboBox control. Test the movie and check that the external XML document loads successfully. Figure 8-2 shows how the interface should appear at this point. You should see the TextArea populated with the loaded XML document and the ComboBox displaying the first author name, Alison Ambrose.

Figure 8.2. Testing that the application loads the external XML document

The application now needs to load the books for the author displayed in the ComboBox. When the application first starts, it will display the first author's books in the DataGrid to match the value initially shown in the ComboBox. When the user selects a different author, the books shown will change. To accomplish this, the application needs to detect when the selection in the ComboBox changes, and then locate the <books> element for the selected author.

Add the following line to the initApp() function to detect a change in the ComboBox component:

authors_cbo.addEventListener(Event.CHANGE, changeHandler);

Each change in the selected value in the ComboBox calls the changeHandler() function. Add the following changeHandler() function at the bottom of the Actions panel:

function changeHandler(e:Event):void {
  var authorIndex:int = e.target.selectedIndex;
  loadBooks(authorIndex);
}

The changeHandler() function receives an Event as an argument. You can determine the selectedIndex from the target of this event, which is the ComboBox control.

The function assigns the selectedIndex value of the ComboBox to the authorIndex variable. The number will be the same as the author index from the XML object, as both are zero-sbased.

The function finishes by calling another function, loadBooks(), passing the value of the selectedIndex property. The loadBooks() function will populate the DataGrid component.

Add the loadBooks() function shown here to the actions layer:

function loadBooks(authorIndex:int):void {
  var booksDP:DataProvider;
  booksList = new XML(authorsXML.authors.author[authorIndex].books);
  booksDP = new DataProvider(booksList);
  books_dg.dataProvider = booksDP;
}

Each time the user selects a new author, the loadBooks() function will locate that author's books and use them to populate the DataGrid.

This function starts by declaring a DataProvider object called booksDP, which the application will use to populate the DataGrid. It then locates the <books> element using the E4X expression authorsXML.authors.author[authorIndex].books. Notice that the E4X expression includes the authorIndex passed from the changeHandler() function.

The loadBooks() function sets the returned XMLList as the source for the booksList XML object. It then assigns the booksList object to the DataProvider object. Finally, the bookDP object is assigned as the dataProvider for the DataGrid.

If you tested the application now, you wouldn't see any books populated initially. That's because you need to add another call to the loadBooks() function, which runs when the XML content first loads. This call will allow you to see the first author's books.

Add the line shown in bold to the completeHandler() function:

function completeHandler(e:Event):void {
  authorsXML = XML(e.target.data);
  authorList = new XML(authorsXML.authors);
  authors_cbo.dataProvider = new DataProvider(authorList);
loadBooks(0);
  tree_txt.text = authorsXML.toXMLString();
}

Once the content is loaded, the application will call the loadBooks() function, passing the first author's index of 0 as an argument.

Test the application again and check that the books for the first author appear when the application first loads. You also need to test that you can see other authors' books when you change the selection in the ComboBox.

Figure 8-3 shows the interface when the application first loads.

Figure 8.3. Loading the DataGrid

The DataGrid doesn't look too good. The column headings are the default field names, and the book titles are cut off. You can fix the way it looks by calling another function, setupDataGrid(), which formats the DataGrid's appearance.

Add the following function call to the end of the completeHandler() function. The new line appears in bold.

function completeHandler(e:Event):void {
  authorsXML = XML(e.target.data);
  authorList = new XML(authorsXML.authors);
  authors_cbo.dataProvider = new DataProvider(authorList);
  loadBooks(0);
setupDataGrid();
  tree_txt.text = authorsXML.toXMLString();
}

You also need to add the setupDataGrid() function to your actions layer.

function setupDataGrid():void {
  books_dg.columns = ["ID", "Name", "Publish year", "Cost"];
  books_dg.columns[0].width = 50;
  books_dg.columns[1].width = 200;
  books_dg.columns[2].width = 50;
  books_dg.columns[3].width = 50;
  books_dg.columns[0].dataField = "bookID";
  books_dg.columns[1].dataField = "bookName";
  books_dg.columns[2].dataField = "bookPublishYear";
  books_dg.columns[3].dataField = "bookCost";
  books_dg.columns[0].editable = false;
}

The role of this function is to set column headings, widths, and assign which data field to display. This function starts by declaring the column headings for the DataGrid. It refers to each column using its position in the columns collection.

The function then sets the width and dataField properties for each column. Feel free to modify the width settings to display more or less of each column.

The function finishes by making the first column read-only. The application needs to do this because the users should not be able to change the bookID field. Normally, that field would be the primary key and would be allocated externally.

Test the application again. The DataGrid looks much better, as shown in Figure 8-4.

Figure 8.4. The DataGrid has been formatted.

The application has now set up the interface to display thedata. The next step is to allow the users to modify the books for each author. They will be able to add, edit, and delete book information.

Let's start by providing the functionality to add a new book. You'll need to add a handler function that responds when the user clicks the Add book button.

Add the following line to the initApp() function:

addRow_btn.addEventListener(MouseEvent.CLICK, addClickHandler);

This line adds an event listener that responds when a user clicks the addRow_btn button. You also need to add the addClickHandler() function shown here:

function addClickHandler(e:MouseEvent):void {
  var newBookName:String = name_txt.text;
  var newPublishYear:String = year_txt.text;
  var newBookCost:String = cost_txt.text;
  var newBookXML:XML;
  if(newBookName.length > 0 && newPublishYear.length > 0 &&
    
newBookCost.length > 0) {
    books_dg.addItem({bookName: newBookName,
      
bookPublishYear: newPublishYear, bookCost: newBookCost});
    newBookXML = <book bookID=''></book>;
    newBookXML.bookName = newBookName;
    newBookXML.bookPublishYear = newPublishYear;
    newBookXML.bookCost = newBookCost;
    authorsXML.authors.author[authors_cbo.selectedIndex]
      
.books.appendChild(newBookXML);
    tree_txt.text = authorsXML.toXMLString();
  }
}

This function responds to the click of the Add book button and receives a MouseEvent as an argument. It starts by adding the user entries to three variables: newBookName, newPublishYear, and newBookCost. The function also declares an XML object that will store the new XML content.

The function checks that the user has entered values in each of the Name, Published year, and Cost TextInput controls. If so, it uses the addItem() method of the DataGrid to add the new entry. The code creates an object made up of name/value pairs and passes this object to the addItem() method. Notice that the code uses the field name from the XML object, rather than the column headings, to indicate where you want users to enter each new piece of information.

After adding the new row, the function then creates a <book> element for the newBookXML object. Notice that this element has one attribute that doesn't have a value. Normally, you would get the bookID value from the database.

The function then assigns the bookName, bookPublishYear, and bookCost properties to the newBookXML object. This approach provides a quick way to add the child elements to the <book> element.

The function finishes by using the appendChild() method to add the newBookXML object to the <books> element of the selected author. Notice that you pass the authors_cbo.selectedIndex as the author index. Finally, the function displays the updated XML object in the TextArea control.

Note that I haven't provided any processing in case the user clicks the button without filling in all of the TextInput controls. Feel free to add a text field and display a message to deal with this situation.

Test the application again. You should be able to enter details of a new book and add it to the DataGrid and XML object. Figure 8-5 shows an example of adding a new book to the author Douglas Donaldson. As I mentioned, we didn't create an ID for this book because that would most likely be managed by the database.

Figure 8.5. Adding a new book

You can see that the new book appears at the bottom of the list of books for Douglas Donaldson. It also appears as a new <book> element in his list of all books. Because the code uses the appendChild() method, the book appears as the last child of the <books> element.

Let's see how to delete a book from the DataGrid and the XML object. The user will select a row in the DataGrid and click the Delete selected book button. You'll need to add a listener for the click of this button.

Add the following line to the initApp() function:

delete_btn.addEventListener(MouseEvent.CLICK, deleteClickHandler);

This line adds an event listener that responds when the Delete selected book button is clicked. Add the deleteClickHandler() function now.

function deleteClickHandler(e:MouseEvent):void {
  var bookIndex:int = books_dg.selectedIndex;
  var authorIndex:int = authors_cbo.selectedIndex;
  if (bookIndex != −1) {
    books_dg.removeItemAt(bookIndex);
    delete(authorsXML.authors.author[authorIndex].books.book[bookIndex]);
    tree_txt.text = authorsXML.toXMLString();
  }
}

This function receives a MouseEvent as an argument. It starts by declaring two variables: one for the index of the selected book, called bookIndex, and one for the index of the selected author, called authorIndex. It populates these variables with the selectedIndex properties from each control.

The function checks to make sure that the user has selected a row in the DataGrid. In this case, the selectedIndex property of the DataGrid will have a value other than −1.

If a row is selected, the function finds the selected book and author indices and uses the removeItemAt() method of the DataGrid. It passes the index of the book to delete, which corresponds to the index of the <book> element in the DataProvider.

Finally, the function uses the delete() ActionScript 3.0 operator to remove the <book> element from the authorsXML object. The code locates the relevant book with an E4X expression that targets the relevant author and book indices. The function finishes by displaying a String representation of the XML object in the TextArea.

Test the application. You should be able to select a row in the DataGrid and click the Remove selected row button to remove the row. Check that the book has also been removed from the XML object by looking in the TextArea.

The last task is to allow users to modify the values in a row of the DataGrid. They can modify anything except for the bookID. In this case, the application is going to respond when the editing ends, which can be done with a DataGridEvent. You'll need to start by importing this class with the following statement at the top of the Actions panel:

import fl.events.DataGridEvent;

The application can now use a DataGridEvent in the addEventListener() call. You'll need to add an event listener that responds when the editing of a cell finishes.

Add the next line to the initApp() function:

books_dg.addEventListener(DataGridEvent.ITEM_EDIT_END,
  
itemEditEndHandler);

This line responds to ITEM_EDIT_END, which occurs when the user finishes editing an individual cell. The application will need to check if anything has changed, and if so, process the changes to that value.

Add the handler function itemEditEndHandler() to the actions layer:

function itemEditEndHandler(e:DataGridEvent):void {
  var dg:DataGrid = e.target as DataGrid;
  var field:String = e.dataField;
  var row:Number = Number(e.rowIndex);
  var col:int = e.columnIndex;
  var oldVal:String;
  var newVal:String;
  oldVal = e.itemRenderer.data[field];
  newVal = dg.itemEditorInstance[dg.columns[col].editorDataField];
  if (oldVal != newVal) {
    modifyXMLTree(dg.columns[col].dataField, row, newVal)
  }
}

This function starts by declaring dg as a DataGrid object and assigning the target of the DataGridEvent to this object. The target property refers to the DataGrid, but notice that the code needed to use an as statement to type it correctly.

The function identifies the dataField being changed using the property e.dataField and assigns it to the variable field. This value is a String. The function also locates the row and column of the edit using the rowIndex and columnIndex properties.

The itemEditHandler() declares variables for the old and changed values so the application can compare the two. It will treat them both as String variables, even if they contain numbers. A String data type is suitable, as all values will be treated as a String in the XML object.

The function finds the original value by looking at the itemRenderer property for the DataGridEvent. This property gets the item renderer for the item being displayed in the cell. The itemRenderer makes available a property called data, which the function can use to find the original value of the field. The function uses the expression e.itemRenderer.data[field]. The field variable created earlier determines the field name to use.

The itemEditEndHandler() function finds the changed value by looking at the itemEditorInstance property of the DataGrid. This property returns a reference to the active item editor after the user starts editing a cell. You can use it to locate changed values in edited cells, as you can see in the line that assigns a value to the newVal variable. The function passes the field name to the expression dg.itemEditorInstance[dg.columns[col].editorDataField].

Finally, the function compares the original and changed values, and calls the modifyXMLTree() function if these values are different. The application doesn't need to respond if the values are the same, because that means the user hasn't made a change.

You have yet to create the modifyXMLTree() function, but it will receive the name of the dataField, the row being edited, and the newVal variable.

You can't test this functionality yet because no modifications are processed. Add the following modifyXMLTree() function:

function modifyXMLTree(fieldName:String, elementIndex:int,
  
newVal:String):void{
  var newXMLString:String = "<" + fieldName + ">" + newVal +
    
"</" + fieldName + ">";
  authorsXML.authors.author[authors_cbo.selectedIndex].
    
books.book[elementIndex].replace(fieldName, newXMLString);
  tree_txt.text = authorsXML.toXMLString();
}

This function processes the changes to the cell value in the XML object. It starts by creating a new variable that contains an XML String made up of the field name and the new value. The newXMLString variable will contain something in the form of <fieldName>New value <fieldName>. The field name can be taken from one of the three columns and can have only the values of bookName, bookPublishYear, or bookCost.

The function then locates the relevant book element, finding which author is selected in the ComboBox and using the row number as the <book> element index. It uses the replace() method to replace the entire existing element with the changed element, passing the String value that it created earlier.

This function finishes by displaying a string representation of the updated XML object in the TextArea.

Test the application again. You should be able to change the values in one of the DataGrid cells and see it immediately update in the TextArea. Notice that each time you edit a cell, the updates take place.

Open the starter file AuthorBookEditor.mxml in Flex Builder. You can copy the file and paste it into your existing Flex project. The interface for the application, shown in Design view of Flex Builder, appears in Figure 8-6.

Figure 8.6. The application interface in Design view

As with the Flash version of this example, you'll populate the ComboBox with a list of authors from the external XML document. When an author is selected, the application will show the books for that author in the DataGrid component beneath the author name. It will show a String representation of the XML object in the TextArea at the bottom of the interface. To the right, TextInput controls allow a user to enter new book details.

If you're using a new Flex project, create an assets folder inside the src folder of the project. Copy the authorsAndBooks.xml file to this folder. The file contains the details of the authors and their books.

You'll load the XML document with the MyXMLLoaderHelper class that you created in Chapter 5. The class exists in the xmlUtilities package, so add a folder of that name to your Flex project. Copy the file MyXMLLoaderHelper.as from the chapter resources to the xmlUtilities folder. You can also use the version that you created yourself in Chapter 5.

This class file handles the loading of the external XML file. It also returns a specified child element from the XML object. However, you'll need to modify the class file to add a little more functionality for this example.

Because the XML file that you're loading is complicated, you're going to define the <authors> element from the external file as its own XML object. This approach will allow you to work with just that part of the XML document and make it easier to locate the <books> element for each author.

Add two new private variable declarations with the other declarations:

private var xmlRootString:String;
private var xmlRoot:XML;

The first variable will store the name of the element to use as the new XML object root. In this case, the new XML object xmlRoot will store the <authors> element information with all of its child elements.

The application will pass in an additional parameter to the loadXML() method to specify the child element to use for the new XML object root. Modify the function as shown in bold here. It will assign the new parameter to the xmlRootString variable.

public function loadXML(xmlFile:String, rootElement:String):void {
  xmlRootString = rootElement;
  try {
    xmlLoader.load(new URLRequest(xmlFile));
  }
  catch (e:Error) {
    trace ("Can't load external XML document");
  }
}

You also need to modify the completeHandler() private method as shown in bold:

private function completeHandler(e:Event):void {
  xmlAllContent = XML(e.target.data);
  xmlRoot = XML(xmlAllContent.child(xmlRootString));
  dispatchEvent(new Event(Event.COMPLETE));
}

The new line assigns the XML content from the specified child element to the xmlRoot object. Because the child() method actually returns an XMLList object, the code needs to cast it as an XML object so there isn't a type mismatch.

The class file needs a new public method to return the XML object to the calling application. Add the following getXML() method:

public function getXML():XML {
  return xmlAllContent;
}

The final change to the class file is to modify the getChildElements() public method to find a child of the xmlRoot object instead of the xmlAllContent element. Change the first line as shown here in bold:

childElements = xmlRoot.child(elementName);

The complete class file follows in case you want to check that you've included all of the changes correctly:

package xmlUtilities {
  import flash.net.URLLoader;
  import flash.net.URLRequest;
  import mx.collections.XMLListCollection;
  [Bindable]
  public class MyXMLLoaderHelper {
    private var xmlAllContent:XML;
    private var xmlLoader:URLLoader;
    private var xmlRootString:String;
    private var xmlRoot:XML;
    private var childElements:XMLList;
    private var childElementsCollection: XMLListCollection;
    public function MyXMLLoaderHelper() {
      xmlLoader = new URLLoader();
      xmlLoader.addEventListener(Event.COMPLETE, completeHandler);
    }
    public function loadXML(xmlFile:String,
      
rootElement:String):void {
      xmlRootString = rootElement;
      try {
        xmlLoader.load(new URLRequest(xmlFile));
      }
      catch (e:Error) {
        trace ("Can't load external XML document");
      }
    }
    public function getXML():XML {
      return xmlAllContent;
    }
    public function getChildElements(elementName:String):
      
XMLListCollection {
      childElements = xmlRoot.child(elementName);
      childElementsCollection = new XMLListCollection(childElements);
      return childElementsCollection;
    }

private function completeHandler(e:Event):void {
      xmlAllContent = XML(e.target.data);
      xmlRoot = XML(xmlAllContent.child(xmlRootString));
      dispatchEvent(new Event(Event.COMPLETE));
    }
  }
}

You'll make further changes to this class as part of building this example, so leave the file open in Flex Builder.

You need to initialize the application and call the loadXML() method of our custom class to load the external document into the application. Switch to the AuthorBookEditor.mxml file and add the following code, including the initApp() function, to an <mx:Script> block at the top of the file:

import mx.collections.XMLListCollection;
import xmlUtilities.MyXMLLoaderHelper;
import mx.events.FlexEvent;
private var myXMLLoader:MyXMLLoaderHelper;
private function initApp(e:FlexEvent):void {
  myXMLLoader = new MyXMLLoaderHelper();
  myXMLLoader.addEventListener(Event.COMPLETE, completeHandler);
  myXMLLoader.loadXML("assets/authorsAndBooks.xml", "authors");
}
private function completeHandler(e:Event):void {
}

This code starts by importing the classes that the application needs, including the XMLListCollection, the custom class MyXMLLoaderHelper, and the FlexEvent class. The XMLListCollection wrapper class will work with XMLListCollection objects returned from the custom class. As you saw earlier in the book, this class provides additional functionality to an XMLList object and is suitable as a DataProvider for list-based components.

The code block then declares a private variable, myXMLLoader, which is an instance of the custom class. The code block includes the initApp() function, which creates a new instance of the MyXMLLoaderHelper class and assigns an event listener to respond to the complete event.

The function also calls the loadXML() method of the custom class, passing the external XML document file name and target element name.

I've included the function signature for the completeHandler() function without any code. You'll need to call this function in the creationComplete attribute of the <mx:Application> element as shown in bold in the following code, so make the change in your own file.

<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml"
  layout="absolute" creationComplete="initApp(event)">

You'll modify the completeHandler() function to display the author names in the ComboBox control. The code will call the getChildElements() method of the custom class to return an XMLListCollection containing all of the <author> elements. It will assign this object as the dataProvider property for the ComboBox.

The completeHandler() function will also populate the TextArea with a String representation of the loaded XML object. The application will use this TextArea control to keep track of the current contents of the XML object.

Add the following lines to the completeHandler() function:

authors_cbo.dataProvider = myXMLLoader.getChildElements("author");
tree_txt.text = myXMLLoader.getXML().toXMLString();

The first line sets the dataProvider property of the ComboBox to the XMLListCollection returned by the getChildElements() method of the myXMLLoader class.

As the full name doesn't appear in a single element in the dataProvider, the application will need to use a labelFunction in the ComboBox control to display this value. You've seen this function earlier in the book. Add it to the <mx:Script> block.

private function getFullName(item:Object):String {
  return item.authorFirstName + " " + item.authorLastName;
}

The function joins the author's first and last names with a space in between to create a full name.

You also need to assign the getFullName() function to the ComboBox so it knows how to create the label. Modify the initApp() function as shown here in bold to assign it as the labelFunction property.

private function initApp(e:FlexEvent):void {
  myXMLLoader = new MyXMLLoaderHelper();
  myXMLLoader.addEventListener(Event.COMPLETE, completeHandler);
  authors_cbo.labelFunction = getFullName;
  myXMLLoader.loadXML("assets/authorsAndBooks.xml", "authors");
}

Test the movie and check that the ComboBox populates correctly with the full name of each author. Figure 8-7 shows how the interface should appear if you run the application and view it in a web browser.

Figure 8.7. The ComboBox populates from the external XML document.

Now it's time to load the books for the author selected in the ComboBox. When the application first loads, it should show the books for the first author.

The class file needs a public method that returns the <books> element for the selected author. Switch to the custom class file and add the following getBooks() public method:

public function getBooks(authorIndex:int):XMLListCollection {
  bookElements = xmlAllContent.authors.author[authorIndex].books.book;
  bookElementsCollection = new XMLListCollection(bookElements);
  return bookElementsCollection;
}

This method takes as its only argument the selected author index from the ComboBox. This value equates to the index of the <author> element in the XML object.

The method creates an XMLList called bookElements from the list of all <book> elements for the current author. It does this using the E4X expression xmlAllContent.authors.author[authorIndex].books.book. The getBooks() method then creates an XMLListCollection from this XMLList object and returns it to be used as the dataProvider property for the DataGrid.

The application file calls this public method in two places. First, it calls the method after the ComboBox is loaded so the application can display the first author's books. It also calls the method in response to a change in the selectedIndex of the ComboBox so that the application can repopulate the DataGrid with the correct books.

Switch to the application file and add the following line to the completeHandler() function:

books_dg.dataProvider = myXMLLoader.getBooks(0);

This line calls the getBooks() public method when the application initializes, passing the first author index of 0. It sets the returned XMLListCollection as the dataProvider for the DataGrid, showing the books for the first author whose name displays in the ComboBox.

For the second method call, add the following line to the initApp() function:

authors_cbo.addEventListener(ListEvent.CHANGE, changeHandler);

Whenever the author chosen in the ComboBox changes, the application will call the changeHandler() function.

Now, you need to add the changeHandler() function. Add the following code block to your application file:

private function changeHandler(e:Event):void {
  books_dg.dataProvider = myXMLLoader.getBooks(e.target.
    
selectedIndex);
}

The changeHandler() function again sets the dataProvider property for the DataGrid by calling the getBooks() public method of the myXMLLoader object. This time, it passes the selectedIndex from the ComboBox to specify which <author> element to target. It finds the correct author using e.target.selectedIndex.

You need to set up the DataGrid to display the columns correctly before testing the application. If you tested the application now, you would see only the bookID displayed in the DataGrid; the remaining information wouldn't appear.

The easiest way to modify the setup of the DataGrid is within the MXML element itself. Modify the element as shown here. Notice that you need to rewrite the <mx:DataGrid> element with a closing tag.

<mx:DataGrid width="350" height="150" id="books_dg" editable="true">
  <mx:columns>
    <mx:DataGridColumn headerText="ID" dataField="@bookID"
      editable="false" width="50"/>
    <mx:DataGridColumn headerText="Name" dataField="bookName"
      width="200"/>
    <mx:DataGridColumn headerText="Publish year"
      dataField="bookPublishYear" width="50"/>
    <mx:DataGridColumn headerText="Cost" dataField="bookCost"
      width="50"/>
  </mx:columns>
</mx:DataGrid>

The <mx:DataGrid> element includes the list of all columns to display inside the <mx:columns> element. Each column contains a headerText, dataField, and width attribute. The dataField determines which element to display from the dataProvider, and the value equates to the name of a child element. Notice that the expression uses an @ sign to indicate that bookID is an attribute.

The first <mx:DataGridColum> element also sets the first column to be read-only so that the user can't edit the bookID value. Normally, this value would equate to the primary key in the data source and would be maintained externally. Because the <mx:DataGrid> element contains the attribute editable="true", it will be possible for a user to edit all other columns.

Test the application again. You should see the book information displaying correctly in the DataGrid, as shown in Figure 8-8.

Figure 8.8. The DataGrid synchronizes with the selected author.

Now that the interface is set up, it's time to look at adding, editing, and deleting book information. Remember that the application will change only the XML object in the SWF application, and not in the external document, as Flex isn't capable of updating external content.

When you finish building this application, the class file will contain public methods that add, edit, and delete <book> elements from the XML object. The application file will call these methods to process the updates made in the interface. Before it continues, it will need to know that the updates have been completed. Each of the public methods must dispatch an event to the application, notifying it that this has occurred.

After the application receives this event, it can refresh the dataProvider for the DataGrid and display the updated XML object in the TextArea control. This process must occur with every type of modification made in the interface.

You'll create a new event in the class file to be dispatched when changes have been completed. This event is called xmlUpdated, and you'll create a handler function in the application file to respond when it is notified of the event.

Switch to the custom class file MyXMLLoaderHelper.as. Declare the event by adding the following [Event] metadata tag above the class declaration:

[Event(name="xmlUpdated", type="flash.events.Event")]

This is an event called xmlUpdated with an Event type. In this case, the application doesn't need a custom Event object, because you're not passing information with the event. The metadata tag needs to declare this event so that the application file will recognize it correctly.

Switch to the application file and add a handler for this new event in the initApp() function, as shown here:

myXMLLoader.addEventListener("xmlUpdated", xmlUpdatedHandler);

Whenever the application file is notified of the xmlUpdated event, it will call the xmlUpdatedHandler() function. Add the xmlUpdatedHandler() function that follows to the <mx:Script> block:

private function xmlUpdatedHandler(e:Event):void {
  books_dg.dataProvider = myXMLLoader.getBooks(
    
authors_cbo.selectedIndex);
  tree_txt.text = myXMLLoader.getXML().toXMLString();
}

This handler function sets the dataProvider property for the books_dg control, which effectively refreshes the content in the DataGrid. It also displays a String representation of the XML object in the TextArea component so that you can see the updated content. You'll want to repeat these steps every time a user changes book details.

Now it's time to add more functionality so that a user can make modifications to the books. You'll start by seeing how to add a new book to the currently selected author.

You need an event handler that responds when a user clicks the Add book button. Add the following line to the initApp() function:

addRow_btn.addEventListener(MouseEvent.CLICK, addClickHandler);

You also need to add the addClickHandler() function to the <mx:Script> block. The function follows. Note that it references a public method of a custom class, addBook(), that you have yet to create.

private function addClickHandler(e:MouseEvent):void {
  var newBookName:String = name_txt.text;
  var newPublishYear:String = year_txt.text;
  var newBookCost:String = cost_txt.text;
  var authorIndex:int = authors_cbo.selectedIndex;
  if(newBookName.length > 0 && newPublishYear.length > 0
    
&& newBookCost.length > 0) {
    myXMLLoader.addBook(authorIndex, newBookName, newPublishYear,
      
newBookCost);
  }
}

The addClickHandler() function receives a Mouse Event as an argument. The function declares variables for each of the user entries and checks that the user entered a value for each one. If this is the case, the function calls the addBook() method of the myXMLLoader instance, passing the selected author index as well as the new values. You'll set up this public method next.

I didn't add any functionality to deal with the situation where a user doesn't enter all of the information for a book and then clicks the button. Feel free to extend this example to display an error message in the interface when this occurs.

Switch to the MyXMLLoaderHelper class file. Add the following addBook() public method to process the new book details:

public function addBook(authorIndex:int, bookName:String,
  
bookPublishYear:String, bookCost:String):void {
  var newBookXML:XML;
  newBookXML = <book bookID=''></book>;
  newBookXML.bookName = bookName;
  newBookXML.bookPublishYear = bookPublishYear;
  newBookXML.bookCost = bookCost;
  xmlAllContent.authors.author[authorIndex].books.
    
appendChild(newBookXML);
  dispatchEvent(new Event("xmlUpdated"));
}

This method receives the selectedIndex from the ComboBox and the new book values as parameters. The selectedIndex is called authorIndex, and this value corresponds with the node index for the <author> element in the XML object.

The addBook() method declares a new local XML object called newBookXML and populates it with a <book> element containing an empty bookID attribute. It then adds the bookName, bookPublishYear, and bookCost properties to this object. Notice that, instead of using appendChild(), you've used dot notation to speed up the process.

This method finishes by using the appendChild() method to add the newly created <book> element as the last child of the current author's <books> element. In the last line, the method finishes by dispatching an xmlUpdated event to inform the application that the updating of the XML object is complete. The application will then respond by calling the xmlUpdatedHandler() function.

Test the application and enter a new book. The application should add the new book to the selected author, updating both the DataGrid and TextArea. Figure 8-9 shows a new book added to the author Douglas Donaldson. It appears in both the XML tree in the TextArea and as a new row at the bottom of the DataGrid.

Figure 8.9. Adding a new book

You'll now add functionality so that a user can delete a book from the DataGrid and XML object. By selecting a row and clicking the Delete selected book button, a user can remove a book. Start by adding an event listener to respond when the Delete selected book button is clicked.

Add the following line to the initApp() function in the MXML file:

delete_btn.addEventListener(MouseEvent.CLICK, deleteClickHandler);

Add the following deleteClickHandler() function to the <mx:Script> block. This method calls a deleteBook() public method from the class file that you'll add shortly.

private function deleteClickHandler(e:MouseEvent):void {
  var bookIndex:int = books_dg.selectedIndex;
  var authorIndex:int = authors_cbo.selectedIndex;;
  if (books_dg.selectedIndex != −1) {
    myXMLLoader.deleteBook(authorIndex, bookIndex);
  }
}

The deleteClickHandler() function receives a MouseEvent as an argument and declares two variables: one for the selected DataGrid row index, called bookIndex, and one for the selected author index, called authorIndex. It assigns values for these variables.

The function then checks that the user has selected a row in the DataGrid. If no row is selected, the selectedIndex will have a value of −1.

The function finishes by calling the deleteBook() public method of the myXMLLoader object to carry out the deletion. It passes both the authorIndex and bookIndex so that the public method will be able to locate the correct element.

Switch to the MyXMLLoaderHelper class file. Add the following deleteBook() public method to handle the book deletion:

public function deleteBook(authorIndex:int, bookIndex:int):void {
  delete(xmlAllContent.authors.author[authorIndex].books.
    
book[bookIndex]);
  dispatchEvent(new Event("xmlUpdated"));
}

This public method uses the ActionScript 3.0 delete() operator to remove the relevant <book> element. It locates the correct element with the E4X expression xmlAllContent.authors.author[authorIndex].books.book[bookIndex]. The method then dispatches the xmlUpdated event to notify the application that the updates are finished.

Test the application and make sure that you can remove a row from the DataGrid. If you look at the TextArea control, you should see that the element has been removed from the XML object as well.

The final task is to allow the user to edit entries in the DataGrid. A user will be able to modify any value except for the bookID. As I've noted, that value is usually allocated by the external data source.

As with the Flash example, the application will handle when the editing of an individual cell ends by responding to a DataGridEvent. The updating will happen immediately after each cell has been edited.

Switch to the application file. Import the DataGridEvent class with the following import statement. Add it with the other import statements at the top of the <mx:Script> block.

import mx.events.DataGridEve

Add the following event listener to the initApp() function:

books_dg.addEventListener(DataGridEvent.ITEM_EDIT_END,
  
itemEditEndHandler);

The application responds when the user finishes editing a cell by referencing ITEM_EDIT_END. This value indicates that the editing of a cell is ending, and it will allow the application to capture both the starting and ending values.

Add the following itemEditEndHandler() function to process the changes to the cell value:

function itemEditEndHandler(e:DataGridEvent):void {
  var authorIndex:int = authors_cbo.selectedIndex;
  var dg:DataGrid = e.target as DataGrid;
  var field:String = e.dataField;
  var row:Number = Number(e.rowIndex);
  var col:int = e.columnIndex;
  var oldVal:String = e.itemRenderer.data[field];
  var newVal:String = dg.itemEditorInstance[dg.columns[col].
    
editorDataField];
  if (oldVal != newVal) {
    myXMLLoader.modifyXMLTree(authorIndex,
      
dg.columns[col].dataField, row, newVal);
  }
}

This function calls a public method, modifyXMLTree(), which you have yet to add to the class file. It starts by declaring an object for the DataGrid and locating it with the expression e.target. The code uses as to type the object correctly as a DataGrid.

The function identifies the dataField being modified as well as the row and column being changed. It also declares variables for the original and changed values so that they can be compared to see if a change actually took place.

If the values are not the same—that is, something has been modified—the itemEditEndHandler() function calls the modifyXMLTree() public method of the myXMLLoader object. It passes the name of the field being edited; the row number in the DataGrid, which will equate to the <book> node index; and the new value entered by the user.

Switch to the class file and add the modifyXMLTree() method shown here:

public function modifyXMLTree(authorIndex:int, fieldName:String,
  
elementIndex:int, newVal:String):void{
  var newXMLString:String = "<" + fieldName + ">" + newVal +
    
"</" + fieldName + ">";
  xmlAllContent.authors.author[authorIndex].books.book[elementIndex].
    
replace(fieldName, newXMLString);
  dispatchEvent(new Event("xmlUpdated"));
}

This public method creates a new String variable that contains the changed value, formatted as an XML element. It uses the fieldName value passed from the MXML file for the element name. It will produce a variable containing the structure <fieldName>New value</fieldName>.

The modifyXMLTree() method then uses an E4X expression to locate the relevant <book> element being edited. In the expression xmlAllContent.authors.author[authorIndex].books.book[elementIndex], the authorIndex indicates which <author> element to target; the elementIndex indicates the <book> index to use. The function uses the replace() method to update the existing element and replace it with the provide String content. Finally, the function dispatches the xmlUpdated event so that the application can refresh the interface.

Test the application and check that you can edit the name, publish year, and cost of each item. Also make sure that the contents of the TextArea control are updated with each of your changes.