Quick Reference for the Atlas DataTable
This is a list of Q&A about the Web.Data.DataTable control provided by the Atlas framework. All the examples provided refer to a DataTable instance named dataTable.
- How can I get a DataTable instance from the server?
- How can I pass a DataTable instance to the server?
- How many rows has my DataTable?
- I want to get the value in row x, column y.
- How can I add a new row to the DataTable?
- I want to update an existing row.
- I want to delete an existing row.
- Did I insert/update/delete any rows?
- I want to get my inserted/updated/deleted rows.
- What about columns?
- How can I clear my DataTable?
- How can I get a DataTable contained in a DataSet?
1. How can I get a DataTable instance from the server?
Just return it from your Page/Service method. For example, consider this WebMethod that returns a System.Data.DataTable instance:
#using System.Data;
[WebMethod]
public DataTable GetDataTable()
{
DataTable dt = new DataTable();
dt.Columns.Add(new DataColumn("Name", typeof(string)));
dt.Columns.Add(new DataColumn("LastName", typeof(string)));
dt.Columns.Add(new DataColumn("Email", typeof(string)));
dt.Rows.Add("John", "Doe", "john.doe@example.com");
dt.Rows.Add("Joe", "Smith", "jsmith@example.com");
return dt;
}
For example, if you declare this method in a Page, you can obtain the client DataTable instance by invoking the server method from the client proxy:
function getData() {
PageMethods.GetDataTable(onGetComplete);
}
function onGetComplete(result) {
var dataTable = result;
}
2. How can I pass a DataTable instance to the server?
When you are done with a client DataTable instance, you can pass it to any Page/Service method that accepts a System.Data.DataTable as an argument; the Atlas framework will take care of the serialization/conversion between types.
Note: actually it's not possible to pass a DataTable back to the server without building a custom type converter.
3. How many rows has my DataTable?
The number of rows in the DataTable can be retrieved with the statement
var nRows = dataTable.get_length();
4. I want to get the value in row x, column y.
This can be done use the getItem() and getProperty() methods of the Web.Data.DataTable class. The getItem() method returns a Web.Data.DataRow object, while getProperty() returns a value given a column name. Putting these two methods together, if we want to obtain the value in row x, column name 'y', we have to write a statement like
var theValue = dataTable.getItem(x).getProperty('y');
5. How can I add a new row to the DataTable?
A very simple way to add a new row is to create a row object using Javascript's object notation. Each field in the row object has the name of the corresponding column, while the value is the one to be inserted. For example, if our DataTable schema has the three columns 'Name', 'LastName', 'Email' of type String, we can build a row object for that schema with the statement:
var oRow = { Name:'John', LastName:'Doe', Email:'jdoe@example.com' }
and then pass this object to the add() method of the DataTable class:
dataTable.add(oRow);
to add the new row to the DataTable instance.
6. I want to update an existing row.
To update an existing row, we have to retrieve it using the getItem() method and then set the value for a particular column using the setProperty() method. For example, the statement
dataTable.getItem(1).setProperty('Name', 'Mary');
will set the value in the second row, column 'Name', to 'Mary'.
7. I want to delete an existing row.
To delete an existing row, just retrieve it with the getItem() method and then pass it to the remove() method. For example, the statement
dataTable.remove(dataTable.getItem(2));
will remove the second row from the DataTable.
8. Did I insert/update/delete any rows?
By writing a statement like:
var hasChanges = dataTable.get_isDirty();
we can know if the DataTable has been modified.
9. I want to get my inserted/updated/deleted rows.
This can be done with the statement
var oChanges = dataTable.getChanges();
that returns an object with three properties:
- inserted, that exposes an array containing the inserted rows;
- updated, that returns an array containing the updated rows;
- deleted, that returns an array containing the deleted rows;
Thus, to retrieve the updated rows we have to write:
var updatedRows = dataTable.getChanges().updated;
10. What about columns?
Info on a particular column can be retrieved with the statement
var colName = dataTable.getColumn('Name');
that returns the Web.Data.DataColumn instance for the 'Name' column. The DataColumn class exposes three methods:
- get_columnName(), returns the name of the column;
- get_dataType(), returns the type of data stored in the column;
- get_defaultValue(), returns the default value for the column.
11. How can I clear my DataTable?
A DataTable can be cleared with the statement
dataTable.clear();
12. How can I get a DataTable contained in a DataSet?
The Atlas framework represents a System.Data.DataSet instance as an array of Web.Data.DataTable objects. If we are dealing with a Page/Service method that returns a DataSet, we can for example get the first DataTable with the statement
var dataTable = dataSet[0];
Go Back to the Questions