Add documentation for HyperLink and Menu components; update navigatio…

README.md

@@ -32,7 +32,6 @@ There are a significant number of controls in ASP.NET Web Forms, and we will foc
     - [DropDownList](docs/EditorControls/DropDownList.md)
     - FileUpload
     - [HiddenField](docs/EditorControls/HiddenField.md)
-    - [HyperLink](docs/EditorControls/HyperLink.md)
     - [Image](docs/EditorControls/Image.md)
     - [ImageButton](docs/EditorControls/ImageButton.md)
     - ImageMap
@@ -69,7 +68,8 @@ There are a significant number of controls in ASP.NET Web Forms, and we will foc
     - [RequiredFieldValidator](docs/ValidationControls/RequiredFieldValidator.md)
     - [ValidationSummary](docs/ValidationControls/ValidationSummary.md)
   - Navigation Controls
-    - [Menu](docs/Menu.md)
+    - [HyperLink](docs/NavigationControls/HyperLink.md)
+    - [Menu](docs/NavigationControls/Menu.md)
     - SiteMapPath
     - [TreeView](docs/NavigationControls/TreeView.md)
   - Login Controls

docs/EditorControls/Button.md

@@ -1,19 +1,37 @@
-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
+# Button
 
-## Blazor Features Supported
+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.
 
-- OnClick event handler
-- OnClientClick JavaScript pointer
-- OnCommand event handler with event bubbling
-- Button Style attributes and CssClass formatting
-- CausesValidation will control whether  Form validation is triggered on click
+Original Microsoft documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.button?view=netframework-4.8
 
-## WebForms Features Not Supported
+## Features Supported in Blazor
 
-- PostBackUrl is not supported as you will be triggering Button click events on the same page
-- UseSubmitBehavior is not supported as Blazor buttons trigger click events and you can inspect the Form regardless
+- `Text` - the text displayed on the button
+- `OnClick` - event handler triggered when button is clicked
+- `OnClientClick` - JavaScript code to execute on client-side click
+- `OnCommand` - event handler with event bubbling, receives `CommandEventArgs` with `CommandName` and `CommandArgument`
+- `CommandName` - the command name passed to `OnCommand` event
+- `CommandArgument` - the command argument passed to `OnCommand` event
+- `CausesValidation` - controls whether form validation is triggered on click (default: `true`)
+- `Enabled` - enables or disables the button
+- `Visible` - controls button visibility
+- `ToolTip` - tooltip text displayed on hover
+- All style properties (`BackColor`, `ForeColor`, `BorderColor`, `BorderStyle`, `BorderWidth`, `CssClass`, `Width`, `Height`, `Font`)
 
-## WebForms Syntax
+### Blazor Notes
+
+- The `OnCommand` event uses a `CommandEventArgs` class that contains `CommandName` and `CommandArgument` properties
+- When `CommandName` is set, clicking the button triggers `OnCommand` instead of `OnClick`
+- Event bubbling is supported for container components that need to handle commands from child buttons
+
+## Web Forms Features NOT Supported
+
+- **PostBackUrl** - Not supported; Blazor uses component events instead of postbacks to different pages
+- **UseSubmitBehavior** - Not supported; Blazor buttons trigger click events and you can inspect the form regardless
+- **ValidationGroup** - Not yet implemented; use EditForm validation instead
+- **AccessKey** - Use HTML `accesskey` attribute directly if needed
+
+## Web Forms Declarative Syntax
 
 ```html
 <asp:Button
@@ -63,3 +81,200 @@ It may seem strange that we have a Button component when there already is an HTM
     Width="size"
 />
 ```
