Skip to content

Commit cc1d2cb

Browse files
csharpfritzcsharpfritz
authored
Merge pull request #308 from csharpfritz/fix-docs
2 parents ef63e40 + 287fbcd commit cc1d2cb

13 files changed

Lines changed: 769 additions & 28 deletions

File tree

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,6 @@ There are a significant number of controls in ASP.NET Web Forms, and we will foc
3232
- [DropDownList](docs/EditorControls/DropDownList.md)
3333
- FileUpload
3434
- [HiddenField](docs/EditorControls/HiddenField.md)
35-
- [HyperLink](docs/EditorControls/HyperLink.md)
3635
- [Image](docs/EditorControls/Image.md)
3736
- [ImageButton](docs/EditorControls/ImageButton.md)
3837
- ImageMap
@@ -69,7 +68,8 @@ There are a significant number of controls in ASP.NET Web Forms, and we will foc
6968
- [RequiredFieldValidator](docs/ValidationControls/RequiredFieldValidator.md)
7069
- [ValidationSummary](docs/ValidationControls/ValidationSummary.md)
7170
- Navigation Controls
72-
- [Menu](docs/Menu.md)
71+
- [HyperLink](docs/NavigationControls/HyperLink.md)
72+
- [Menu](docs/NavigationControls/Menu.md)
7373
- SiteMapPath
7474
- [TreeView](docs/NavigationControls/TreeView.md)
7575
- Login Controls

‎docs/EditorControls/Button.md‎

Lines changed: 226 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,37 @@
1-
It may seem strange that we have a Button component when there already is an HTML button and Blazor has features that enable C# interactions with that button, but we need to activate other features that were once present in Web Forms. Original Web Forms documentation is at: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.button?view=netframework-4.8
1+
# Button
22

3-
## Blazor Features Supported
3+
The **Button** component displays a push button control that allows users to trigger actions. It may seem strange that we have a Button component when there already is an HTML button and Blazor has features that enable C# interactions with that button, but we need to activate other features that were once present in Web Forms, such as `OnCommand` event bubbling, `OnClientClick` JavaScript execution, and `CausesValidation` support.
44

5-
- OnClick event handler
6-
- OnClientClick JavaScript pointer
7-
- OnCommand event handler with event bubbling
8-
- Button Style attributes and CssClass formatting
9-
- CausesValidation will control whether Form validation is triggered on click
5+
Original Microsoft documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.button?view=netframework-4.8
106

11-
## WebForms Features Not Supported
7+
## Features Supported in Blazor
128

13-
- PostBackUrl is not supported as you will be triggering Button click events on the same page
14-
- UseSubmitBehavior is not supported as Blazor buttons trigger click events and you can inspect the Form regardless
9+
- `Text` - the text displayed on the button
10+
- `OnClick` - event handler triggered when button is clicked
11+
- `OnClientClick` - JavaScript code to execute on client-side click
12+
- `OnCommand` - event handler with event bubbling, receives `CommandEventArgs` with `CommandName` and `CommandArgument`
13+
- `CommandName` - the command name passed to `OnCommand` event
14+
- `CommandArgument` - the command argument passed to `OnCommand` event
15+
- `CausesValidation` - controls whether form validation is triggered on click (default: `true`)
16+
- `Enabled` - enables or disables the button
17+
- `Visible` - controls button visibility
18+
- `ToolTip` - tooltip text displayed on hover
19+
- All style properties (`BackColor`, `ForeColor`, `BorderColor`, `BorderStyle`, `BorderWidth`, `CssClass`, `Width`, `Height`, `Font`)
1520

16-
## WebForms Syntax
21+
### Blazor Notes
22+
23+
- The `OnCommand` event uses a `CommandEventArgs` class that contains `CommandName` and `CommandArgument` properties
24+
- When `CommandName` is set, clicking the button triggers `OnCommand` instead of `OnClick`
25+
- Event bubbling is supported for container components that need to handle commands from child buttons
26+
27+
## Web Forms Features NOT Supported
28+
29+
- **PostBackUrl** - Not supported; Blazor uses component events instead of postbacks to different pages
30+
- **UseSubmitBehavior** - Not supported; Blazor buttons trigger click events and you can inspect the form regardless
31+
- **ValidationGroup** - Not yet implemented; use EditForm validation instead
32+
- **AccessKey** - Use HTML `accesskey` attribute directly if needed
33+
34+
## Web Forms Declarative Syntax
1735

