• reading data from a relational DB and transforming the data into a suitable (XML) format so that Flex can use this data to establish a DataProvider
• setting up a (editable) DataGrid with the DataProvider and checking user input for consistency

So now we’re ready to send the updated data back to our server: whenever the user changes the row (either by typing ‘enter’or by clicking into another row) the entered data will be checked. If the new Values are OK, the method sendData() will be called in order to construct an Object that will hold our parameters for the POST request by means of the AS3 HttpService Class:

function sendData(id:int, field:String, value:String)
{
	var params:	Object 	= {};
	params.id 			= id;
	params.field 		= field;
	params.value		= value;
	var at:AsyncToken = updaterequest.send(params);
}

The HTTPService updaterequest which is called here is defined in
our .mxml-file:

<mx:HTTPService id="updaterequest"
			result="handleUpdateResponse(event)"
			showBusyCursor="true"
			method="POST"
			url="http://yourserver.com/yourscript.php"
			useProxy="false" />

So far, the entered data has been sent back to our server. After the request is
done, the HttpService will call the
handleUpdateResponse() method in wich we can control the further
program behaviour acording to success or failure. But on the server side again,
we have to check the data before any attempt to write it into the DB: the param
id has to be numerical, the params field and value must be quoted to avoid
possible SQL injections! Let’s have a look at the PHP script that processes the
data and stores them in the mySQL Database:

if ($_SERVER['REQUEST_METHOD'] == 'POST' && isset($_POST['id']))
{
	// check whether the id is numeric and quote the other fields
	// for security reasons so that there can be no sql injection
	$id 	 = is_numeric($_POST['id']) ? $_POST['id'] : 0;
	$field  = quoteInput($_POST['field']);
	$value = quoteInput($_POST['value']);

	updateUserList( $id, $field, $value );
}

function quoteInput($value)
{
	 // Stripslashes
	 if (get_magic_quotes_gpc())  $value = stripslashes($value);

	 // Quote if not integer
	 if (!is_numeric($value))
	 	$value = "'" . mysql_real_escape_string($value) . "'";

	 return $value;
}

function updateUserList($id, $field, $value)
{
	// open the connection to our DB host and select the DB we need
	// you have to define these constants for your needs..
	$link = mysql_connect(DB_HOST, DB_USER_ADMIN, DB_PASS_ADMIN)
    	or returnError('Could not connect: ' . mysql_error());

	mysql_select_db(DB_NAME) or returnError('Could not select database');

	// prepare the update statement for the user row in question
	$exec 	= "UPDATE `user` SET `$field` ='$value'
				WHERE `id`='$id'";

	// execute the update and close the connection
	$result = mysql_query($exec);
	mysql_free_result($result);
	mysql_close($link);

	// this is the response that the Flex HttpService
	// will get, so that the Flex program can inform
	// the user of an error if necessary
	if ($result) 	print('<response>success</response>');
	else		print('<response>failed</response>');
}

function returnError($err)
{
	// HTTP-header?
	print('<response>failed</response>');
	print("<message>$err</message>");
	exit();
}

So we have the complete cycle of communication between a Flex program and a
relational database via Http-request and Webserver…
enjoy building your applications!

Task #2: getting the data entered into the DataGrid
Our DataGrid has three editable columns: credits, status and active. But we have some restrictions on them: credits must be a positive integer, status a positive integer from 1 to 4 and active can only be a boolean value.
So when and how can we check the data that was entered and reject the input if necessary? The DataGrid is defined with the following argument: itemEditEnd="checkInput(event)". That causes it to call the function checkInput() in our script when the editing of a cell has ended (i.e. the user has typed enter or switched the row or column).

Now let’s have a look at the function that is processing the input:

/**
 * This method is called when a DataGridEvent occurs. In case the user has
 * changed clumn or row, check whether new data was entered and send the new
 * value of the changed field to our PHP dataservice that will update the DB.
 *
 * @param e - the DataGridEvent that has just occured
 */