+
+## Blazor Razor Syntax
+
+### Basic Button with Click Event
+
+```razor
+<Button Text="Click Me" OnClick="HandleClick" />
+
+@code {
+    void HandleClick()
+    {
+        // Handle the click
+    }
+}
+```
+
+### Button with Command
+
+```razor
+<Button Text="Save" 
+        CommandName="Save" 
+        CommandArgument="@itemId" 
+        OnCommand="HandleCommand" />
+
+@code {
+    private string itemId = "123";
+
+    void HandleCommand(CommandEventArgs args)
+    {
+        var command = args.CommandName;    // "Save"
+        var argument = args.CommandArgument; // "123"
+    }
+}
+```
+
+### Button with JavaScript Click
+
+```razor
+<Button Text="Alert" OnClientClick="alert('Hello World!')" />
+```
+
+### Styled Button
+
+```razor
+<Button Text="Styled Button"
+        BackColor="WebColor.Blue"
+        ForeColor="WebColor.White"
+        Font_Bold="true"
+        CssClass="my-button-class" />
+```
+
+### Disabled Button
+
+```razor
+<Button Text="Cannot Click" Enabled="false" />
+```
+
+### Button with Validation Control
+
+```razor
+<EditForm Model="@model" OnValidSubmit="HandleSubmit">
+    <TextBox @bind-Text="model.Name" />
+    <RequiredFieldValidator ControlToValidate="..." Text="Required" />
+
+    @* This button triggers validation *@
+    <Button Text="Submit" CausesValidation="true" />
+
+    @* This button skips validation *@
+    <Button Text="Cancel" CausesValidation="false" OnClick="HandleCancel" />
+</EditForm>
+```
+
+## HTML Output
+
+**Web Forms Input:**
+```html
+<asp:Button ID="btnSubmit" Text="Submit" CssClass="btn" runat="server" />
+```
+
+**Rendered HTML:**
+```html
+<button type="submit" class="btn">Submit</button>
+```
+
+**Styled Button Input:**
+```razor
+<Button Text="Styled" BackColor="WebColor.Blue" ForeColor="WebColor.White" />
+```
+
+**Rendered HTML:**
+```html
+<button type="submit" style="background-color:Blue;color:White;">Styled</button>
+```
+
+## Migration Notes
+
+When migrating from Web Forms to Blazor:
+
+1. **Remove `asp:` prefix** - Change `<asp:Button>` to `<Button>`
+2. **Remove `runat="server"`** - Not needed in Blazor
+3. **Remove `ID` attribute** - Use `@ref` if you need a reference to the component
+4. **Update event handler syntax** - Change `OnClick="btnSubmit_Click"` to `OnClick="HandleClick"`
+5. **Replace `PostBackUrl`** - Use navigation or component state instead
+6. **Update `OnCommand` handlers** - The signature changes from `(object sender, CommandEventArgs e)` to `(CommandEventArgs args)`
+
+### Before (Web Forms)
+
+```html
+<asp:Button ID="btnSave" 
+            Text="Save" 
+            OnClick="btnSave_Click" 
+            CssClass="btn btn-primary"
+            runat="server" />
+```
+
+```csharp
+protected void btnSave_Click(object sender, EventArgs e)
+{
+    // Handle click
+}
+```
+
+### After (Blazor)
+
+```razor
+<Button Text="Save" 
+        OnClick="HandleSave" 
+        CssClass="btn btn-primary" />
+
+@code {
+    void HandleSave()
+    {
+        // Handle click
+    }
+}
+```
+
+## Examples
+
+### Basic Click Handler
+
+```razor
+<Button Text="Click Me!" OnClick="OnClick" />
+
+<span style="font-weight: bold">@message</span>
+
+@code {
+    private string message = "Not clicked yet!";
+
+    void OnClick()
+    {
+        message = "I've been clicked!";
+    }
+}
+```
+
+### Command Pattern with Multiple Buttons
+
+```razor
+<Button Text="Edit" CommandName="Edit" CommandArgument="@item.Id" OnCommand="HandleCommand" />
+<Button Text="Delete" CommandName="Delete" CommandArgument="@item.Id" OnCommand="HandleCommand" />
+
+<p>Last action: @lastAction</p>
+
+@code {
+    private string lastAction = "None";
+
+    void HandleCommand(CommandEventArgs args)
+    {
+        lastAction = $"Command '{args.CommandName}' on item {args.CommandArgument}";
+    }
+}
+```
+
+### Styled Buttons
+
+```razor
+@using static BlazorWebFormsComponents.WebColor
+
+<Button Text="Blue Button" BackColor="Blue" ForeColor="White" />
+<Button Text="Red Bold Button" BackColor="Red" ForeColor="Yellow" Font_Bold="true" />
+<Button Text="Custom Class" CssClass="rounded-corners" />
+```
+
+### JavaScript Integration
+
+```razor
+<Button Text="Show Alert" OnClientClick="alert('Hello from JavaScript!')" />
+<Button Text="Confirm" OnClientClick="return confirm('Are you sure?')" OnClick="HandleConfirmed" />
+```
+
+## See Also
+
+- [LinkButton](LinkButton.md) - A button that renders as a hyperlink
+- [ImageButton](ImageButton.md) - A button that displays an image
+- [RequiredFieldValidator](../ValidationControls/RequiredFieldValidator.md) - Validate required fields
+- [Live Demo](https://blazorwebformscomponents.azurewebsites.net/ControlSamples/Button) - Interactive Button samples

docs/EditorControls/HiddenField.md

@@ -1,11 +1,34 @@
-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)
+# HiddenField
 