1836
```html
1937
<asp:Button
@@ -63,3 +81,200 @@ It may seem strange that we have a Button component when there already is an HTM
6381
Width="size"
6482
/>
6583
```
84+
85+
## Blazor Razor Syntax
86+
87+
### Basic Button with Click Event
88+
89+
```razor
90+
<Button Text="Click Me" OnClick="HandleClick" />
91+
92+
@code {
93+
void HandleClick()
94+
{
95+
// Handle the click
96+
}
97+
}
98+
```
99+
100+
### Button with Command
101+
102+
```razor
103+
<Button Text="Save"
104+
CommandName="Save"
105+
CommandArgument="@itemId"
106+
OnCommand="HandleCommand" />
107+
108+
@code {
109+
private string itemId = "123";
110+
111+
void HandleCommand(CommandEventArgs args)
112+
{
113+
var command = args.CommandName; // "Save"
114+
var argument = args.CommandArgument; // "123"
115+
}
116+
}
117+
```
118+
119+
### Button with JavaScript Click
120+
121+
```razor
122+
<Button Text="Alert" OnClientClick="alert('Hello World!')" />
123+
```
124+
125+
### Styled Button
126+
127+
```razor
128+
<Button Text="Styled Button"
129+
BackColor="WebColor.Blue"
130+
ForeColor="WebColor.White"
131+
Font_Bold="true"
132+
CssClass="my-button-class" />
133+
```
134+
135+
### Disabled Button
136+
137+
```razor
138+
<Button Text="Cannot Click" Enabled="false" />
139+
```
140+
141+
### Button with Validation Control
142+
143+
```razor
144+
<EditForm Model="@model" OnValidSubmit="HandleSubmit">
145+
<TextBox @bind-Text="model.Name" />
146+
<RequiredFieldValidator ControlToValidate="..." Text="Required" />
147+
148+
@* This button triggers validation *@
149+
<Button Text="Submit" CausesValidation="true" />
150+
151+
@* This button skips validation *@
152+
<Button Text="Cancel" CausesValidation="false" OnClick="HandleCancel" />
153+
</EditForm>
154+
```
155+
156+
## HTML Output
157+
158+
**Web Forms Input:**
159+
```html
160+
<asp:Button ID="btnSubmit" Text="Submit" CssClass="btn" runat="server" />
161+
```
162+
163+
**Rendered HTML:**
164+
```html
165+
<button type="submit" class="btn">Submit</button>
166+
```
167+
168+
**Styled Button Input:**
169+
```razor
170+
<Button Text="Styled" BackColor="WebColor.Blue" ForeColor="WebColor.White" />
171+
```
172+
173+
**Rendered HTML:**
174+
```html
175+
<button type="submit" style="background-color:Blue;color:White;">Styled</button>
176+
```
177+
178+
## Migration Notes
179+
180+
When migrating from Web Forms to Blazor:
181+
182+
1. **Remove `asp:` prefix** - Change `<asp:Button>` to `<Button>`
183+
2. **Remove `runat="server"`** - Not needed in Blazor
184+
3. **Remove `ID` attribute** - Use `@ref` if you need a reference to the component
185+
4. **Update event handler syntax** - Change `OnClick="btnSubmit_Click"` to `OnClick="HandleClick"`
186+
5. **Replace `PostBackUrl`** - Use navigation or component state instead
187+
6. **Update `OnCommand` handlers** - The signature changes from `(object sender, CommandEventArgs e)` to `(CommandEventArgs args)`
188+
189+
### Before (Web Forms)
190+
191+
```html
192+
<asp:Button ID="btnSave"
193+
Text="Save"
194+
OnClick="btnSave_Click"
195+
CssClass="btn btn-primary"
196+
runat="server" />
197+
```
198+
199+
```csharp
200+
protected void btnSave_Click(object sender, EventArgs e)
201+
{
202+
// Handle click
203+
}
204+
```
205+
206+
### After (Blazor)
207+
208+
```razor
209+
<Button Text="Save"
210+
OnClick="HandleSave"
211+
CssClass="btn btn-primary" />
212+
213+
@code {
214+
void HandleSave()
215+
{
216+
// Handle click
217+
}
218+
}
219+
```
220+
221+
## Examples
222+
223+
### Basic Click Handler
224+
225+
```razor
226+
<Button Text="Click Me!" OnClick="OnClick" />
227+
228+
<span style="font-weight: bold">@message</span>
229+
230+
@code {
231+
private string message = "Not clicked yet!";
232+
233+
void OnClick()
234+
{
235+
message = "I've been clicked!";
236+
}
237+
}
238+
```
239+
240+
### Command Pattern with Multiple Buttons
241+
242+
```razor
243+
<Button Text="Edit" CommandName="Edit" CommandArgument="@item.Id" OnCommand="HandleCommand" />
244+
<Button Text="Delete" CommandName="Delete" CommandArgument="@item.Id" OnCommand="HandleCommand" />
245+
246+
<p>Last action: @lastAction</p>
247+
248+
@code {
249+
private string lastAction = "None";
250+
251+
void HandleCommand(CommandEventArgs args)
252+
{
253+
lastAction = $"Command '{args.CommandName}' on item {args.CommandArgument}";
254+
}
255+
}
256+
```
257+
258+
### Styled Buttons
259+
260+
```razor
261+
@using static BlazorWebFormsComponents.WebColor
262+
263+
<Button Text="Blue Button" BackColor="Blue" ForeColor="White" />
264+
<Button Text="Red Bold Button" BackColor="Red" ForeColor="Yellow" Font_Bold="true" />
265+
<Button Text="Custom Class" CssClass="rounded-corners" />
266+
```
267+
268+
### JavaScript Integration
269+
270+
```razor
271+
<Button Text="Show Alert" OnClientClick="alert('Hello from JavaScript!')" />
272+
<Button Text="Confirm" OnClientClick="return confirm('Are you sure?')" OnClick="HandleConfirmed" />
273+
```
274+
275+
## See Also
276+
277+
- [LinkButton](LinkButton.md) - A button that renders as a hyperlink
278+
- [ImageButton](ImageButton.md) - A button that displays an image
279+
- [RequiredFieldValidator](../ValidationControls/RequiredFieldValidator.md) - Validate required fields
280+
- [Live Demo](https://blazorwebformscomponents.azurewebsites.net/ControlSamples/Button) - Interactive Button samples

‎docs/EditorControls/HiddenField.md‎

Lines changed: 89 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,34 @@
1-
The HiddenField component is meant to emulate the asp:HiddenField control in markup and is defined in the [System.Web.UI.WebControls.HiddenField class](https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.hiddenfield?view=netframework-4.8)
1+
# HiddenField
22

3-
## Blazor Features Supported
3+
The **HiddenField** component stores a non-displayed value that can be posted back to the server. It emulates the `asp:HiddenField` control, providing a way to store page-specific information that should not be visible to users but needs to be available during processing.
44

5-
- `Value` the value of the hidden field component.
6-
- `OnValueChanged` Occurs when the value of the HiddenField component changes between posts to the server.
5+
Original Microsoft documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.hiddenfield?view=netframework-4.8
76

8-
## WebForms Syntax
7+
## Features Supported in Blazor
8+
9+
- **Value** - The value stored in the hidden field
10+
- **OnValueChanged** - Event that fires when the value changes
11+
- **ID** - Renders as the HTML `id` attribute
12+
13+
### Blazor Notes
14+
15+
In Blazor, the HiddenField is useful for:
16+
17+
- Storing values that need to be accessible via JavaScript interop
18+
- Maintaining compatibility with migrated Web Forms markup
19+
- Storing temporary data that shouldn't be visible to users
20+
21+
Unlike Web Forms, Blazor maintains component state automatically, so you may not need HiddenField as frequently. Consider using component fields or cascading parameters for state management in pure Blazor applications.
22+
23+
## Web Forms Features NOT Supported
24+
25+
- **EnableTheming** - Blazor uses CSS for styling
26+
- **EnableViewState** - Blazor handles state differently; use component state instead
27+
- **SkinID** - Themes/skins not supported; use CSS classes
28+
- **OnDataBinding, OnDisposed, OnInit, OnLoad, OnPreRender, OnUnload** - Blazor component lifecycle is different; use Blazor lifecycle methods (`OnInitialized`, `OnParametersSet`, etc.)
29+
- **Visible** - Not applicable; use conditional rendering with `@if` instead
30+
31+
## Web Forms Declarative Syntax
932

1033
```html
1134
<asp:HiddenField
@@ -25,3 +48,64 @@ The HiddenField component is meant to emulate the asp:HiddenField control in mar
2548
Visible="True|False"
2649
/>
2750
```
51+
52+
## Blazor Razor Syntax
53+
54+
### Basic Usage
55+
56+
```razor
57+
<HiddenField ID="myHiddenField" Value="@secretValue" />
58+
59+
@code {
60+
private string secretValue = "stored-data-123";
61+
}
62+
```
63+
64+
### With Value Changed Event
65+
66+
```razor
67+
<HiddenField ID="trackingField"
68+
Value="@trackingId"
69+
OnValueChanged="HandleValueChanged" />
70+
71+
@code {
72+
private string trackingId = "initial-value";
73+
74+
private void HandleValueChanged(EventArgs e)
75+
{
76+
// Handle the value change
77+
Console.WriteLine("Hidden field value changed");
78+
}
79+
}
80+
```
81+
82+
## HTML Output
83+
84+
**Blazor Input:**
85+
```razor
86+
<HiddenField ID="myHidden" Value="secret123" />
87+
```
88+
89+
**Rendered HTML:**
90+
```html
91+
<input id="myHidden" type="hidden" value="secret123" />
92+
```
93+
94+
## Migration Notes
95+
96+
When migrating from Web Forms to Blazor:
97+
98+
1. **Remove `runat="server"`** - Not needed in Blazor
99+
2. **Remove `EnableViewState` and `EnableTheming`** - Not applicable in Blazor
100+
3. **Replace lifecycle events** - Use Blazor lifecycle methods instead
101+
4. **Consider alternatives** - For pure Blazor apps, you may not need HiddenField; use component state or `@bind` instead
102+
5. **JavaScript interop** - HiddenField is still useful when you need to exchange values with JavaScript
103+
104+
!!! tip "Best Practice"
105+
In new Blazor development, prefer using component fields and parameters over hidden fields. Only use HiddenField when migrating existing markup or when JavaScript interop requires a DOM element to read/write values.
106+
107+
## See Also
108+
109+
- [TextBox](TextBox.md) - For visible text input
110+
- [ViewState](../UtilityFeatures/ViewState.md) - State management options
111+
- [JavaScript Setup](../UtilityFeatures/JavaScriptSetup.md) - JavaScript interop guidance

0 commit comments

Comments
 (0)