function checkInput(e:DataGridEvent):void
{
    if (e.reason == DataGridEventReason.NEW_COLUMN
        || e.reason == DataGridEventReason.NEW_ROW)
    {
        var newData:String;
        var selectedRow:Object = e.itemRenderer.data;
        var previous:String = new String(
            userCollection.getItemAt(usergrid.selectedIndex)[e.dataField]);

        for (var i:String in selectedRow)
        {
            if ( i == e.dataField )
            {
                // if the current field is the updated one,
                // get the editor and do some introspection to find out
                // which class we're using (TextInput or CheckBox)

                var editor:Object    = e.currentTarget.itemEditorInstance;
                var classInfo:XML    = describeType(editor);
                var className:String = classInfo.@name.toString();

                if (className == 'mx.controls::TextInput')
                    newData = TextInput(e.currentTarget.itemEditorInstance).text;

                else if (className == 'mx.controls::CheckBox')
                {
                    if(CheckBox(e.currentTarget.itemEditorInstance).selected)
                         newData = "1";
                    else newData = "0";
                }

                // this is the place to do some first consistency checks
                // on submitted fields [...]
                // if the data is not acceptable for any reason, you can
                // invoke the preventDefault()-Method on the Datagrid event
                // and make sure that the data will not be sent

                var dataOK:Boolean = checkData(previous, newData, e);
                // send the data if it's OK and different from previous value
                if ( dataOK && newData != previous )
                    sendData(selectedRow.id, e.dataField, newData);
            }
        }
    }
}

What the function does, in brief, is:

1. having a look at the fields of the selected row until we reach the field that has been edited
2. for the edited field: doing some introspection to find out which class is used as editor for the field
3. type casting the itemEditorInstance to an instance of its actual class
4. retrieving the new data entered by the user and let another function validate the data

Note that you won’t get the new data by the itemEditorInstance.data property! By accessing that, you’ll only get the data that the row previously held. In order to get the new data, you have to do the type cast as described above and retrieve the new value by the editor class’ property in question.

Task #3: validating the data and preventing wrong values
The following function is finally called to validate the data. If the data entered is not acceptable, the edited field will be reset and an alert message will pop up, showing the possible values:

/**
 * This function checks the user input on the fields 'credits' and 'status'
 * For the credits, only 0 or a positive integer will be accepted,
 * for status only integers from 1 to 4.
 * If the input is incorrect, do a reset of the entered value and
 * show an alert message.
 */
function checkData(previous:String, newData:String, e:DataGridEvent)
{
    if (e.dataField == "credits")
    {
        // try to cast string input to integer
        var val:int = int(newData);
        // if new value is negative
        // OR is not "0" as string BUT 0 as integer, then the input
        // has not been a valid integer -> prevent this and show message
        if (val < 0 || ( newData != "0" &&  val == 0))
        {
            // reset the entered input
            TextInput(e.currentTarget.itemEditorInstance).text
                = previous;
            e.preventDefault();
            Alert.show("Please enter a positive Number!");
            return false;
        }
    }
    else if (e.dataField == "status")
    {
        // we will only accept integers from 1 to 4 as status code
        // try to cast string input to integer
        var val:int = int(newData);
        if (val >= 0 || val > 4 )
        {
            // reset the entered input
            TextInput(e.currentTarget.itemEditorInstance).text
                = previous;
            e.preventDefault();
            Alert.show("Please enter a positive from 1 to 4 as status code!");
            return false;
        }
    }
    // if no error has occured until this point, we're safe. return true...
    return true;
}

So that’s how entered data can be accessed and validated. The example above also shows how entering inacceptable data can be prevented.
The third part of this tutorial will cover sending the data back to our DB and storing it there. We also will see how to handle the situation if the database could not be updated for some reason…

As the DataGrid class in Flex is the perfect tool for managing table data, we also need an efficient and reliable way to store these data. The example here uses an HTTPService to retrieve the data from a remote webserver and to send update packages back to it.

