Rarely has a feature sparked so much debate at Xceed as hierarchical master/detail. And I think that this feature made it in both the WinForms and WPF grids solely on the fact that our customer base kept requesting it. So here we are, a couple of years later, with a feature that when used appropriately can be a valid way to display information, but that can easily spiral into an incomprehensible mess. What I mean by this is that one level of detail information per master row is perfectly acceptable and legible, but throw in grouping and things start getting ugly. Add more than one detail level as well as grouping and you are in for a world of confusion. So whether you agree with me or not, let’s get started!
In order to be able to display master/detail data, the grid must be bound through a DataGridCollectionView to an underlying data source that contains hierarchical detail relations (not 100% true, but I will get to that later). The content of those relations will be displayed as the details of the data items in a grid or in another detail. Each relation is represented by a DataGridDetailDescription, which will automatically be created for:
Detail descriptions can also be explicitly defined by adding them to DetailDescriptions collection of the DataGridCollectionView to which the grid is bound.
In order for the detail to appear in the grid, the grid’s AutoCreateDetailConfigurations property must be set to true. At this point, you are probably wondering what the difference is between a “detail description” and a “detail configuration”, so I will explain it before continuing:
A “detail description” is the data representation of a detail relation while a “detail configuration” is its visual representation. See? Easy. 
So let’s see how this would look in code:
DataGridCollectionView view = new DataGridCollectionView( this.Orders.DefaultView );
DataGridControl grid = new DataGridControl();
grid.AutoCreateDetailConfigurations = true;
grid.ItemsSource = view;
If you have been following this series of posts, you knowthat “Orders” is a DataTable from the Northwind DataSet that also happens to contain a DataRelation (remember, these are automatically detected) to the OrderDetails DataTable.
In XAML, it would look like the following:
<Grid xmlns:xcdg="http://schemas.xceed.com/wpf/xaml/datagrid">
<Grid.Resources>
<xcdg:DataGridCollectionViewSource x:Key="cvs_orders"
Source="{Binding Path=Orders}"/>
</Grid.Resources>
<xcdg:DataGridControl x:Name="OrdersGrid"
ItemsSource="{Binding Source={StaticResource cvs_orders}}"
AutoCreateDetailConfigurations="True"/>
</Grid>
Notice that the DataGridCollectionViewSource is used in exactly the same way to display master/detail data as it is to display data that does not have relations, that is, when you let the automatic detection of detail relations do its thing. Now, if you want to intervene in this process, you are more than welcome to do so. Here’s how.
Detail Descriptions
Every detail description must have a unique, identifying relation name that can be provided through its RelationName property and that will be used by detail configurations to identify which description their configuration will be applied to. If the detail descriptions are automatically created, their relation name will be extracted from the underlying source or a default one will be provided. If they are explicitly provided, then their relation name must also be explicitly set.
The AutoCreateDetailDescriptions property of the DataGridCollectionView class determines whether detail descriptions are automatically created when a data relation is encountered in the data source and can only be set at construction time.
OK, enough copy and paste from the documentation. Let’s look at some code that changes the title that will be used to represent the resulting details in the HierarchicalGroupByControl and in other locations where the detail title is displayed:
view.DetailDescriptions[ "OrdersOrderDetails" ].Title = "Order Details";
In XAML:
<xcdg:DataGridCollectionViewSource.DetailDescriptions>
<xcdg:DataRelationDetailDescription RelationName="OrdersOrderDetails"
Title="Order Details"/>
</xcdg:DataGridCollectionViewSource.DetailDescriptions>
Now, if we were to bypass the automatic creation of the detail descriptions, it would be necessary to create the detail description and provide it to the DetailDescriptions collection of the DataGridCollectionView before it can be accessed. Of course, adding it to the collection with its Title property already set is probably a better idea.
DataGridCollectionView view = new DataGridCollectionView( this.Orders.DefaultView, typeof( System.Data.DataRowView ), true, false );
DataRelationDetailDescription relation = new DataRelationDetailDescription();
relation.RelationName = "OrdersOrderDetails";
relation.Title = "Order Details";
view.DetailDescriptions.Add( relation );
And now the XAML version, which does not do much in this case since we only have one detail relation; however, if the source were to contain more than one relation, by setting the AutoCreateDetailDescriptions property to false, only the “OrdersOrderDetails” relation would have been created.
<xcdg:DataGridCollectionViewSource x:Key="cvs_orders"
Source="{Binding Path=Orders}"
AutoCreateDetailDescriptions="False">
<xcdg:DataGridCollectionViewSource.DetailDescriptions>
<xcdg:DataRelationDetailDescription RelationName="OrdersOrderDetails"
Title="Order Details"/>
</xcdg:DataGridCollectionViewSource.DetailDescriptions>
</xcdg:DataGridCollectionViewSource>
Sibling and Child Detail Descriptions
Not only can each detail description can have one or more sibling detail descriptions (they will be contained in the same DetailDescriptions collection), they can also have one or more child detail descriptions, and so on and so forth.
Now I won’t go into detail about sibling and child detail descriptions. Just keep in mind that they work like the first-level detail descriptions, and that each has its own DetailDescriptions collection.
Ok, so now you know how to get your detail data displayed in a grid, and you know the difference between a detail description and a detail configuration.Let’s take a look at how to use the detail configurations to change the look of the details.
I have the sudden urge to count the number of times I have written the word “detail” so far...
Detail Configurations
As I previously mentioned, detail descriptions are the data representation of detail relations while detail configurations are their visual representation. Each detail that results from a detail description is configured according to its corresponding detail configuration, which is identified by its relation name (the same relation name that was used for or extrapolated by the corresponding detail description). By default, a detail configuration that contains a ColumnManagerRow and a TextBlock containing the detail title will be applied to all resulting details. Now, you can decide to change the configuration of all details, regardless of their level, through the grid’s DefaultDetailConfiguration property, or you can provide a detail configuration for a specific detail level through the grid’s DetailConfigurations collection.
Before I continue, I want to explain the difference between the default detail configuration and the configurations contained in the configuration collection. The main difference is their type: the DefaultDetailConfiguration property expects a DefaultDetailConfiguration while the DetailConfigurations collection expects DetailConfiguration types. Why? Well, since there is a direct one-to-one relation between a detail description and a detail configuration, we did not think it was a good idea to expose properties, such as RelationName and Title in the default detail configuration,since these properties could not be applied to all. So we decided to create the DefaultDetailConfiguration class, which only exposes the properties that can be applied to all details indiscriminately.
So let’s take a look at how we could use the default detail description to provide an InsertionRow in the footers of every detail:
DataTemplate template = new DataTemplate();
template.VisualTree = new FrameworkElementFactory( typeof( InsertionRow ) );
DefaultDetailConfiguration defaultConfiguration = new DefaultDetailConfiguration();
defaultConfiguration.Footers.Add( template );
grid.DefaultDetailConfiguration = defaultConfiguration;
And the XAML:
<xcdg:DataGridControl.DefaultDetailConfiguration>
<xcdg:DefaultDetailConfiguration>
<xcdg:DefaultDetailConfiguration.Footers>
<DataTemplate>
<xcdg:InsertionRow>
</DataTemplate>
</xcdg:DefaultDetailConfiguration.Footers>
</xcdg:DefaultDetailConfiguration>
</xcdg:DataGridControl.DefaultDetailConfiguration>
Now if we were to explicitly provide a detail configuration for a specific detail relation, the default detail configuration would be ignored and the explicit detail configuration would be used. So let’s see how that would look:
grid.AutoCreateDetailConfigurations= false;
DetailConfiguration configuration = new DetailConfiguration();
configuration.RelationName = "OrdersOrderDetails";
configuration.Title = "Order Details";
// Do not use the default headers ( TextBlock andColumnManagerRow )
configuration.UseDefaultHeadersFooters = false;
DataTemplate cmrTemplate = new DataTemplate();
cmrTemplate.VisualTree = new FrameworkElementFactory( typeof( ColumnManagerRow) );
configuration.Headers.Add( cmrTemplate );
grid.DetailConfigurations.Add( configuration );
XAML:
<xcdg:DataGridControl.DetailConfigurations>
<xcdg:DetailConfiguration RelationName="OrdersOrderDetails"
Title="Order Details"
UseDefaultHeadersFooters="False">
<xcdg:DetailConfiguration.Headers>
<DataTemplate>
<xcdg:ColumnManagerRow/>
</DataTemplate>
</xcdg:DetailConfiguration.Headers>
</xcdg:DetailConfiguration>
</xcdg:DataGridControl.DetailConfigurations>
In this situation there is one MAJOR difference between the code and the XAML: in code, the value of the AutoCreateDetailConfigurations property (which I will refer to as ACDC from now on because you can’t get a better acronym) is set to false, while in XAML, its value is of no importance in this situation. Let me explain: in XAML, when the ACDC property is set to true, the DetailDescriptions collection will be automatically populated with the appropriate detail configurations, and any items that are added to the collection will be “linked” to the existing item in the collection. If set to false (still in XAML), the collection will not automatically be populated, but by defining a configuration in the collection, it is also added at the same time. In code, as I have painstakingly learned, the ACDC property takes on a different personality... sort of... I have already explained that, when set to true, detail configurations will automatically be created and added to the DetailConfigurations collection. BUT what is not so obvious is that setting values of properties on the automatically created detail configuration does not provide the same result as creating a new DetailConfiguration for the specific detail relation. So, if ACDC remains true, you will need to replace the one that was automatically created with the new one. So to keep things simple, I would suggest you set the ACDC property to false and add the DetailConfiguration to the DetailConfigurations collection.
Custom Detail Descriptions
Remember in the first few paragraphs when I said that it was not 100% true that a data source must contain detail relations in order to display detail data? What I meant by that is that although the most common types of detail relations are automatically detected, it is also possible to create and use custom detail descriptions that will return detail items for a parent item, whatever the definition of the detail relation is.
Custom detail descriptions can be created by deriving from the DataGridDetailDescription class and overriding its GetDetailsForParentItem method to return the desired details for a data item. Now the detail data returned can be anything, as long as it is at least an IEnumerable. If a data item does not have detail data, simply return null.
I will not go into details about how to create a custom detail description, so if you want an example, you can take a look at the “Custom Detail Descriptions” topic in the documentation.
What Now?
This post ended up being much longer than I had originally anticipated! So if you read all the way to the end and have any questions or would like more information, please post it here or in the forums.
For those of you who are interested, I wrote “detail” 156 times.