-## Blazor Features Supported
+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.
 
-- `Value` the value of the hidden field component.
-- `OnValueChanged` Occurs when the value of the HiddenField component changes between posts to the server.
+Original Microsoft documentation: https://docs.microsoft.com/en-us/dotnet/api/system.web.ui.webcontrols.hiddenfield?view=netframework-4.8
 
-## WebForms Syntax
+## Features Supported in Blazor
+
+- **Value** - The value stored in the hidden field
+- **OnValueChanged** - Event that fires when the value changes
+- **ID** - Renders as the HTML `id` attribute
+
+### Blazor Notes
+
+In Blazor, the HiddenField is useful for:
+
+- Storing values that need to be accessible via JavaScript interop
+- Maintaining compatibility with migrated Web Forms markup
+- Storing temporary data that shouldn't be visible to users
+
+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.
+
+## Web Forms Features NOT Supported
+
+- **EnableTheming** - Blazor uses CSS for styling
+- **EnableViewState** - Blazor handles state differently; use component state instead
+- **SkinID** - Themes/skins not supported; use CSS classes
+- **OnDataBinding, OnDisposed, OnInit, OnLoad, OnPreRender, OnUnload** - Blazor component lifecycle is different; use Blazor lifecycle methods (`OnInitialized`, `OnParametersSet`, etc.)
+- **Visible** - Not applicable; use conditional rendering with `@if` instead
+
+## Web Forms Declarative Syntax
 
 ```html
 <asp:HiddenField
@@ -25,3 +48,64 @@ The HiddenField component is meant to emulate the asp:HiddenField control in mar
     Visible="True|False"
 />
 ```
+
+## Blazor Razor Syntax
+
+### Basic Usage
+
+```razor
+<HiddenField ID="myHiddenField" Value="@secretValue" />
+
+@code {
+    private string secretValue = "stored-data-123";
+}
+```
+
+### With Value Changed Event
+
+```razor
+<HiddenField ID="trackingField" 
+             Value="@trackingId" 
+             OnValueChanged="HandleValueChanged" />
+
+@code {
+    private string trackingId = "initial-value";
+
+    private void HandleValueChanged(EventArgs e)
+    {
+        // Handle the value change
+        Console.WriteLine("Hidden field value changed");
+    }
+}
+```
+
+## HTML Output
+
+**Blazor Input:**
+```razor
+<HiddenField ID="myHidden" Value="secret123" />
+```
+
+**Rendered HTML:**
+```html
+<input id="myHidden" type="hidden" value="secret123" />
+```
+
+## Migration Notes
+
+When migrating from Web Forms to Blazor:
+
+1. **Remove `runat="server"`** - Not needed in Blazor
+2. **Remove `EnableViewState` and `EnableTheming`** - Not applicable in Blazor
+3. **Replace lifecycle events** - Use Blazor lifecycle methods instead
+4. **Consider alternatives** - For pure Blazor apps, you may not need HiddenField; use component state or `@bind` instead
+5. **JavaScript interop** - HiddenField is still useful when you need to exchange values with JavaScript
+
+!!! tip "Best Practice"
+    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.
+
+## See Also
+
+- [TextBox](TextBox.md) - For visible text input
+- [ViewState](../UtilityFeatures/ViewState.md) - State management options
+- [JavaScript Setup](../UtilityFeatures/JavaScriptSetup.md) - JavaScript interop guidance