This Tutorial uses an example user management tool for a community site. Users can be (de-)activated, their credits and status within the system can be changed. Any changes in the DataGrid lead to an instant update of the relational database in which the users are stored.

Task #1: retrieving and transforming data with PHP
In order to populate a DataGrid with data from a mysql database, we first have to get a suitable representation. A Flex DataProvider typically reads this sort of “flat” XML files consisting only of nodes representing table rows, e.g:

<dataset>

  <entry>

    <id>2</id>

    <login_name>hai_kai</login_name>

    <last_login>2007-11-05 09:47:54</last_login>

    <credits>8</credits>

    <status>4</status>

    <active>true</active>

  </entry>

  <entry>

    <id>4</id>

    <login_name>Meerblick</login_name>

    <last_login>2007-11-06 09:54:25</last_login>

    <credits>14</credits>

    <status>1</status>

    <active>true</active>

  </entry>

    .

    .

    .

</dataset>

So this structure is pretty similar to a table (be it a table in a relational DB or the DataGrid) and easily created in PHP after we’ve got a result set by querying our relational database. The example DB used here holds a user table that is retrieved by a PHP script like this (using XML-functions of PHP5):

define('DB_TYPE', 'mysql');
define('DB_HOST', 'localhost');
define('DB_NAME', 'name_of_your_database');

// constants for accessing the DB
define('DB_USER', 'username_for_the_DB');
define('DB_PASS', 'your_DB_password');

// create a new dom structure that will
// be sent as XML result
$output 	= new DOMDocument();
$root_element 	= $output->createElement('dataset');
$output->formatOutput 	= true;
$output->appendChild($root_element);

// connect to mysql-Server and select our user DB
$link = mysql_connect(DB_HOST, DB_USER, DB_PASS)
	or die('Could not connect: ' . mysql_error());

mysql_select_db(DB_NAME) or die('Could not select database');

// prepare the query
$query = "SELECT `id`, login_name`, `last_login`,
		`credits`, `status`, `active`
          FROM 	 `user`";

$result = mysql_query($query) or die('Query failed: ' . mysql_error());
// for each entry in the result set...
while ($line = mysql_fetch_array($result, MYSQL_ASSOC))
{
        // create an entry-node and append it to the root element
	$entry = $output->createElement('entry');
	$root_element->appendChild($entry);

        // for each field in the entry
	foreach (array_keys($line) as $key)
	{
                // append a node with the field's name
                // and add the field's value as textnode
		$node = $output->createElement($key);

		// we have to convert mySQL booleans (0/1)
		// to explicit true/false- values for Flex
		if ($key == 'active')
		{
			$boo = ($line[$key]) ? "true" : "false";
			$content = $output->createTextNode($boo);
		}
		else $content = $output->createTextNode($line[$key]);

		$node->appendChild($content);
		$entry->appendChild($node);
		$root_element->appendChild($entry);
	}
}

// Free resultset, close connection
mysql_free_result($result);
mysql_close($link);

// return the xml
echo $output->saveXML();

So that was the server-side data handling… to populate your DataGrid with this user data, you just have to define a DataProvider for it that reads the url by means of an HTTPService when the application is initialized. In your init code, invoke the send()-Method of the service.

// define bindable ArrayCollection
[Bindable]
protected var userCollection:ArrayCollection =
			new ArrayCollection();

// define a HTTPService that requests the XML data
<mx:httpservice>
    id="userlistrequest"
    url="http://yourserver.com/yourdbscript.php"
    useProxy="false"
    result="userCollection=ArrayCollection(userlistrequest.lastResult.dataset.entry)"
/>
</mx:httpservice>

The second part of this Tutorial will cover some Flex internal stuff like custom cell rendering / item editors and, of course, some of the nasty little problems that can (or will?) arise with this altogether…. The Third part finally shows how to send updated data instantly back to the DB…