Collaborating with XtraGrid - General Information
Download VB and C# sources for this article
Introduction
This whitepaper will give you step by step instructions on how to use eXpress Persistent Objects for .NET with the XtraGrid SUite. XPO provides the data to be displayed, while XtraGrid obtains the data and shows it in the most appropriate manner. Most of the advanced features introduced by the XtraGrid for the display and manipulation of data can be easily used. The combination of these two tools is especially powerful for a developer who has to quickly retrieve data, visualize it and allow it to be modified.
Contents
This paper assumes that you have the two following products installed:
XtraGrid 2.0
eXpress Persistent Objects 1.0
Providing Data to Display
In order to designate the information to be displayed in a grid we have to specify its source and contents. This is a simple task - we will select the data stored in a database using various selection criteria. Suppose we have a simple Customer tracking system. Each Customer has several Addresses and multiple Orders. You can easily persist business objects by means of XPO. The business model for the application is shown below.
|
public class Address: XPObject {
public string City;
public string AddressLine;
public Address() : base() {
}
public Address(Session session) : base(session) {
}
[Association("Customer-Addresses")]
public Customer Customer;
}
public class Order: XPObject {
public DateTime Date;
public double Amount;
[Association("Customer-Orders")]
public Customer Customer;
public Order() : base() {}
public Order(Session session) : base(session) {}
}
public class Customer: XPObject {
public string FullName;
[Aggregated]
public Address DefaultAddress = null;
[Aggregated, Association("Customer-Addresses", typeof(Address))]
public XPCollection Addresses {
get {return GetCollection("Addresses");}
}
[Aggregated, Association("Customer-Orders", typeof(Order))]
public XPCollection Orders {
get {return GetCollection("Orders");}
}
public string Telephone;
public Customer() : base() {}
public Customer(Session session) : base(session) {}
}
Public Class Address : Inherits XPObject
Public City As String
Public AddressLine As String
Public Sub New()
End Sub
Public Sub New(ByVal session As Session)
MyBase.New(session)
End Sub
<Association("Customer-Addresses")> Public Customer As Customer
End Class
Public Class Order : Inherits XPObject
Public [Date] As DateTime
Public Amount As Double
<Association("Customer-Orders")> Public Customer As Customer
Public Sub New()
End Sub
Public Sub New(ByVal session As Session)
MyBase.New(session)
End Sub
End Class
Public Class Customer : Inherits XPObject
Public FullName As String
<Aggregated()> Public DefaultAddress As Address = Nothing
<Aggregated(), Association("Customer-Addresses", GetType(Address))> _
Public ReadOnly Property Addresses() As XPCollection
Get
Return GetCollection("Addresses")
End Get
End Property
<Aggregated(), Association("Customer-Orders", GetType(Order))> _
Public ReadOnly Property Orders() As XPCollection
Get
Return GetCollection("Orders")
End Get
End Property
Public Telephone As String
Public Sub New()
End Sub
Public Sub New(ByVal session As Session)
MyBase.New(session)
End Sub
End Class
|
With XPO, you can query the database and retrieve collections of persistent objects matching the specific criteria. To do this we create a special XPO object called a XPCollection, which represents a collection object. To create a collection at design time, drag an XPCollection object from the Developer Express tab of the Toolbox onto your form or component and adjust its properties. The only property we should worry about for the moment is the ObjectClassInfo. This property provides a selection of persistent objects defined in your application. By setting the property you specify the type of objects to be retrieved by the XPCollection (XtraGridSample.Customer object in our case). The DisplayableProperties property now shows a list of properties to be displayed in a bound control, such as the XtraGrid. This list is filled with property names separated by semicolons. Once you have selected a persistent object, all its properties are included in the list. We will leave the DisplayableProperties property unchanged for now. Let us name this collection of customers, say ‘xpCollectionCustomers’. 
Once the XPCollection is defined, you are only one step from using it as a data source for the XtraGrid control. You need to take the XPCollection data and pass it as the DataSource for the XtraGrid. XpoXtraDataAdapter is an intermediate object used to exchange data between the XPCollection and the XtraGrid. At design time, you can select the XpoXtraDataAdapter component from the Developer Express tab of the Toolbox, drag it onto your form or component and set its Collection property to refer to the XPCollection you previously defined.
Voila! You have prepared the xpoXtraDataAdapter1 to be a data source for the XtraGrid control.
Displaying Data in XtraGrid
Now you can select the xpoXtraDataAdapter1 from the list of available data sources in the DataSource property of the XtraGrid control.
XtraGrid automatically detects data relations represented in the XPCollection via the properties chosen by the DisplayableProperties and lets you design your grid view at this early step.
Run application and let us see the result.
Basically, this is what we need. XPCollection contents are displayed in the grid.
Now you can use the advanced features provided by the XtraGrid component for displaying, sorting and grouping data retrieved by the XPCollection.
Records in a grid can be sorted
grouped
and filtered
Now let us adjust the grid view to be more relevant by tweaking the data source object, that is, the XPCollection.
Tweaking the Grid View
As you can see we have some unnecessary fields being displayed, including system ones. It is time to do some tweaking. You can tweak the XPCollection contents and then adjust XtraGrid properties as a final touch.
First of all, you can freely edit the XPCollection.DisplayableProperties property list to preserve all of the properties sufficient for displaying data. For example, let us set Oid, FullName and Telephone fields visible in a grid.
So far we have not even opened the XtraGrid designer to customize the column properties. XtraGrid uses default settings to display the data. You can filter out the data to be displayed in a grid by removing unnecessary columns directly from the Column Designer. To do this, open the Column Designer and click the Retrieve Fields button to populate the Columns list with the persistent object properties provided by the XPCollection. Then click Remove button to delete all unnecessary columns from the list (we’d like to see Oid, FullName and Telephone columns only).
The resulting grid view will be the same as when you edited the DisplayableProperties list (see above).
To bind additional information linked to the selected customer, Order items, for instance, as well as any other information on the opposite end of the association (see business model above), include the collection name related to the association to the DisplayableProperties list of the XPCollection. To do this, we will add the Orders property related to the “Customer-Orders” association.
Since we have not included Orders to the Columns list in the XtraGrid, the data related to the Orders collection is not displayed in the main view of the grid, though it is displayed in the detail view. By clicking any of the “plus” symbols you can open a detail view.
To adjust the detail view, you can customize grid views in XtraGrid designer. For example, in the Views list of the XtraGrid you can specify the BandedGridView for the Orders collection. A new view named bandedGridView1 will be added to the Views list.
Select bandedGridView1 and pick Date and Amount fields in the Column Designer columns list.
To customize the band where order items will be displayed, open Band Designer. Here you can name the band, say “Orders”.
Each order item represents a “Many” end of the one-to-many relationship which is defined in the business model, that is why the Customer information is linked to the Order and this link can be visualized in the Orders band. To suppress the visualization, set EnableMasterViewMode in the OptionsDetail for the bandedGridView1 to False. Also we will disable group panel in the band by setting ShowGroupPanel in the OptionsView to False.
Now you can run application and see results.
By default, the data presented by the XPCollection is unsorted. You can precisely specify the sort order for the collections contents via its XPCollection.Sorting property. Select the XPCollection in the designer and then click the ellipsis (...) button in the Properties window to invoke the SortProperty Collection Editor. The SortProperty Collection provides the way to handle the sort order for XPCollection contents. Here you can add the SortProperty items that make up the SortProperty Collection as well as the order in which the items are arranged. Set the Direction and PropertyName for each item. Select PropertyName value from a list of the persistent object properties. Click OK button to save the Sorting property. Here we define sorting order by ascending FullName of the customer.
We need to add columns to the XtraGrid (see method above) in order to control the sorting order in a grid by the sorting order of the items in XPCollection.
The result is the following grid view.
By default, the XPCollection retrieves all persistent objects of the object class identified by the ObjectClassInfo property unless you specify the criteria to filter the objects to be included or to limit the size of the XPCollection by using the TopReturnedObjects property value (The default value of 0 requests the all objects be retrieved). For more information about this topic, see the XPO documentation.
Linked information can be displayed in a grid with ease. Let us include DefaultAddress information to the grid. To provide the data to display, add DefaultAddress.City and DefaultAddress.AddressLine properties to the xpCollectionCustomers.DislplayableProperties list.
Then, add new columns to the grid in the Column Designer. You can do these manually via the Add button or Retrieve fields and delete unnecessary columns from the list. Set Caption and FieldName properties as shown below.
In order to enforce the changes that occurred during field modification, we have marked the DefaultAddress property with the Aggregated attribute (see business model above). When you leave the grid record, the changes are saved to the database.
The resulting grid has the following view.
To learn more about working with the XtraGrid, read our next article on this subject (XPO.NET at Your Service. Collaborating with XtraGrid. Additional Tips).
Download VB and C# sources for this article To learn more about XPO, please write to us at: info@devexpress.com.
To order your copy, visit our online order page.
|