Improvement Request: Item containers and templates - confusing

[SetTrend]

After reading this page I have a strong feeling that the "Introduction to customization" chapter needs improvement because it's mixing up a template object with a structural design concept, and it's not clearly identifying or distinguishing between both.

What I see missing in the text depicted by the above screenshot:

1. "The control template provides [...]"

   There is no such thing like a control template available to the programmer. It's (supposedly) an intrinsic wrapper component being automatically added by WinRT as a parent of a 'DataTemplate' component. But that sort of information is not coming clear from the information in the bullet list.

2. "You can use the ItemContainerStyle property [...]"

   You can use? What are the alternatives then?

   This sentence should state clearly that a ListView's ItemContainerStyle properties get forwarded to the intrinsic wrapper component, called "control template".

3. The naming is misleading. A "control template" may be feast of famine.

   I suggest to revise the name. "Item Container" may be feasible, given that the corresponding ListView style property is called ItemContainerStyle.

   As there supposedly is no such thing like a ControlTemplate component publicly available, this item seems a document issue to me, too.

4. Is propose it should get clear from the documentation that two different wrappers exist around each of the list items just for one single purpose: the purpose of being able to distribute styling among two different "hooks", so styling can be eased when creating styles for a number of ListViews in an app. One set of styles addresses the DataTemplate object while the other set of styles addresses the wrapper object created and addressed by the ListView/GridView's ItemContainerStyle component; in combination these two sets of styles can then easily be intermixed.

5. "This image shows how the control template and the data template combine [...]"

   Frankly, this image (like seen in the screenshot above) doesn't show anything. It merely shows a green and a yellow row getting intermixed. It isn't even annotated, so it doesn't get clear what the green row refers to, or what the yellow row refers to.

   For this item, I propose to replace the image with meaningful content, similar to the following one (the annotations I used are just placeholders; you'll probably find better text annotations, explaining what the different parts in a ListView or GridView are):

   

---

I created the above animation using SVG, so it may be easily added to the documenation. Here's the source:

ListViewItem-Struktur-Animation (SVG).zip

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: 5d3f1b01-489f-e9d4-9e97-845757d31e6a
• Version Independent ID: 21d56dad-eff2-ab13-cbd3-468de4036338
• Content: Item containers and templates - UWP applications - Introduction to customization
• Content Source: windows-apps-src/design/controls-and-patterns/item-containers-templates.md
• Product: uwp
• Technology: design
• GitHub Login: @jwmsft
• Microsoft Alias: jimwalk