Document Context="Item" requirement for Web Forms compatibility (#310)

Co-authored-by: csharpfritz <78577+csharpfritz@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

Author: Copilot

docs/DataControls/DataList.md

@@ -28,7 +28,7 @@ The DataList component is meant to emulate the asp:DataList control in markup an
     - `EnableViewState`
 - `ID` should be converted to `@ref` if the component is referenced in code
 - `ItemType` MUST be defined as an attribute
-- `Context` should be used to define the object used in templates.  If not defined, the default `<INSERT>` will be available.
+- **For Web Forms compatibility, use `Context="Item"`** to access the current data item in templates with the name `@Item` instead of Blazor's default `@context`
 
 ## Web Forms Declarative Syntax
 

docs/DataControls/FormView.md

@@ -10,6 +10,10 @@ The FormView component is meant to emulate the asp:FormView control in markup an
 
 ## Usage Notes
 
+- **ItemType attribute** - Required to specify the type of items in the collection
+- **Context attribute** - For Web Forms compatibility, use `Context="Item"` to access the current item as `@Item` in templates (ItemTemplate, EditItemTemplate, InsertItemTemplate) instead of Blazor's default `@context`
+- **ID** - Use `@ref` instead of `ID` when referencing the component in code
+
 ## Web Forms Declarative Syntax
 
 ```html

docs/DataControls/GridView.md

@@ -8,6 +8,7 @@ The GridView component is meant to emulate the asp:GridView control in markup an
 ### Blazor Notes
 
 - The `RowCommand.CommandSource` object will be populated with the `ButtonField` object
+- **Context attribute** - When using `<TemplateField>`, add `Context="Item"` to access the current row item as `@Item` instead of Blazor's default `@context`
 
 ## Web Forms Declarative Syntax
 

docs/DataControls/ListView.md

@@ -21,7 +21,9 @@ The ListView component is meant to emulate the asp:ListView control in markup an
 
 ## Usage Notes
 
- - LayoutTemplate requires a `Context` attribute that defines the placeholder for the items
+- **LayoutTemplate** - Requires a `Context` attribute that defines the placeholder for the items
+- **Context attribute** - For Web Forms compatibility, use `Context="Item"` on the ListView to access the current item as `@Item` in ItemTemplate and AlternatingItemTemplate instead of Blazor's default `@context`
+- **ItemType attribute** - Required to specify the type of items in the collection
 
 ##### [Back to top](#listview)
 

docs/DataControls/Repeater.md

@@ -39,3 +39,29 @@ The Repeater component is meant to emulate the asp:Repeater control in markup an
         </SeparatorTemplate>
 </asp:Repeater>
 ```
+
+## Usage Notes
+
+- **ItemType attribute** - Required to specify the type of items in the collection
+- **Context attribute** - For Web Forms compatibility, use `Context="Item"` to access the current item as `@Item` in templates instead of Blazor's default `@context`
+- **ID** - Use `@ref` instead of `ID` when referencing the component in code
+- **runat** and **EnableViewState** - Not used in Blazor (these attributes are ignored)
+
+## Blazor Example
+
+```razor
+<Repeater Items="products" ItemType="Product" Context="Item">
+    <HeaderTemplate>
+        <h2>Product List</h2>
+    </HeaderTemplate>
+    <ItemTemplate>
+        <div class="product">@Item.Name - $@Item.Price</div>
+    </ItemTemplate>
+    <SeparatorTemplate>
+        <hr />
+    </SeparatorTemplate>
+    <FooterTemplate>
+        <p>End of list</p>
+    </FooterTemplate>
+</Repeater>
+```

docs/Migration/migration_readiness.md

@@ -20,6 +20,11 @@ Throughout this document, we will refer to several framework and technology term
 - Class libraries referenced need to be convertible to .NET Standard
 - No 3rd party control libraries that don't have a shim for conversion (none available at the time of this writing)
 
+### Data-Bound Controls
+
+- For data-bound controls (Repeater, DataList, GridView, ListView, FormView), use `Context="Item"` attribute to access items with `@Item` instead of Blazor's default `@context`
+- This provides compatibility with Web Forms' strongly-typed `Item` property when using `ItemType` attribute
+
 ## Application architecture suggestions
 
 - Prefer model-binding techniques over handling Form life-cycle events like `Init`, `Load`, `PreRender`, and `Unload`

docs/Migration/readme.md

@@ -113,6 +113,41 @@ Alternatively, you can add the script manually to your layout:
 
 For more options and details, see the [JavaScript Setup documentation](../UtilityFeatures/JavaScriptSetup.md).
 
+## Step 5.6 - Data-Bound Controls and Template Context
+
+When migrating data-bound controls like `<asp:Repeater>`, `<asp:DataList>`, `<asp:GridView>`, `<asp:ListView>`, and `<asp:FormView>`, you'll encounter a key difference in how templates access the current data item.
+
+### Web Forms vs. Blazor Context
+
+In ASP.NET Web Forms, when using strongly-typed data-binding with the `ItemType` attribute, templates access the current item using the `Item` property. In Blazor, templated components use a context variable.
+
+**Blazor's Default Behavior:**
+By default, Blazor uses `@context` as the variable name inside templates:
+
+```razor
+<Repeater Items="widgets" ItemType="Widget">
+    <ItemTemplate>@context.Name</ItemTemplate>
+</Repeater>
+```
+
+**Web Forms Compatibility:**
+For better compatibility with Web Forms conventions and to reduce migration friction, **use the `Context="Item"` attribute** on data-bound components. This allows you to use `@Item` (similar to Web Forms' `Item` property):
+
+```razor
+<Repeater Items="widgets" ItemType="Widget" Context="Item">
+    <ItemTemplate>@Item.Name</ItemTemplate>
+</Repeater>
+```
+
+This pattern applies to all templated data controls:
+- `<Repeater>` - ItemTemplate, AlternatingItemTemplate, HeaderTemplate, FooterTemplate
+- `<DataList>` - ItemTemplate, AlternatingItemTemplate, HeaderTemplate, FooterTemplate
+- `<ListView>` - ItemTemplate, AlternatingItemTemplate, LayoutTemplate, GroupTemplate
+- `<FormView>` - ItemTemplate, EditItemTemplate, InsertItemTemplate
+- `<GridView>` with `<TemplateField>` - ItemTemplate
+
+**Note:** While it's one extra attribute per component, using `Context="Item"` eliminates the need to learn Blazor-specific `@context` syntax and makes your templates more readable for developers familiar with Web Forms.
+
 ## Step 6 - Pages
 
 Page migration is a process very similar to UserControls, except working on files with the `.aspx` extension.