On API Names, Documentation... and... ExtractTemplateRows

Opinions on documentation, API naming, and a quiz for readers...

Recently, Mike posted his experiences relying on intellisense instead of documentation while working with the new Whidbey Mail APIs. I am one of those (assuming there is such a camp) who believe a class browser and/or intellisense should suffice for understanding an API without requiring topic after topic of reference documentation. Sure, I am exaggerating a bit. I think conceptual documentation is far more important so it can help explaining whats there, why it is there, and how it can be used. The idea is that consistent naming (all public names: type names, properties, methods, events, and yes, parameters as well) combined with standard design patterns go a long way in helping preserve the flow of thought while programming, without requiring a context switch into the documentation viewer.

Resources such as the design guidelines, and Brad's Designing .NET Class Libraries series go a long way in documenting and establishing these conventions and designs. Go through them, and then be sure to keep a copy of the reference handy.

The .NET framework is (generally speaking) more consistent than things like Win32, COM and script APIs. Sure there are exceptions and some relatively harder and more involved APIs, and you can tell them apart as soon as you find the need to reach for F1, or the need to browse to your favorite search engine. Alas, I have my own share in contributing badly named APIs... one that is fresh in memory from a recent discussion with folks here is the "ExtractTemplateRows" property on DataList from v1. I am sure there are others APIs... :-).

So here is a quiz for you guys: what does this funky sounding property do?

Posted on Friday, 8/12/2005 @ 4:34 PM | #ASP.NET


Comments

9 comments have been posted.

i/Noodle

Posted on 8/13/2005 @ 2:41 AM
Ooo, I remember reading that one in Dino Esposito's asp.net book. I vaguely remember that it 'extracts' rows from any nested list item tables and combines them into the one main table for the list.
I must admit I've pretty much avoided the datalist in favour of the repeater, so I've never been entirely clear on 'why' i'd want to do the extraction.

Nikhil Kothari

Posted on 8/13/2005 @ 9:00 AM
The documentation seems reasonable except it leaves out an important reason for the existence of this property, which is what I was hoping to see in the answers. It sure does give away some of the answer to this quiz. Given that, let me also add this question to the quiz - what would you name this property so its name would be more intuitive, and you wouldn't need a long msdn reference topic in the first place?

I'd also love to hear what people are trying that causes them to ignore controls such as DataList and DataGrid/GridView and miss out on lots of (what I think) useful features by resorting to Repeater.

i/Noodle

Posted on 8/13/2005 @ 10:06 AM
The question of the repeater over datalist etc is interesting, but (for me) quite complex.
Over the 3 or more years I've used asp.net, I've transformed from someone who uses the visual studio designer, to someone who never uses the designer. This has been in part due to the fact that I use css for layout, and the designer just can't seem to cope well enough, and in part because of the known issues with the designer reformatting / losing code etc.
Now you can't use css long before you realize the need to validate your html to ensure its not the reason for the layout failing etc. This then leads to the realization that asp.net 1.1 has 'issues' in this area. The markup thrown out by many of the controls is quite nasty, and using them without the wizards in the designer reduces a lot of the RAD benefits anyway. Added to this is the fact that often the extra features aren't needed, and lower level controls can provide everything thats needed.
Many of the extra features really need a dataset as the datasource to get the free goodies, and since I've got a domain model / persistence framework which deals with entities / collections, its usually just too much like hard work, and easier to just iteratively add the 'required' functionality as the site develops.

Phew. Hope that makes some sense - as I said its complex, and I haven't fully solidified my reasoning.

Perhaps with asp.net 2.0 I'll be able to use the designer again, but I'm very afraid that the whole 'generic control' concept isn't quite providing the benefits it should / could.

Nikhil Kothari

Posted on 8/15/2005 @ 9:30 PM
OK, first off to answer the question (as mentioned, the documentation on msdn does a reasonable job), but the key idea or the motivation behind the property is to be able to create tabular UI where columns align perfectly across rows (the browser does a real good job laying out tables), as well as to create DataList items that each contain multiple rows. Without the ExtractTemplateRows feature, you can achieve such layout, but its impossible to reliably align columns. You can sort of implement such layouts using Repeater, but you have to resort to HTML fragments for template contents, thereby losing any design ability.

For example if you want your items to be three columns, where the 1st column spans two rows, and the 2nd column in the 1st row spans two columns, you could use the following:
<ItemTemplate>
<asp:Table runat="server">
<asp:TableRow>
<asp:TableCell RowSpan="2">...</asp:TableCell>
<asp:TableCell ColumnSpan="2">...</asp:TableCell>
</asp:TableRow>
<asp:TableRow>
<asp:TableCell>...</asp:TableCell>
<asp:TableCell>...</asp:TableCell>
</asp:TableRow>
</asp:Table>
</ItemTemplate>

This property is actually also personally interesting to me - its one of those properties that has existed since the early XSP/prototyping days way before v1 started to take shape. The feature was initially slated to be cut in fact, simply because there was no reasonable and short name to describe it... but I managed to save it... partly by simply leaving the code in there... The sad part about it is that it is limited to <asp:Table> and doesn't support <table runat="server" />. The latter would have made it designable.

On Repeater vs. DataList - I understand a lot of people choose the former for full control over rendering, or should I say percieved control. Sure, with the DataList you loose some control. But there are a number of style properties each with CssClass as well if you'd like, and we do in fact merge them logically (for example, the 2nd item picks up AlternateItemStyle followed by ItemStyle) that allow quite a bit of control over the rendering. In return for the abstraction you get all sort of goodies such as horizontal and vertical layout, fixed number of columns and wrapping (which by the way can't be done with CSS), separator items etc. etc. Also note that the controls work with plain IEnumerable, and optimize if they find an implementation of IList. You are by no means restricted to using DataSets. The whole data-binding architecture in ASP.NET v1 and v2 is based on being able to enumerate rows.

Léon Andrianarivony

Posted on 8/16/2005 @ 1:28 AM
I have write an article on it here http://www.dotnetguru.org/articles/DP/PagedList/PagedDataList.htm, sorry it is in French.
I have explain how powerfull is the "ExtractTemplateRows" property on "DataList" than a DataGrid. This property is very helpfull when we need a grid layout on a DataList and combine it with a ItemTemplate, you can do everything. Maybe this is the reason why DataList can be more powerfull than a DataGrid, because, in a DataGrid, you can't provide your custom template Row.

i/Noodle

Posted on 8/17/2005 @ 2:12 AM
Hi,
Late reponse with regard to the use of datasets / IEnumerable. My point was that without a dataset, things like sorting require the implementation of IComparable, whereas the dataset automatically gives you some workable implementations.

Suman Chakrabarti

Posted on 9/12/2005 @ 10:25 AM
I have to admit that even though I've used this property, every time I read the name it is really confusing to me. I had come up with another name for it, "AutoAlignColumns".

If this makes it into the final release of Beta 2, I'll send you my bill :)

ujjwal

Posted on 5/30/2006 @ 2:43 AM
hey nikhil can there be 2 headres in gridview???
what i want is that can there be headers and subheaders in gridview?
The discussion on this post has been closed. Please use my contact form to provide comments.